Vol. I · Field Notes

NousResearchhermes-agent

The self-improving AI agent — creates skills from experience, improves them during use, and runs anywhere

9 May 2026·a vast project
Reading Posture
From the Field
Over-engineered Swiss Army knife that tries to do everything, masters nothing.
Verdict:Pass
Reach for it when

You want a single codebase to experiment with every possible agent pattern and platform integration.

Look elsewhere when

You need a focused, production-ready agent that does one thing well without 300K LOC of bloat.

In context

It's like AutoGPT but with 10x the complexity and half the polish — a research playground, not a tool.

Complexity●●●Heavy
Read time~30 minutes
Language
JavaScript
Runtime
Python >=3.11
Dependencies
2total
Notable Dependencies
@askjo/camofox-browseragent-browser

What using it looks like

Drawn from the project's README

From the README
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Fig. 1 — example 1 of 6

What this is

As told for the tourist

# What Is This?

Hermes Agent is a personal AI assistant that actually learns from your conversations and gets better over time. Think of it like having a really smart intern who takes notes, remembers what you taught them, and starts doing tasks on their own without you having to explain everything from scratch each time.

# What Can You Do With It?

You could use this to have an AI assistant that lives on a cheap cloud server (like $5/month) and talks to you through Telegram while you're on your phone, then switches to your computer terminal when you're at your desk. It remembers who you are across all these different places.

Here's what it looks like in practice:

hermes # Start chatting right in your terminal

hermes model # Switch between different AI brains (OpenAI, open-source models, etc.)

hermes gateway # Connect it to Telegram, Discord, or Slack

You could ask it to research a topic, write code, or help plan a project. After it finishes something complex, it might create a new "skill" — like a recipe it can reuse next time you ask something similar. Over time, it builds a better picture of how you like things done.

# How It Works (No Jargon)

1. Memory like a personal notebook. Instead of forgetting everything after each conversation (like most AI assistants), Hermes keeps notes. It's like having a friend who writes down important things you say and flips back through their notebook when you mention something from last week.

2. Skills like cooking recipes. When you teach it to do something complicated — say, "analyze this spreadsheet and email me the summary" — it writes down the steps as a reusable skill. Next time, it doesn't need you to explain the whole process again. It just follows the recipe.

3. Runs anywhere like a portable toolbox. Most AI assistants are stuck on your laptop or in a specific app. Hermes is designed to run on a cheap cloud computer, your gaming PC, or even a tiny server that costs pennies when you're not using it. You talk to it through whatever app you prefer — Telegram, Discord, or just your terminal.

# What's Cool About It?

The learning loop is the real magic. Most AI assistants are like vending machines — you put in a question, get an answer, and that's it. Hermes is more like a curious apprentice. It nudges itself to save important information, creates new skills when it notices patterns, and actually improves the skills it already has while using them. It's one of the few AI tools that gets smarter the more you use it, without you having to do any extra work.

Also cool: you're not locked into one AI company. You can swap between different AI brains (OpenAI, open-source models, whatever) with a single command. No code changes, no vendor lock-in.

# Who Should Care?

Reach for this if: You want an AI assistant that actually remembers you, learns your preferences, and works across all your devices. If you're a developer who wants to experiment with self-improving AI, or just someone who's tired of starting from scratch with every new AI chat.

Skip it if: You just want a simple chatbot for quick questions and don't care about memory or learning. Or if you're not comfortable running software on a server — this isn't a click-and-forget app, it's a tool you set up and customize.

hermes              # Start chatting right in your terminal
hermes model        # Switch between different AI brains (OpenAI, open-source models, etc.)
hermes gateway      # Connect it to Telegram, Discord, or Slack

Start Here

A recommended reading path through the code

Start Here

A recommended reading path through the code

  1. 01
    hermes_constants.py(Core & Misc)

    Defines the foundational constants and home directory resolution used across the entire codebase.

  2. 02

    Serves as the single source of truth for provider identity, revealing how external tools are integrated.

  3. 03

    Implements the core process management lifecycle, showing how services are started, stopped, and monitored.

  4. 04

    Exemplifies the plugin architecture with a concrete, feature-rich provider implementation.

  5. 05

    Demonstrates the scheduling and automation layer that ties together agents and gateway processes.

What's inside

123 sections of the codebase

Read Next

Where to go from here

📰
Article2024

What is an AI Agent? A Beginner's Guide

IBM Think Blog

