Hermes Agent: How a Self-Improving AI Agent Remembers What It Learns

Banner from the Hermes Agent repository (MIT License, © Nous Research).

Most AI agents start every session from zero. You explain your environment, your conventions and your preferences, the agent does the work, and the next day you explain it all again. Hermes Agent from Nous Research is built around fixing that. It is an open-source (MIT), self-hosted agent that writes down how it solved a problem, keeps a small curated memory about you and your setup, and can search its own past conversations.

This post walks through how those pieces actually work, based on the project’s documentation as of v0.14.0 (released May 16, 2026), and what to lock down before handing it a terminal.

What it is

Hermes Agent is a Python application you install and run yourself. It is not tied to a single model: it works with Nous Portal, OpenRouter, OpenAI, a long list of other hosted providers, or your own OpenAI-compatible endpoint, and you switch between them with hermes model. The one hard requirement is a model with at least 64,000 tokens of context. Hermes rejects smaller windows at startup because multi-step tool use needs the room.

You can talk to it in two ways: a terminal interface (hermes, or hermes --tui for the newer full-screen UI) or a messaging gateway that connects it to chat apps. Many slash commands work in both, and a conversation can continue across platforms.

The learning loop: skills as procedural memory

The headline idea is that the agent turns finished work into reusable instructions. Hermes calls these skills. A skill is a folder under ~/.hermes/skills/ containing a SKILL.md file (YAML frontmatter plus written steps) and optional reference files, templates and scripts. The format follows the agentskills.io open standard, so skills are not locked to Hermes.

Diagram of the Hermes skill loop: do the work, save a skill, index it, reuse it, patch it

The loop works like this:

Do the work. The docs list when the agent creates a skill: after successfully finishing a complex task (five or more tool calls), after hitting dead ends and finding the path that works, when you correct its approach, or when it works out a non-trivial workflow.
Save the how. It writes a skill with its skill_manage tool. The docs describe this as procedural memory: the lesson and the steps, not a log of what happened.
Index it. Only each skill’s name, description and category go into the prompt. The whole index costs roughly 3,000 tokens.
Reuse it. When a similar task comes up, the agent calls skill_view(name) to load the full instructions, and can pull individual reference files on top of that. Hermes calls this progressive disclosure: you pay for a skill’s tokens only when it is used.
Fix it in use. If a skill turns out to be wrong or out of date, the agent edits it. The preferred action is patch, a targeted find-and-replace, because only the changed text has to go through the model.

Skills also become slash commands. A skill named plan is available as /plan, and you can install community skills from the Skills Hub with hermes skills install.

The part worth thinking about: the agent can create, rewrite and delete its own skills. That is the feature, and it is also a risk. A skill that learned the wrong lesson will keep applying it. Treat ~/.hermes/skills/ like code: keep it under version control and review what changes.

Memory is deliberately small

Hermes separates “what I know how to do” (skills) from “what I know about you and this environment” (memory). Built-in memory is two plain files in ~/.hermes/memories/:

MEMORY.md holds the agent’s own notes about environment facts, project conventions and lessons learned. It is capped at 2,200 characters, about 800 tokens.
USER.md holds your preferences and communication style. It is capped at 1,375 characters, about 500 tokens.

Diagram of what Hermes keeps in the prompt versus what it loads on demand

Those limits are small on purpose. Both files are injected into the system prompt as a frozen snapshot at the start of each session. The agent can add, replace or remove entries mid-session and the change is saved to disk immediately, but it only shows up in the prompt next session. That keeps the prompt identical for the whole conversation, which preserves the model’s prompt cache. When a file is full, adding an entry returns an error, so the agent has to consolidate or remove entries to make room.

For everything that does not fit, there are two other layers:

Session search. Every CLI and messaging conversation is stored in SQLite at ~/.hermes/state.db with FTS5 full-text search. The session_search tool lets the agent look up something you discussed weeks ago without keeping it in the prompt.
External memory providers. Eight optional plugins, including Honcho and Mem0, add things like semantic search and automatic fact extraction. They run alongside the built-in files rather than replacing them. Set one up with hermes memory setup.

Not tied to your laptop

Two design choices let Hermes run somewhere other than the machine you are typing on.

