What SOUL.md actually is
SOUL.md is the first thing in Hermes' system prompt. It is the agent's identity, and it replaces the built-in default identity instead of being added on top of it. Hermes creates a starter file at ~/.hermes/SOUL.md (strictly, $HERMES_HOME/SOUL.md) the first time it runs and never overwrites a file you've already edited. If the file is empty or can't be read, Hermes falls back to its built-in identity.
Hermes only loads SOUL.md from its home folder, never from the directory you launch it in. That's deliberate: your agent's personality shouldn't change because you cd into a different project. Each profile has its own home, so each profile can have its own SOUL.md. That's a clean way to run a terse coding agent next to a warmer personal assistant.
What belongs in it, and what doesn't
The docs draw a sharp line here. SOUL.md is for things that should follow you everywhere: tone, directness, how to handle uncertainty and disagreement, and what to avoid in style. AGENTS.md is for things that belong to one project: architecture, coding conventions, commands, ports, paths and deployment notes. A good test is to ask whether the instruction would still make sense in a completely different folder. If it would, it belongs in SOUL.md.
- Strong: a few specific lines about voice. For example: be direct, admit uncertainty plainly, push back on weak ideas, keep answers compact unless depth helps.
- Weak: generic filler like 'be helpful and clear'. Hermes already does that.
- Wrong place: file paths, repo rules, temporary task instructions, or anything that tries to micro-manage the shape of every response.
A first edit that pays off
You don't need a long file. The official guide suggests changing a few lines so the agent sounds like someone you want to work with, then living with it for a few days. A simple structure helps: Identity (who the agent is), Style (how it sounds), Avoid (what it shouldn't do), and Defaults (how it behaves when a request is ambiguous). Edit the file directly, then start a new session to hear the difference.
Because SOUL.md is your own file, Hermes still scans it for prompt-injection patterns, but a match doesn't block it the way it would block a project AGENTS.md. The file still loads, Hermes logs a warning, and /context marks the file for review. If you see that warning, read the flagged line rather than ignoring it.
Personalities are temporary overlays
/personality switches the agent into a mode for the current conversation without touching your SOUL.md. Built-in presets include helpful, concise, technical, creative and teacher, plus playful ones like pirate, noir and shakespeare. Type /personality on its own to list them and see which is active, and use /personality none (or default or neutral) to go back to your base voice. Presets work in the CLI, the TUI, the desktop app and messaging platforms.
You can define your own under agent.personalities in config.yaml. For example, a codereviewer entry with a short paragraph describing a meticulous reviewer becomes available as /personality codereviewer. Reusing a built-in name overrides that preset. The active selection is stored as a name in display.personality, and personalities never change agent.system_prompt.
How the layers stack
Roughly, the prompt is built in this order: SOUL.md first, then tool guidance, memory and user context, skills guidance, context files such as AGENTS.md, the timestamp, platform formatting hints, and finally any overlay such as /personality. The recommended setup follows from that order: a thoughtful global SOUL.md, project instructions in AGENTS.md, and /personality only when you want a temporary change of mode. Terminal appearance is a separate setting entirely. /skin and display.skin change how Hermes looks, not how it talks.
Related guides
- Hermes Agent memory vs context files vs project notes
- Hermes Agent ignoring your project instructions
- Hermes Agent profiles: separate agents for separate jobs
- Hermes Agent setup: your first 24 hours
Primary sources
Spotted something wrong or out of date? Tell us on X at @HermesWatcher (opens in a new tab) and we will fix it.
New Hermes Agent updates every day on X. Follow @HermesWatcher