Memory
9.6. Classification and Memory Management
Decision table — what should be stored and what should not
This is the core classification logic the agent applies whenever it is deciding whether something is worth remembering:
| Question | If Yes |
|---|---|
| Is this a fact or convention that should always be remembered? | → store it in MEMORY.md |
| Is this a user preference or habit? | → store it in USER.md |
| Is it easy to look up again (web search, existing docs)? | → do not store it, ignore |
| Is it relevant only to this one session (temporary path, one-off debugging context)? | → do not store it, ignore |
Five categories that should be stored (per the official docs)
User preferences (“prefers TypeScript”) go to USER.md. Environment facts (“server runs Debian 12”) go to MEMORY.md. Corrections (“do not use sudo for Docker commands”) go to MEMORY.md. Project conventions (“use tabs, 120 characters per line”) go to MEMORY.md. And explicit user requests to remember something should also be stored.
Four categories that should be ignored
Information that is too obvious or too vague, facts that are easy to look up again, bulky raw data such as large code blocks, log files, or tables that are too big for memory, and context that only matters for the current session.
The memory tool model — only three actions, no read
memory(action="add", store="memory"|"user", content="...")
memory(action="replace", store=..., old_substring="...", new_content="...")
memory(action="remove", store=..., substring="...")
There is no read action because memory is already available in the system prompt, so no separate tool is needed to read it back. replace and remove locate the target entry by a unique substring match, not by ID or sequence number. If the substring matches more than one entry, the command fails instead of guessing and editing the wrong thing.
No automatic compression — errors force the agent to clean up
This is the most important design point in all of section 9: memory is not automatically compacted. When a write would exceed the limit, the memory tool returns an error instead of silently trimming content. The agent is forced to clean up, by merging or removing older entries, in that same turn before trying again. A practical threshold is to start consolidating related entries once memory usage exceeds 80%, which is shown in the system prompt header as a percentage. For example, three separate entries saying “project uses X” should be merged into one more comprehensive project entry before adding more.
Practical lessons
- Proactively tell the agent to “clean up memory” when you see capacity getting close to full. Do not wait for the agent to hit an error in the middle of an important task.
- Because
replaceandremovedepend on substring matching, write entries so they are meaningfully distinct from one another from the beginning. Otherwise you end up with several near-duplicate entries that later cause repeated “matched more than one” errors. - Do not run two agent processes against the same
HERMES_HOME. Memory writes are automatic and memory is reloaded into the system prompt at the start of each session, so two processes writing into one profile will accumulate entries that neither side fully intended. If you need multiple simultaneous agents, give each one its own profile (section 19.4). If you truly need shared memory between multiple agents, use an external memory provider such as Honcho, Mem0, or Supermemory instead of built-in memory. - If your needs go beyond the model of “one machine, one project at a time” — for example long-term parallel work across many projects, multi-user environments behind a shared gateway, or synchronized memory across several machines — the built-in two-file memory system starts to show its limits. That is when it makes sense to consider one of the available external memory providers, such as Honcho, Mem0, Supermemory, or Hindsight, running alongside built-in memory as a supplement rather than a replacement.