Memory: MEMORY.md and USER.md
Hermes's memory is not a vector database — it is two small markdown files:
MEMORY.md— environment facts, project conventions, learned correctionsUSER.md— who you are, your preferences, your communication style
Both have a hard character budget (the docs give memory_char_limit: 2200 and user_char_limit: 1375 — roughly 800 and 500 tokens). That is not a limitation but a design decision: memory enters the system prompt on every request, so it must be a curated list of facts, not an archive.
An important behaviour: at session start, memory is placed into the prompt as a frozen snapshot. Changes made during a session are written to disk immediately, but only show up in the prompt in the next session. The reason is the prefix cache — if the prompt changed mid-session the cache would break.
The memory tool has three actions: add, replace, remove. There is no read — the content is already in the prompt.
| Mechanism | Capacity | Speed | What it is for |
|---|---|---|---|
| Memory (MEMORY/USER) | ~1,300 tokens | Instant — always in the prompt | Critical facts you always need |
| Session search | Unlimited | Milliseconds (FTS5) | "Did we discuss X last week?" |
| Skills | Practically unlimited | A tool call | Repeatable procedures |
What not to put in memory: large code blocks, logs, tables, temporary paths and facts easily found on the web. When memory is 80% full the agent must consolidate before adding — once the budget is exceeded the tool returns an error.
There is a write gate too: with memory.write_approval: true, every write waits for approval (/memory pending, /memory approve). In a corporate setting that is useful for seeing what the agent remembers.
Practice. Deliberately have the agent remember a fact (for example: "tests run with make test"), close the session, open a new one and check the fact carries over. Then look at what was learned with hermes journey. Done means: you can find the fact in MEMORY.md and remove it with /memory.
📚 Sources and documentation
- The memory systemofficialhermes-agent.nousresearch.com
Limits, actions, the approval flow and the memory vs sessions vs skills comparison.
- External memory providersofficialhermes-agent.nousresearch.com
If the built-in budget is too small, an external backend can be plugged in.
- Configurationofficialhermes-agent.nousresearch.com