Two small files, not a database
Hermes's built-in memory is deliberately small. It is two markdown files in ~/.hermes/memories/: MEMORY.md holds the agent's own notes (facts about your environment, conventions, lessons it learned the hard way) and USER.md holds what it knows about you (preferences, communication style, expectations). If you use a named profile, the files live under that profile's own memories folder instead, so each profile remembers separately.
The limits are strict and worth knowing by heart: MEMORY.md is capped at 2,200 characters (roughly 800 tokens) and USER.md at 1,375 characters (roughly 500 tokens). That is a few dozen short facts, not a notebook. The design choice is intentional: because both files are injected into every session, keeping them small keeps every message cheaper.
The frozen snapshot: why a new fact doesn't show up straight away
At the start of a session Hermes reads both files and renders them into the system prompt as a frozen snapshot. That snapshot does not change for the rest of the session, even if the agent writes something new. The write is saved to disk immediately, but you will only see it reflected in the prompt from the next session onward.
This trips people up: you say "remember that I prefer metric units", the agent confirms, and nothing seems different. It is working as designed. The reason is prompt caching: a stable system prompt lets your provider reuse the cached prefix, which is faster and cheaper. If you need the new fact active now, start a fresh session with /new.
How the agent edits memory
The agent manages memory with a single memory tool. Every call names a target, either "memory" or "user", and uses one of three actions. There is no read action, because the contents are already in the prompt.
- add: appends a new entry. Exact duplicates are rejected with a 'no duplicate added' note.
- patch: replaces one span inside an existing entry and keeps the rest. The matching text has to identify exactly one entry.
- remove: deletes the entry that matches a substring. Again, the substring must match only one entry.
- The older replace action now returns an error pointing to patch.
What happens when memory is full
Memory does not compact itself. When a write would exceed the limit, the tool returns an error listing the current entries and usage, and the agent has to free space and add the new entry in one batch. The docs suggest consolidating once usage passes about 80%. In practice the easiest fix is to ask Hermes directly: "consolidate your memory and drop anything outdated."
Every entry is also scanned before it is saved. Content that looks like prompt injection, credential exfiltration, SSH backdoors or hidden Unicode is blocked. If you want to see every write before it lands, set memory.write_approval: true in config.yaml and review staged writes with /memory pending, /memory approve and /memory reject.
What belongs in memory and what doesn't
Good memory entries are short, durable and genuinely useful in most future sessions. The docs list what to keep out:
- Trivial or vague notes, and facts that are easy to look up again.
- Raw dumps such as large code blocks, logs or data tables.
- Session-specific details like one-off paths or debugging context.
- Anything already covered by context files such as
AGENTS.mdorSOUL.md. - Credentials: those belong in
~/.hermes/.env, not memory. - Step-by-step procedures you repeat: write a skill instead. The docs summarise it as memory for facts, skills for procedures.
Beyond the two files: session search and external providers
Two other mechanisms cover what the small files cannot. First, every CLI and messaging conversation is stored in a SQLite database (~/.hermes/state.db) with full-text search, and the agent can query it with the session_search tool. That search is unlimited, runs only when needed and makes no extra LLM calls, so it is the right place for "what did we decide last month?" rather than stuffing memory.
Second, you can add one external memory provider at a time. The docs list Honcho, OpenViking, Mem0, Hindsight, Holographic (local SQLite, no external service), RetainDB, ByteRover, Supermemory and Memori. Run hermes memory setup to pick and configure one, hermes memory status to see what is active and hermes memory off to disable it. A provider is additive: MEMORY.md and USER.md keep working, while the provider prefetches relevant memories each turn, syncs turns after responses and adds its own search tools. Content sent to a provider is scrubbed for recognisable secrets first, but credentials without a recognisable shape are not caught, so don't rely on scrubbing alone.
Related guides
- Hermes Agent memory vs context files vs project notes
- Hermes Agent memory not carrying over between sessions
- Hermes Agent sessions: search and resume past work
- How to write your first Hermes Agent skill
Primary sources
Spotted something wrong or out of date? Tell us on X at @HermesWatcher (opens in a new tab) and we will fix it.
New Hermes Agent updates every day on X. Follow @HermesWatcher