The Memory System: MEMORY.md, USER.md, and External Memory Providers

What Memory Solves That SOUL.md and AGENTS.md Do Not

SOUL.md (Lesson 5) is identity. AGENTS.md (Lesson 6) is project knowledge you wrote by hand. Memory is different again: it is what the agent learns on its own, over time, through actually working with you -- facts neither you nor it had written down anywhere until the moment it came up.

Two Files, Two Purposes

Hermes splits memory into two separate files, both living in ~/.hermes/memories/:

• MEMORY.md -- a 2,200 character limit, roughly 800 tokens. This is the agent's notes about your environment, your conventions, and lessons it has learned working with you.
• USER.md -- a 1,375 character limit, roughly 500 tokens. This is specifically about you: preferences, communication style, expectations.

The split matters because the two kinds of information have different shelf lives and different relevance. Splitting them keeps each file focused enough to actually stay useful as it fills up.

How Entries Get Written

The agent manages memory through a dedicated tool with three actions:

• add -- create a new entry
• replace -- update an existing entry, matched by a unique substring rather than requiring the full original text
• remove -- delete an entry no longer relevant, also via substring match

Substring matching for replace/remove is a small but practical detail: the agent does not need to reproduce an entry word-for-word to update or delete it, just enough of it to uniquely identify which one it means.

Inside the system prompt, individual entries are separated by the § (section sign) character, and can span multiple lines. You will sometimes see the current capacity displayed, in a format like [67% — 1,474/2,200 chars] -- a running gauge of how full a given memory file is.

The Frozen Snapshot Behavior

This is the single most important mechanical detail about Hermes memory, and it surprises people who expect memory to update live mid-conversation: memory loads once, at session start, and stays unchanged for the rest of that conversation. This is intentional -- it preserves the LLM's prefix cache, which keeps responses faster and cheaper.

What this means in practice: if the agent writes a new memory entry to disk during a session, that write happens immediately and persists -- but it will not show up in the system prompt of the current conversation. It only appears starting with the next session. If you ask the agent to remember something and then immediately quiz it in the same conversation, it will already know the answer (it is right there in the conversation history) -- but the real test is whether a brand new session, started fresh, also knows it.

Configuration

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375
  write_approval: false

write_approval is worth knowing about even if you leave it off to start. Setting it to true gates every memory write behind your explicit approval rather than letting the agent write freely -- useful if you want oversight over what it decides is worth remembering. Pending writes under this setting are reviewable with /memory pending.

Testing It For Real

Do not take memory persistence on faith -- verify it. In a session, tell the agent something specific and slightly unusual: "Remember that I prefer terse commit messages, no more than one line." Then close that session entirely and start a brand new one. Ask something that would only be answered correctly if it actually remembered: "What do you know about how I like commit messages written?" If the new session gets it right without you re-explaining, the frozen-snapshot mechanism worked exactly as designed.

When Built-In Memory Is Not Enough

For most individual use, MEMORY.md and USER.md are sufficient. But Hermes also supports nine external memory provider plugins for more advanced cross-session modeling, semantic search, or shared/multi-device memory -- only one can be active at a time, alongside the built-in files:

Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, Supermemory, Memori

These range from fully local and free (Holographic, a SQLite store with full-text search) to cloud-hosted and paid (Mem0, Supermemory). Setup is interactive:

hermes memory setup      # Pick a provider
hermes memory status     # Check what is currently active
hermes memory off        # Disable an external provider

Or configure one manually in config.yaml:

memory:
  provider: honcho

This is genuinely optional -- most people get real value from the built-in files alone, and switching to an external provider is something to revisit later if you find yourself wanting cross-device memory or semantic search over a much larger history than 2,200 characters can hold.

That completes the foundational picture: identity, project awareness, inline context, and memory. The final lesson in this track ties all four together in one real, hands-on walkthrough.