Explains the core concept of autonomous AI agents in plain English, setting the stage for understanding what Hermes tries to do.

📺
Video2023

AutoGPT Explained in 5 Minutes

Fireship

Quick visual primer on the AutoGPT-style agent that Hermes is compared to, highlighting the complexity trade-offs.

📰
Article2024

The Rise of Self-Improving AI Agents

Simon Willison

Accessible overview of how agents learn from experience, directly relevant to Hermes' skill lifecycle concept.

📰
Article2024

What is a Tool-Using AI Agent?

Anthropic Blog

Explains the tool registry pattern in simple terms, mirroring Hermes' core abstraction for plugin capabilities.

Sibling Projects

Codebases that occupy adjacent space

Related Expeditions
hermes-agent🤖AutoGPT🔗LangChain📘OpenAI Cookbook🧩Semantic Kernel👥crewAI
 

Export & Share

Take the field notes with you

Words You'll Hear

Hover the dotted terms above for definitions in context

ABC (Abstract Base Class)

concept

A blueprint for other classes that defines what methods they must have, but doesn't provide the actual code for those methods.

argparse

library

A Python library that helps programs understand and process command-line arguments, like when you type '--help' or '--verbose' in a terminal.

AST analysis

concept

A way for the program to read and understand its own source code structure at startup, like a robot reading its own blueprints to find all the tools it has.

Composite Pattern

pattern

A design pattern that lets you treat individual objects and groups of objects the same way, like handling a single file and a whole folder of files with the same command.

Cooldown timer

concept

A waiting period that prevents a service from being used again too quickly after it fails, giving it time to recover.

Dependency injection

pattern

A technique where a program receives its dependencies (like a database connection) from the outside instead of creating them itself, making it easier to test and change.

Event bus

pattern

A central message board where different parts of the program post updates and listen for updates from others, allowing them to communicate without being directly connected.

Factory Pattern

pattern

A design pattern that creates objects without specifying the exact class of object that will be created, like a vending machine that gives you a drink without you knowing how it was made.

Failover strategy

pattern

A backup plan for when a service fails, like automatically switching to a different API key or server if the first one stops working.

FTS5

tool

A search engine built into SQLite that lets you quickly find past conversations by typing keywords, like a super-fast search bar for your chat history.

Gateway adapter

pattern

A translator that converts messages from different chat apps (like Telegram or Discord) into a single format the AI can understand, so it doesn't need to learn each app's language.

Hexagonal architecture

pattern

A design pattern that isolates the core logic of a program from outside systems (like databases or user interfaces) using adapters, making it easier to change parts.

JSON-RPC

pattern

A simple way for different programs to send commands to each other over the internet or a local connection, using a format similar to a text message.

Knowledge graph

concept

A database that stores information as a network of connected facts, like a map where people, places, and things are dots connected by lines showing their relationships.

Layered monolith

pattern

A single large program organized into stacked layers (like a cake), where each layer has a specific job, but the whole thing runs as one piece.

Lazy loading

pattern

A technique where a program delays loading a part of itself until it is actually needed, which makes the program start up faster.

MCP (Model Context Protocol)

concept

A standard way for AI models to connect to external tools and data sources, like a universal plug for different devices.

OAuth flow

concept

A secure way for a program to get permission to access your data on another service (like Google) without needing your password.

Observer Pattern

pattern

A design pattern where one object (the subject) notifies a list of other objects (observers) when its state changes, like a news channel broadcasting to all its subscribers.

Playwright

tool

A tool that lets a program control a web browser automatically, like a robot that can click buttons, fill forms, and take screenshots on a website.

ReAct pattern

pattern

A method where an AI alternates between thinking (Reasoning) and taking actions (Acting) to solve a problem, like a person who thinks, then does something, then thinks again.

Serialization boundary

concept

The point where data is converted from one format to another (like from a chat message to a special AI format), which is a common place for errors or slowdowns.

SQLite with WAL mode

tool

A small, file-based database that uses Write-Ahead Logging to allow multiple parts of the program to read and write data at the same time without crashing.

State Machine

concept

A model of behavior that can only be in one of a limited number of states at a time, and changes between states based on inputs, like a traffic light that can only be red, yellow, or green.

Strategy Pattern

pattern

A design pattern that lets you swap out different algorithms or behaviors at runtime, like choosing between driving, walking, or biking to a destination.

NousResearch/hermes-agent · Archaeologist