Most people searching for "hermes soul md" have just discovered the strangest little file in modern AI: a plain markdown document that tells an agent who it is. Not what it knows. Not which tools it can call. Who it is — its name, its voice, its values, and the rules it never breaks. This guide covers what SOUL.md does inside Hermes, the open-source agent at the heart of Julian Goldie's Agent OS, what belongs in the file, what does not, and how to edit it without giving your agent an identity crisis.
What Is SOUL.md? The Two-Minute Version
Hermes keeps its configuration and memory as plain files you can open, read and edit. SOUL.md is the convention for the persona file: the markdown document that defines the agent's identity and standing behaviour.
A prompt tells an agent what to do today. SOUL.md tells it who to be every day. The agent reads the file each session, so the personality holds steady across conversations instead of resetting to generic-assistant mode every morning.
The difference is a contractor you re-brief from scratch every week versus a colleague who already knows how you work.
The Hermes Soul MD File, Explained
The file lives with the rest of your agent's profile and workspace files, alongside things like its memory files. It is ordinary markdown — headings, bullets, plain sentences — and the format matters:
- You can read it. No dashboard, no hidden system prompt buried in someone else's cloud.
- You can edit it. Any text editor works. So does simply asking the agent to change it.
- You can track it. Plain files compare cleanly, so you can see exactly what changed when the agent started behaving differently.
- You can copy it. A persona that works well in one agent can seed the next one.
The soul is portable, and that is deliberate: personality as data you own, not a setting a platform owns for you.
📺 Watch: Hermes Agent V0.19 Just Changed AI Agents Forever!
One Gateway, Many Souls: Agent Profiles
Since the Quicksilver release, a single Hermes gateway can route to multiple agent profiles. Each profile is a fully separate agent — its own model, its own memory, its own skills, its own secrets. Which means each profile can carry its own SOUL.md.
That is the mechanism behind agent teams. Julian's Agent OS ships specialist agents such as Hermes Apollo for voice, Hermes Oracle for news and Hermes Astros for competitor tracking. Under the hood, each one is effectively a differently-tuned persona doing a different job.
Strip the persona files away and you get one generic bot answering everything in the same beige voice. Put them back and you get a team: a voice agent that keeps answers speakable, a news agent that leads with what changed, a competitor agent that reports without editorialising.
That is part of what you are buying in a done-for-you stack: Agent OS ships with tuned persona files for every agent in the fleet, so you start from a working baseline, not a blank page.
SOUL.md vs Memory: Two Files, Two Jobs
The fastest way to ruin a soul file is to treat it as a notebook. Hermes keeps identity and knowledge separate, and the split is worth memorising:
| Question | SOUL.md | Memory |
|---|---|---|
| What it answers | Who is this agent? | What does this agent know? |
| How often it changes | Rarely, and deliberately | Constantly, as the agent works |
| Typical contents | Name, role, voice, values, boundaries | Facts, preferences, project context |
| Written mostly by | You, on purpose | The agent, as it learns |
| If it vanished | The agent turns generic overnight | The agent forgets your world |
| Human equivalent | Character | Experience |
Julian Goldie's own setup pushes the split to an extreme: knowledge lives in a sprawling Obsidian-based memory system he calls his memory galaxy, while each agent's soul file stays short and stable. The soul is who the agent is; memory is what it knows. Do not stuff facts into the soul file.
📺 Watch: Hermes Agent + Buzz is INSANE!
What Actually Goes In A Good SOUL.md
You need a checklist more than a template. A good soul file covers six things in short, plain, declarative lines — the agent re-reads it every session, so every sentence costs attention.
1. Identity
Name, role, one-line mission. For example: "You are the research agent. You turn messy questions into sourced answers." One line like that already rules out a thousand off-brand behaviours.
2. Voice and tone
How it speaks. Plain English. UK spelling. No hype, no exclamation marks, no filler enthusiasm. If you have ever winced at an AI reply, write the rule that would have prevented it.
3. Values and priorities
What wins when goals collide. Accuracy over speed. Ask before doing anything risky. Prefer boring and correct to clever and wrong.
4. Boundaries
The never-do list, stated flatly: never send money, never publish without approval, never contact anyone new without checking first. Boundaries are the section you will be most grateful for later.
5. Handling uncertainty
Tell the agent what to do when it does not know: say so, plainly, and never invent. An agent that admits uncertainty is worth ten that bluff.
6. Relationship to you
Standing preferences about the human it serves, such as "Julian prefers short answers first, detail on request." The things a good assistant learns in month one, written down on day one.
Resist the urge to write an essay. Long, literary soul files feel satisfying and perform worse: instructions blur, and none get weighted properly. Ten sharp lines beat three paragraphs of vibes.
If you want agents with money-making personalities built in, check out the AI Profit Boardroom — it includes Agent OS with tuned persona files for the whole specialist fleet, so your agents arrive with the personality work already done. → Get the done-for-you agent personas
📺 Watch: Hermes Agent: New Voice Activation Update is INSANE!
Does Persona Tuning Actually Change Output?
Fair question, because a personality file can sound like decoration.
Julian Goldie runs his own hands-on model testing under the banner of Goldie Bench, pitting models against real business tasks rather than abstract puzzles. One pattern he keeps seeing in that testing: persona quality shows up in output quality. The same model, on the same task, reads noticeably different with a sharp persona file behind it — tighter tone, fewer hedges, fewer off-brand moments to edit out. That is his hands-on experience, not a laboratory law — but you will likely notice the same within a day of tuning your own file.
The mechanism is not mysterious. Most of the editing you do on AI output is personality correction — wrong tone, wrong priorities, wrong level of caution. Move those corrections into SOUL.md once and you stop repeating them forever.
How To Edit Your Agent's Soul
Two ways: one obvious, one better.
The direct way
Open the file in your Hermes profile or workspace folder and edit the markdown like any document. Save it, start a fresh chat, and the new personality is live.
The better way
Ask the agent itself. Something like: "Update your SOUL.md — from now on, keep answers brief unless I ask for detail, and always flag anything that costs money before doing it." The agent — or Claude, if that is what drives your setup — edits its own persona file for you, and the change lands in its own voice.
Either way, test like a scientist:
- Change one thing at a time, so you know what caused what.
- Chat with the agent and watch for the behaviour shift.
- Keep the boundaries section intact whenever you trim.
- Copy a persona that works before experimenting on it.
Frequently Asked Questions
Do I need to be technical to edit SOUL.md?
No. It is plain markdown in plain English. If you can edit a note, you can edit a soul — or simply ask the agent to make the change for you.
What happens if I never touch it?
The agent still works; it just behaves like a default assistant. Tuning the file is what turns a capable generalist into a specialist that sounds like your business instead of everyone's.
Can two profiles share one soul file?
Each Hermes profile is a fully separate agent, so each carries its own SOUL.md. The practical pattern: copy a persona that works, keep the values and boundaries, change the role and voice.
How long should the file be?
Short enough that every line still gets respected. If you cannot skim it in under a minute, it is carrying material that belongs in memory instead.
Is SOUL.md the same as a system prompt?
Same family, better habits. It does the job of a system prompt, but as a file you own: readable, editable, versionable and portable rather than locked inside a platform.
The Bottom Line
SOUL.md is the highest-leverage file in a Hermes setup precisely because it is boring: a short markdown document stating who the agent is, how it speaks, what it values and what it never does. Keep identity in the soul, knowledge in memory, and one persona per profile, and a fleet of agents stops feeling like one chatbot wearing different hats and starts feeling like a team.
Start small: ask your agent to show you its current SOUL.md and change one line. You will see the shift in the next conversation — and you will never run a blank-souled agent again.
