The four memory layers
SOUL.md — personality and communication style. MEMORY.md — facts you've shared. Session history database — every conversation, searchable. Honcho — optional external service for smarter cross-session recall.
Each does something different. They work together.
This matters because 'I told my agent something last week — why did it forget?' is almost always a question about which layer that information was supposed to land in. Hermes doesn't automatically remember everything — it decides what's worth writing down. Same way a person takes notes on some things and lets others go.
SOUL.md — personality
SOUL.md defines how the agent communicates: tone, what to avoid, how direct to be. It's the first thing loaded in every conversation, before any task context or memory.
Free-form Markdown, no fixed schema. Example from the official docs:
# Personality
You are a pragmatic senior engineer.
You optimize for truth and clarity over politeness theater.
## Style
- Be direct without being cold
- Prefer substance over filler
## What to avoid
- Sycophancy
- Hype language
Changes take effect the next session. If the file is missing, Hermes falls back to the built-in default: 'You are Hermes Agent, an intelligent AI assistant created by Nous Research.'
SOUL.md shapes how the agent speaks. MEMORY.md shapes what it knows about you. Editing one doesn't affect the other.
MEMORY.md — what it knows about you
MEMORY.md is where Hermes writes facts worth keeping: your name, your tech stack, standing preferences, context that would be annoying to repeat every session.
The agent writes here when it judges something worth persisting. You can push it explicitly:
'Remember that I want all code examples in Python 3.12.'
Or just open the file yourself and add a line — it's plain text, nothing encrypted:
There's also USER.md — the agent updates this on its own based on patterns it notices in how you work. MEMORY.md is facts you told it. USER.md is conclusions it drew. You can read and edit both.
Session history
Every conversation is saved to a searchable database on the server. Ask Hermes about something from a past session — 'What did I tell you about the auth service last month?' — and it searches through conversation history to find the relevant context.
The search is keyword-based. It finds messages containing the words you use, not the meaning behind them. If you said 'that deployment thing' months ago, searching for 'CI/CD pipeline' might not find it. Different words, same concept.
Browse your own history:
Conversations are kept indefinitely unless you configure pruning. On a small server this adds up — the VPS guide covers how quickly storage grows.
The keyword limitation is real. If your vocabulary for something varied across sessions, the agent might not connect the dots. That's the gap Honcho addresses.
Honcho — memory that understands context
Honcho (built by Plastic Labs) adds meaning-based memory on top of keyword search. It understands what you were talking about and surfaces relevant context even when you phrase things differently.
Practical example: you spent Tuesday working through a complex database migration. Three weeks later you start a new session. Keyword search won't connect the two unless you use the same words. Honcho does.
Once connected, it gives Hermes four additional memory tools: fast fact lookup, semantic search over your full history, question-answering from past sessions, and the ability to write important facts down for later.
Setting Honcho up is more involved — it runs as a separate background service and requires Docker. For most people, the built-in keyword search is good enough. Honcho pays off when you have months of history you want the agent to draw on intelligently.
For a simpler alternative: Mem0 is another memory provider, easier to get running. Configure either with:
What actually persists
Reliably remembered: your name; preferences you stated explicitly; standing instructions; anything the agent wrote to MEMORY.md.
Unreliable: things mentioned once in passing that it didn't judge important; things said late in a long conversation when the AI's working memory was full.
Gone at session end: anything not explicitly saved to MEMORY.md or Honcho. Think of it like a phone call — the conversation is over, but notes you took during it survive.
Habit worth building: at the end of a productive session, ask 'What should you save to your memory from this conversation?' It identifies the important facts and writes them down. Faster than editing the file yourself.
Backing up memory
All memory files live in ~/.hermes/. Back up the whole directory:
This captures personality files, facts, conversation history, skills, and config. API keys are usually in there too — encrypt the archive before storing it anywhere:
Restoring on a new server: unpack the archive and Hermes picks everything up on next start.
Memory on Hermes OS
Using Hermes OS: all four memory layers are on and backed up automatically. SOUL.md, MEMORY.md, conversation history, and installed skills survive container restarts, redeployments, and cancellation. Nothing to configure.
Self-hosting: the self-hosting guide covers backup setup. Worth doing before you accumulate months of conversation history you'd be sad to lose.