SOUL.md for Hermes Agent: what it is and how to write one

What is SOUL.md?

SOUL.md is the markdown file that gives your Hermes agent its identity: who it is, how it sounds and how it behaves by default. The docs call it the agent's primary identity. It is meant for durable voice and personality guidance such as:

• tone and communication style
• how direct the agent should be
• its default way of interacting
• what to avoid stylistically
• how to handle uncertainty, disagreement and ambiguity

Hermes creates a starter SOUL.md automatically if one does not exist, and it never overwrites a file you have already written.

Where does SOUL.md live?

SOUL.md lives in the Hermes home directory, at ~/.hermes/SOUL.md for most people or $HERMES_HOME/SOUL.md if you run Hermes with a custom home. Each profile has its own copy, for example ~/.hermes/profiles/coder/SOUL.md.

Hermes never looks for SOUL.md in your current working directory, so a SOUL.md inside a project folder has no effect. This is deliberate: the personality belongs to the Hermes instance, so it does not change when you open a different project.

To edit it:

nano ~/.hermes/SOUL.md

Then start a new session so Hermes reads the new version.

How does Hermes load SOUL.md?

Hermes reads SOUL.md once at the start of each session and places its content in slot #1 of the system prompt, replacing the built-in default identity. Before injecting it, Hermes scans the file for prompt-injection patterns and truncates it if it is too large. No wrapper text is added, so the words you write are exactly what the model sees first.

The full prompt stack, in order, is:

1. SOUL.md (or the built-in identity if SOUL.md is unavailable)
2. Tool-aware behavior guidance
3. Memory and user context
4. Skills guidance
5. Context files such as AGENTS.md
6. Timestamp
7. Platform-specific formatting hints
8. Optional overlays such as /personality

A few edge cases are worth knowing:

• If SOUL.md is empty, whitespace-only or unreadable, Hermes falls back to its built-in default identity.
• The same fallback applies when skip_context_files is set, for example in subagent and delegation contexts.
• If the injection scanner matches something in your own SOUL.md, the file still loads. Hermes logs a warning and /context marks the file for review. A SOUL.md installed by a profile distribution is blocked instead.
• Edits made while a session is running take effect in the next session.

What belongs in SOUL.md, AGENTS.md and memory?

Each file has a different job, and putting content in the wrong one is the most common mistake. Use this table to decide.

The docs give a simple rule: if it should follow you everywhere, it belongs in SOUL.md. If it belongs to one project, it belongs in AGENTS.md.

SOUL.md and USER.md never feed each other. If you write "my name is Sam" in SOUL.md, USER.md stays empty. To store facts about yourself, tell the agent to remember them and it will save them to memory.

Only one project context file loads per session, and the first match wins in this order: .hermes.md, AGENTS.md, CLAUDE.md, .cursorrules. SOUL.md sits outside that chain and always loads.

How do /personality overlays work with SOUL.md?

/personality is a temporary mode switch layered on top of SOUL.md for the current session. SOUL.md stays your baseline voice. Hermes ships built-in personalities such as helpful, concise, technical, creative and teacher, plus playful ones such as pirate and noir.

/personality teacher
/personality none

/personality none (or default, or neutral) clears the overlay and returns to your SOUL.md persona. You can add your own presets in ~/.hermes/config.yaml under agent.personalities:

agent:
  personalities:
    editor: >
      You edit drafts for accuracy and clarity. Flag unsupported claims,
      vague wording and repetition, and suggest a shorter version of each
      weak sentence.

Switch to it with /personality editor. Your selection is stored as a name in display.personality.

What does an example SOUL.md for a practical assistant look like?

The file below is an original example written for this guide, not the default file Hermes ships. It sets up a direct, practical assistant for someone who runs their own work.

# Identity
You are a practical assistant for a person who runs their own work.
You help them decide, then help them act. Being correct and useful
matters more to you than sounding friendly.

# Style
- Lead with the answer, then give the reason in a sentence or two
- Use plain words and short paragraphs
- Number the steps when a task has more than two
- Match length to the request: a quick question gets a quick reply
- Say "I'm not sure" when that is true, and say what would settle it

# Avoid
- Flattery and filler openers
- Restating the question before answering it
- Marketing language and exclamation marks
- Long lists of options when one clear recommendation will do

# Defaults
- If a request is ambiguous and a wrong guess is cheap, pick the most
  likely reading and state your assumption in one line
- If a wrong guess would waste real time or money, ask one short
  question first
- When you disagree, say so once with your reason, then follow the
  user's decision
- Before anything that deletes, sends or spends, say exactly what
  will happen

Why this works: it is stable across contexts, broad enough to apply to any conversation, and specific enough to change how replies read. It contains no file paths, project rules or personal facts, which belong in AGENTS.md and memory.

SOUL.md guides the model. It does not enforce anything. The last default above shapes how the agent talks about risky actions, but the real controls are Hermes' command approvals, terminal.cwd and sandboxed terminal backends.

How do you check that SOUL.md is working?

Start a new session, ask a question where tone matters, and compare the reply with your file. If nothing changed, check these points from the docs:

• You edited ~/.hermes/SOUL.md or $HERMES_HOME/SOUL.md, not a SOUL.md in a project folder.
• You are in the profile you think you are. The CLI prompt shows the profile name.
• The file is not empty.
• You started a new session after editing.
• A /personality overlay is not dominating the result.
• The file is not so long that it was truncated.
• /context does not show a review warning for the file.

What should a finished SOUL.md include?

A good SOUL.md passes every item on this list before you rely on it:

• The file is at ~/.hermes/SOUL.md or in the right profile directory
• It defines identity, style, things to avoid and default behavior
• It adds a few specific lines rather than generic filler like "be helpful"
• It has no commands, ports, paths or repo conventions (move them to AGENTS.md)
• It has no facts about you (let the agent save those to memory)
• It does not contradict itself
• You do not rely on it for safety boundaries
• You start a new session after every edit

FAQ

Sources

• Personality & SOUL.md
• Use SOUL.md with Hermes
• Which File Does What?
• Persistent Memory
• Profiles: Running Multiple Agents
• Security (context file injection protection)