.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Hermes Agent has four markdown files that shape the prompt the model sees on every turn. SOUL.md, AGENTS.md, USER.md and MEMORY.md. They look similar so people often dump everything in SOUL.md and then wonder why behaviour is inconsistent across projects. The split between these files matters more than it looks at first.
This article explains what goes in each one and why. The technical loading order is in our Hermes memory architecture piece. This one is about how to structure the content for real use.
The four files at a glance
| File | Scope | Purpose |
|---|---|---|
| SOUL.md | Global, all sessions | Persona, voice, base behaviour |
| AGENTS.md | Per project | Project conventions and context |
| USER.md | Global, all sessions | Facts about you, the operator |
| MEMORY.md | Global, mostly auto | Retained facts the agent learned |
SOUL.md: persona and voice
This is who the agent is. Tone, values, communication style, base caution level. If you handed a new colleague a single page that says "this is who you should be at this job", that page is SOUL.md.
What belongs in SOUL.md
- "You are direct and prefer short answers over long ones."
- "You explain your reasoning briefly before doing anything irreversible."
- "You write British English. No em dashes."
- "You are comfortable disagreeing when you have a good reason."
What does NOT belong in SOUL.md
- "In ~/code/work-app, run npm test before commits." (belongs in that project's AGENTS.md)
- "My name is Andrei." (belongs in USER.md)
- "Deploy script is at scripts/deploy.sh." (belongs in AGENTS.md)
The most common SOUL.md mistake
Overloading it with caution. "Never run destructive commands. Always ask before editing files. Confirm before pushing. Verify before merging. Be careful with shell access." The model adds these up into an agent that refuses to do anything because it's busy asking for permission constantly.
If you're writing the fourth caution rule, you don't need more caution in SOUL.md. You need better tool scoping. See our Hermes talks but takes no action diagnostic if you've crossed that line.
AGENTS.md: project-specific knowledge
One AGENTS.md per project, in the project root. The agent reads whichever one applies based on the current working directory. Switch directories, different AGENTS.md takes over. No cross-contamination.
What belongs in AGENTS.md
- "This is a Next.js 14 app with the App Router. Server components by default."
- "Tests live in __tests__ next to source. Run with npm test."
- "Deployments through GitHub Actions on main. Don't push directly to main."
- "Linting enforced. Run npm run lint before committing."
- "Staging URL: staging.example.com. Production: example.com. Don't mix them."
AGENTS.md is also where project-specific behaviour overrides go
If your SOUL.md says "always confirm before acting" but in this specific project you trust the agent to run tests aggressively, AGENTS.md is where you say so:
"In this project, run tests after every edit without asking."
That's scoped. It applies only here. It doesn't leak into other projects.
USER.md: who you are
Facts about you, the operator. The agent reads this so it doesn't have to ask you the same things every session. Keep it factual and concise.
What belongs in USER.md
- "My name is Andrei. I am CMO at LumaDock."
- "I'm based in London, GMT/BST."
- "Prefer short replies. Less explanation, more substance."
- "I read code but I'm not a daily coder. Use business framing for technical summaries."
Update USER.md occasionally when something stable about you changes. Don't put project state here. Don't put memory content here.
MEMORY.md: what the agent has learned about you
This file mostly maintains itself. The agent's learning loop adds entries as it picks up things from sessions. Facts you mentioned that turned out to be relevant later. Decisions you made that the agent thinks should persist. Observations about your preferences.
When to hand-edit MEMORY.md
Only when the agent has it wrong. If MEMORY.md says you prefer dark mode but you use light mode and the agent keeps recommending dark themes, find that line and delete it. Don't try to manage the whole file by hand. That defeats the point.
How the precedence works in practice
When the agent builds a prompt, it stacks the files in this order:
- SOUL.md as system-level identity
- AGENTS.md as project context (current directory only)
- USER.md as personal facts
- MEMORY.md as long-term retained info
If two files contradict, later in the stack tends to win for that specific topic. AGENTS.md can override SOUL.md for project-specific behaviour. It cannot rewrite who the agent fundamentally is.
Common problems and fixes
"I edited SOUL.md but the agent sounds the same"
Four possible causes.
Cause: wrong file location
The agent reads SOUL.md from the active persona directory, not always your home dir. Run hermes persona show to see which file it currently loads.
Cause: session cache
SOUL.md is loaded at session start and held for the duration. Run /new to start a fresh session.
Cause: AGENTS.md overrides the edit
If you changed tone in SOUL.md but the project's AGENTS.md sets a different tone, AGENTS.md wins in that project.
Cause: small model ignores nuanced instructions
Smaller models don't always follow detailed persona rules. Test with a bigger model to confirm.
"SOUL.md is becoming too project-specific"
Refactor. Move the project parts into the project's AGENTS.md. Keep SOUL.md focused on persona only. Less is more in SOUL.md.
SOUL.md vs /personality slash command
The /personality command sets a temporary persona for the current session only. Use it for one-off shifts ("be more playful for this brainstorm"). Don't use it for anything you want to persist. If you keep running /personality the same way every session, that instruction belongs in SOUL.md.
Testing SOUL.md edits without breaking your install
Before committing a SOUL.md change, backup the current file:
cp ~/.hermes/SOUL.md ~/.hermes/SOUL.md.backup
# make your edit
hermes chat -q "summarise yourself in two sentences"
# if the output is wrong, revert
cp ~/.hermes/SOUL.md.backup ~/.hermes/SOUL.mdThe smoke test ("summarise yourself in two sentences") catches most persona drift in seconds.
Backing up all four files
These files plus state.db are what define your agent. Lose them, you lose your accumulated identity. A git repo of ~/.hermes/ with state.db gitignored is enough for the markdown. For state.db use the SQLite-aware approach in our Hermes backups guide.
One persona per real context
The reason all four files matter is that you probably need more than one set of them. I run a Work persona and a Personal persona. Each has its own SOUL.md, USER.md and MEMORY.md. AGENTS.md varies by project under either. Switching is one command, zero contamination.
If you're running one giant SOUL.md that tries to be everything, splitting that into focused personas is the first improvement worth making.
Starting from sensible defaults on a LumaDock VPS
If you'd rather not write the four files from scratch, the LumaDock Hermes Agent template comes with reasonable default SOUL.md and an empty USER.md ready to fill in. The layout matches what the rest of these tutorials assume. Unmetered bandwidth, no setup fees. Full setup walkthrough in our Hermes Agent complete guide.
