Hermes Agent

Feature

Hermes Agent Persistent Memory: Facts, History, and Recall

Quick answer

Hermes Agent persistent memory stores compact facts in MEMORY.md and preferences in USER.md, then loads a frozen snapshot at session start. It is not unlimited recall. A real save requires a successful memory tool call and any required approval. Verify the entry in the same profile, then test it in a fresh session. Use session search for old conversations; add an external provider only for a specific retrieval need.

Key Points

  • ✓Built-in memory needs no external memory service: MEMORY.md holds durable facts; USER.md holds preferences.
  • ✓Bounded notes: 2,200 characters in MEMORY.md and 1,375 in USER.md. Over-limit writes fail rather than silently evicting facts.
  • ✓A chat confirmation is not a persistence receipt: check the memory tool result and the stored entry.
  • ✓With write approval enabled, interactive CLI foreground saves prompt inline; messaging, scripts, and background review stage writes for review.
  • ✓A new session loads the latest approved notes. A gateway restart may resume the old conversation instead.
  • ✓Profiles isolate memory. Two agents should not write to the same Hermes home; use separate profiles.
  • ✓SQLite session history and FTS5 search preserve and retrieve conversations separately from compact memory.

How It Works

  1. 1Choose the owning profile and save one non-secret fact with the memory tool.
  2. 2Check the tool result; if approval is enabled, approve the intended change inline or review its pending entry on the relevant surface.
  3. 3Verify the entry in that profile’s MEMORY.md or USER.md before testing recall.
  4. 4Finish the current task, save any handoff, and start a fresh session in the same profile. Ask for the fact without repeating its value.

Real-World Use Cases

Project Context Retention

Save a small set of stable stack choices or conventions, verify the entries, and load them in a fresh session. Keep detailed repository rules in project context files rather than filling the memory budget.

Preference Learning

Store a stable preference such as concise answers in USER.md after a successful tool write and any approval. Verify it in a fresh session instead of assuming a spoken confirmation saved it.

Cross-Session Task Continuity

Pick up mid-task days later by resuming the named session or using FTS5 session search. Promote only reusable lessons from that history into durable memory.

Team Environment Documentation

Store non-secret team conventions and stable preferences in profile-scoped memory. Keep credentials in .env or a secret manager, and use separate profiles when teams or bots need isolation.

Session Recovery Without Memory Bloat

Use `hermes sessions stats` and FTS5 session search to recover historical task details. Keep MEMORY.md for compact reusable facts instead of copying entire transcripts into every prompt.

Under the Hood

Hermes separates the active conversation, durable memory, and session history. MEMORY.md and USER.md live in the active Hermes home’s memories directory. Their prompt snapshot is frozen at session start; a mid-session save changes disk state, not the already-injected block. The live tool response can still show the change.

A messaging conversation can survive a gateway restart or machine reboot. Restarting the process does not necessarily create a new memory snapshot. At a natural task boundary, save a handoff and use /new for an independent recall check. Do not reset an unfinished task merely to test memory.

When memory.write_approval is true, interactive CLI foreground writes ask for approval inline. Messaging, script, and background-review writes are staged for /memory pending. Inspect the proposed change and approve only the intended entry. A pending save is not durable memory yet.

Memory tool actions are add, patch, and remove. A patch changes only the selected span, preserving the rest of the entry. If the result exceeds the character budget, consolidate or remove stale material and retry; increasing a model’s context window does not enlarge these note files.

Full conversation history belongs in the SQLite session store, queried through session_search. External memory providers are optional additions for semantic retrieval or other specific needs, not repairs for a save that never happened. Keep credentials out of memory and separate agent profiles before considering shared external retrieval.

Self-hosted users own runtime, credentials, storage, and backup operations. Managed hosting changes who maintains that environment; it does not guarantee model tool calls, unlimited memory, or correct recall. This site promotes FlyHermes; compare managed operation only if maintenance is the problem you want to offload.

Frequently asked questions

Why does Hermes Agent not remember something I told it?

First check whether the model called the memory tool, whether the write succeeded or is pending approval, and whether the entry exists in the intended profile. Then start a fresh session in that same profile. A chat confirmation or gateway restart alone does not prove persistence or a reloaded snapshot.

Does Hermes Agent memory cause repeated tool-call loops?

Not by default. Use `/context`, `/model`, and `/tools list`, then replay one tiny task in a fresh session and alternate model route before editing MEMORY.md or disabling memory.

Does Hermes silently delete old memories when the store is full?

No. Over-capacity add or lengthening patch operations return an error. Consolidate stale entries and retry; do not confuse the durable-note budget with the model context window.

Does managed hosting give Hermes unlimited memory?

No. Managed operation changes runtime maintenance ownership. Built-in memory remains bounded, and correct recall still depends on a successful save, approval where enabled, the right profile, and the session snapshot.

Sources

Next setup steps

Related Features