Wiki · Start here
Agent memory
Two short notes the agent carries into every new conversation — and the three places where it remembers anything at all.
Two memories, kept apart
The agent keeps two short lists — one about you, one about the work. Both live in
~/.hermes/memories/ as plain text files, so you can back them up or move them.
| File | What is in it | How big it is |
|---|---|---|
USER.md | Who you are and how to talk to you: name, what you do, what annoys you, concise or detailed answers | about 1,375 characters (half a page) |
MEMORY.md | Notes about the work: how the server is set up, your habits, what worked, what to watch out for | about 2,200 characters (under a page) |
Individual notes are separated by the § character so they can be edited or removed one by one.
Why memory is so short
| Reason | What it means for you |
|---|---|
| It is part of every request | Every line in memory costs you on every question — so it cannot hold everything |
| It does not shrink by itself | When it is full, the agent must first drop or shorten something before adding a new note |
| Only essentials belong there | Not fragments of a conversation, and not anything that can be looked up later |
What the agent saves by itself
You do not have to ask. It saves anything it learns that will still be true next time:
| What it learns | Example |
|---|---|
| Your preferences | "I want short answers, no tables." |
| How your environment is set up | "The site runs on nginx, the database is MariaDB, the domain is example.com." |
| Corrections and warnings | "Don't use sudo, the user is in the docker group." |
| Project conventions | "URLs end with a slash, image filenames use hyphens." |
| Completed work | "The database migration happened on 12 Oct 2026." |
What it will not save: something you mentioned in passing with no consequence, values from settings (passwords and keys belong elsewhere, not in memory), and anything it can find in past conversations.
When you want it to remember something
Just say so — that always works:
You can also ask what it keeps, or have a note corrected:
You are welcome to open the file and read it (it is plain text):
cat ~/.hermes/memories/USER.md. Editing it by hand is best left alone — going through the
agent is safer, as it cleans up duplicates itself.
Three places where the agent remembers
| Where | What is there | How to use it |
|---|---|---|
| The live conversation | Everything you have just written to each other | Just talk; when a chat gets long the agent trims it (/compress) |
| Memory (USER.md, MEMORY.md) | Only the essentials, always at hand | Applies to every new conversation from the first question |
| Past conversations | Everything you have ever discussed — unlimited | "How did we do that back then?" It remembers months later |
A practical consequence: memory takes effect in a new conversation.
When you start a new task or a new day, run /new — the agent re-reads what it knows about you and
starts with a clear head (past conversations remain searchable).
Rules that always apply
Alongside memory, the agent reads context files from your folder at the start of work. You write those yourself; they have no length limit and apply to the whole project:
| File | What it is for |
|---|---|
AGENTS.md | Project rules and conventions — what is kept where, what is forbidden, how things are deployed |
HERMES.md (or .hermes.md) | The same, but with the highest priority |
SOUL.md | How the agent should speak and behave (tone, language) |
The distinction is simple: anything long and always true belongs in a context file. Anything short that the agent must always have at hand belongs in memory.
When it does not work
| Symptom | Cause and what to do |
|---|---|
| "I told it and it forgot." | Most likely it stayed in the conversation and was never saved. Say it again explicitly: "remember that…" |
| It saved it, but a new chat acts as if it did not | Check that a new conversation actually started (/new) — memory is read at its beginning |
| It remembers something wrong | Tell it exactly what is wrong: "delete … from memory" or "change that note to…" |
| Memory is full and it saves nothing new | The agent must tidy up first. Say: "tidy up memory and save this." It never compacts on its own |
| I want to approve every save | Set memory.write_approval: true to be asked before anything is written |
Tips from experience
| Tip | Why |
|---|---|
| Start a new day with a new conversation | That is when memory pays off — the agent re-reads what it knows and does not carry yesterday's clutter |
| Put lasting rules in a context file | You do not have to repeat them and they do not take up the short memory |
| Good notes are specific | "URLs end with a slash" can be followed; "do it nicely" cannot |
| Passwords and keys do not belong in memory | Memory is part of every request — secrets belong in settings |
| Ask what it keeps | Surprises are easier to fix now than in a month. Just ask: "what do you remember about me?" |