The messaging gateway is a single long-running process that connects the agent to Telegram, Discord, Slack, WhatsApp, Signal, email and several other platforms. You configure it with hermes gateway setup and start it with hermes gateway start. Conversations and slash commands such as /new, /model and /stop work the same way in chat as in the terminal.

Terminal backends control where the agent’s shell commands actually run. There are seven: local, Docker, SSH, Singularity, Modal, Daytona and Vercel Sandbox. With Modal and Daytona, the agent’s environment hibernates when idle and wakes when a message arrives, so an agent you only use occasionally costs very little to keep around.

Scheduled jobs and subagents

Hermes has a built-in scheduler. You can create jobs in plain language or with cron expressions, from chat or the CLI:

hermes cron create "every 2h" "Check server status"

Jobs can load skills and deliver their results back to the chat they came from, to a file, or to another configured platform.

For bigger tasks, the delegate_task tool spawns subagents. Each child gets a fresh conversation, a restricted toolset and its own terminal session, and only its final summary returns to the parent. That keeps the parent’s context from filling up with every intermediate step. By default up to three subagents run in parallel, and delegation.max_concurrent_children raises that.

One practical tip from the docs: a subagent knows nothing about your conversation. “Fix the error” gives it nothing to go on. Pass the file, the error message and the goal explicitly.

Security: what to set before it runs unattended

An agent with a shell, chat access and a scheduler is exactly the kind of thing that needs guardrails. Hermes has a reasonable set, but several are only as good as your configuration.

Command approval. Commands Hermes detects as dangerous (recursive deletes, world-writable chmod, SQL DROP TABLE, piping curl output into a shell, and so on) go through an approval layer set by approvals.mode in ~/.hermes/config.yaml:

manual, the default, always asks you.
smart has a second model judge the risk. It auto-approves low-risk commands, denies clearly dangerous ones and asks about the rest.
off disables approvals entirely, the same as running with --yolo.

Underneath that is a hardline blocklist that no setting overrides, not even YOLO mode: rm -rf / and its variants, fork bombs, and mkfs on a mounted root device never run.

Who can talk to it. If no allowlists are configured, the gateway denies everyone. You can allow users per platform (for example TELEGRAM_ALLOWED_USERS) or approve them with DM pairing: the bot replies to a new user with an 8-character code that expires after an hour, and you approve it from the CLI. Setting GATEWAY_ALLOW_ALL_USERS=true means anyone who finds your bot can run commands on your machine. Don’t.

Isolation. On container backends the dangerous-command checks are skipped, because the container is the security boundary. That means on the local backend, the approval layer is your main protection. Hermes starts Docker containers with every Linux capability dropped except the few that package managers need, plus no-new-privileges, a 256-process limit and size-limited temp directories. For anything unattended, the docs’ own recommendations are the ones I would start with:

Set terminal.backend: docker.
Configure explicit allowlists or use DM pairing.
Run the gateway as a non-root user.

Hermes also scans project context files such as AGENTS.md and SOUL.md for prompt injection before loading them. That helps, but it doesn’t make an untrusted repository safe to point an agent at.

Getting started

The quickstart comes down to four commands:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.zshrc      # or ~/.bashrc
hermes setup         # pick a provider and model
hermes --tui         # start chatting

The installer supports Linux, macOS, WSL2 and Android via Termux, and native Windows is in early beta. As with any install script piped to a shell, read scripts/install.sh before running it. hermes --continue resumes your last session, and hermes doctor diagnoses configuration problems.

The docs’ advice for a first run is sound: get one clean conversation working before adding the gateway, cron, skills or voice.

Takeaways

Skills are the real differentiator. Saving procedures instead of transcripts, and loading them only when needed, is a sensible way to make an agent improve without bloating every prompt.
Small memory is a feature. Hard character limits force the agent to curate. Session search covers the long tail.
Review what it writes. Self-edited skills and memory are powerful and can drift. Version-control ~/.hermes/.
Configure security before convenience. Leave approvals on manual until you trust your setup, use a container backend, and never open the gateway to all users.

Full documentation lives at hermes-agent.nousresearch.com/docs, and the source is on GitHub.