Hermes Agent Memory: MEMORY.md, USER.md and Providers

Hermes Agent memory is two small, agent-curated files plus a searchable history. MEMORY.md (2,200 characters) holds the agent’s own notes and USER.md (1,375 characters) holds your profile. Both load into the system prompt at session start. Older conversations live in SQLite and are searched on demand. One optional external provider can add more.

Hermes Agent is an open-source (MIT) agent from Nous Research that runs in a terminal or through messaging apps and creates reusable skills from its own experience. This page covers each layer of its memory, the external providers, and what to check when memory seems broken. Details come from the official Hermes memory docs, checked October 2026.

What is Hermes Agent memory?

Hermes Agent memory is a bounded, curated store that persists across sessions. The agent decides what to save, writes short entries into MEMORY.md and USER.md through a memory tool, and Hermes injects both files into the system prompt as a frozen block when each session starts.

The design is small on purpose. Together the two files are about 1,300 tokens, always in context. Everything else (full transcripts, old tasks) stays out of the prompt until the agent searches for it. That split between always-loaded memory and on-demand recall is the same one described in AI agent memory explained.

The layers of Hermes memory

With profiles, the files sit under ~/.hermes/profiles/<name>/memories/ instead.

MEMORY.md and USER.md

MEMORY.md is for the agent’s working knowledge: environment facts, project conventions, tool quirks and techniques that worked. USER.md is for you: name, role, timezone, communication style, pet peeves and technical level. The docs say to skip trivial facts, things that are easy to look up again, raw data dumps, and anything already in SOUL.md or AGENTS.md.

Entries are separated by §. The injected block has a header showing usage (for example 67%, 1,474 of 2,200 characters), so the model knows how full the store is.

The memory tool

The agent edits memory with one tool and three actions:

1. add: append a new entry.
2. replace: find an entry by a unique substring (old_text) and overwrite it.
3. remove: delete the entry matching old_text.

There’s no read action, since the content is already in the prompt. Exact duplicates are rejected. When a write would go over the limit, the tool returns an error with the current entries, and the agent must send one batch of operations that frees space and adds the new entry. Hermes never compacts memory on its own. The docs suggest consolidating once usage passes 80%.

Every entry is scanned for prompt injection, credential exfiltration, SSH backdoors and invisible Unicode before it’s saved. That matters because memory is a known attack surface; see AI memory injection.

Session search

Past CLI and messaging sessions are stored in ~/.hermes/state.db. The session_search tool runs full-text search (SQLite FTS5) over them and returns raw messages, and the agent can scroll through a found session. hermes sessions list shows them from the CLI. This is Hermes’s answer to “what did we do last month”: not stored in memory, but findable.

Background review and write approval

After a conversation, a background review can update memory and skills. It’s on by default (auxiliary.background_review.enabled), uses the main model unless you set another, and caps input at 75% of the model’s context window (up to 600,000 tokens). If you want to approve writes, set memory.write_approval: true; staged writes then appear under /memory pending and can be approved or rejected.

Configuring Hermes memory

Settings live in ~/.hermes/config.yaml:

1memory:
2  memory_enabled: true
3  user_profile_enabled: true
4  memory_char_limit: 2200
5  user_char_limit: 1375
6  write_approval: false
7  # provider: honcho   # optional external provider

Turning off both memory_enabled and user_profile_enabled removes the memory tool entirely. You can raise the character limits, but every character is paid for on every turn, so bigger isn’t free.

The /journey command (also hermes journey) shows a timeline of skills and memory entries, and hermes journey delete <node> removes one.

External memory providers

Hermes can run one external provider at a time next to the built-in files. When one is active, Hermes prefetches relevant memories before each turn, syncs turns after each response, extracts memories at session end where supported, and mirrors built-in memory writes to it. The memory providers page lists nine as of October 2026:

Providers are moving out of the Hermes tree into their maintainers’ own repositories. Holographic used to ship in-tree; it’s now maintained by itpartypattaya (itpartypattaya/hermes-plugin-holographic) and installs from the plugin catalog with the same name, settings and database. RetainDB and ByteRover leave core on October 15, 2026, and the docs say their standalone repositories are “unmaintained and open for a new maintainer”, with no catalog install command listed. Honcho, OpenViking, Mem0, Hindsight, Holographic and Supermemory install with hermes plugins install <name>; Memori uses its own hermes-memori CLI. Holographic uses holographic reduced representations, explained in holographic memory for AI agents, and Honcho has its own page on Honcho LLM memory.

Setup is the same for each:

1hermes plugins install honcho   # or mem0, hindsight, supermemory, openviking
2hermes memory setup             # interactive picker and credentials
3hermes memory status            # confirm which provider is active
4hermes memory off               # disable the external provider

Best memory provider for Hermes Agent

There’s no single best one; it depends on what the agent must remember. Pick Honcho if modeling the user is the point, Mem0 or Supermemory for a hosted fact store with little setup, Hindsight if you want memories consolidated into evidence-backed observations plus a reflect call, and Holographic (or Hindsight’s embedded Postgres) if nothing may leave the machine. Avoid starting new setups on RetainDB or ByteRover until someone maintains them again. If the built-in files already hold what you need, skip providers entirely; they add LLM calls and a dependency.

Of the nine, Hindsight and Mem0 are the two with published head-to-head numbers. On Mem0’s own comparison page they tie on LongMemEval (94.6 vs 94.4) and LoCoMo (92 vs 92.5), and Hindsight leads on the long-history BEAM test: 73.9 vs 64.1 at 1M tokens and 64.1 vs 48.6 at 10M (all vendor-run). That matters for a Hermes agent that runs for months. Hindsight is MIT with every feature in the self-hosted server, and it can use local models through Ollama, LM Studio or llama.cpp, so it also works when nothing may leave the machine. The trade-off: it returns more context per turn than Mem0 (24K-44K vs under 7K tokens by Mem0’s measurement), which Hermes then prefetches into every turn, so lower its max_tokens budget. Details in Mem0 vs Hindsight.

Hermes memory not working: what to check

Most “Hermes forgot” reports come from a handful of causes:

1. The snapshot is frozen. Writes save to disk at once but show up in the prompt only next session. Run /new to reload. Messaging gateways (Telegram, Discord) are one long session until you reset them.
2. The store is full. At 2,200 or 1,375 characters, new adds fail until the agent consolidates. Check usage in the header or open the files.
3. Memory is disabled. Confirm memory_enabled and user_profile_enabled in config.yaml, and that memory isn’t listed under agent.disabled_toolsets.
4. Writes are staged. With write_approval: true, nothing lands until you approve it under /memory pending.
5. Wrong profile. Each profile has its own memory directory.
6. The detail was never memory. Long task history belongs in session search, so ask the agent to search past sessions.
7. Provider problems. Run hermes memory status. Only one provider can be active, and cloud providers need their credentials (RetainDB, for example, reads RETAINDB_API_KEY from ~/.hermes/.env).

Hermes compared with other agents

Hermes’s built-in memory is closest to OpenClaw’s markdown files and Claude Code’s auto memory: plain text, small, loaded at start. It differs in the hard character caps and the frozen snapshot. Hermes can also import from OpenClaw with hermes claw migrate, which carries over SOUL.md, memories, skills and AGENTS.md. For a side-by-side, see OpenClaw vs Hermes Agent memory.