SOUL.md and Personality

The Most Important File You Will Edit

SOUL.md occupies the first slot in your agent's system prompt. It is a durable persona file, living at ~/.hermes/SOUL.md (or $HERMES_HOME/SOUL.md if you are using a custom home directory), that defines who the agent is and persists across every session. Where memory (Lesson 8) tracks facts the agent has learned, SOUL.md tracks something more stable: identity.

You do not need to create this file yourself the first time. Hermes automatically generates a starter SOUL.md if one does not exist -- and once you have edited it, Hermes will never silently overwrite your version.

What Belongs in SOUL.md

The documentation is specific about what this file is for. It works best for stable, contextual elements of how the agent communicates:

• Communication tone and style
• Level of directness
• How to handle uncertainty or disagreement
• What to avoid stylistically

The official example leans toward a pragmatic senior-engineer persona: direct, substance over filler, no hype language, no sycophancy.

Just as important is what does not belong here. Project-specific details -- file paths, which framework a particular repo uses, temporary workflow instructions -- should not go in SOUL.md. That content belongs in AGENTS.md instead, which is the subject of the next lesson. Mixing the two means your agent's core personality file grows stale and project-specific the moment you move to a different piece of work.

Built-In Personality Presets

Separate from SOUL.md, Hermes ships 13 built-in personality presets you can switch to for a given session:

helpful, concise, technical, creative, teacher, kawaii, catgirl, pirate, shakespeare, surfer, noir, uwu, philosopher, hype

Activate one with a slash command:

/personality technical

This is the right tool when you want a different conversational flavor for one session -- "technical" for a deep debugging conversation, "teacher" when you want more explanation than usual -- without permanently rewriting your agent's actual identity.

Defining Your Own Personalities

If the 13 presets do not cover what you want, you can define named custom personalities directly in config.yaml under agent.personalities, then activate yours the same way:

/personality customname

SOUL.md vs. /personality: Knowing Which to Use

This is the distinction that matters most in this lesson, and it is easy to blur the two:

• SOUL.md is your agent's baseline voice -- who it is, every single session, by default.
• /personality is a temporary session-level overlay -- a costume for this conversation, not a personality change.

If you find yourself running /personality the same way at the start of every single session, that is usually a sign the trait belongs in SOUL.md instead, not as a recurring manual step.

Writing Your First Real SOUL.md

A practical starting point: open ~/.hermes/SOUL.md in your editor and write three or four short paragraphs answering these questions directly, in plain prose rather than bullet-pointed rules:

• How direct should this agent be when it disagrees with you?
• Should it hedge ("this might be wrong, but...") or commit to an answer?
• What tone fits the work you actually do with it -- terse and technical, or more conversational?
• Is there anything it should actively avoid -- excessive enthusiasm, apologizing too much, restating your question back to you before answering?

Save the file, start a fresh session, and notice the difference immediately. This is one of the few changes in Hermes that is instantly, viscerally obvious -- unlike most configuration, you will feel SOUL.md working within the first reply.

The next lesson covers AGENTS.md -- the file that makes your agent aware of the actual projects you are working in, which is the project-specific counterpart to the identity work you just did here.