Personality & SOUL.md

Hermes Agent's personality is fully customizable. SOUL.md is the primary identity — it's the first thing in the system prompt and defines who the agent is.

• SOUL.md — a durable persona file that lives in HERMES_HOME and serves as the agent's identity (slot #1 in the system prompt)
• built-in or custom /personality presets — session-level system-prompt overlays

If you want to change who Hermes is — or replace it with an entirely different agent persona — edit SOUL.md.

Hermes now seeds a default SOUL.md automatically in:

~/.hermes/SOUL.md

More precisely, it uses the current instance's HERMES_HOME, so if you run Hermes with a custom home directory, it will use:

$HERMES_HOME/SOUL.md

Important behavior

• SOUL.md is the agent's primary identity. It occupies slot #1 in the system prompt, replacing the hardcoded default identity.
• Hermes creates a starter SOUL.md automatically if one does not exist yet
• Existing user SOUL.md files are never overwritten
• Hermes loads SOUL.md only from HERMES_HOME
• Hermes does not look in the current working directory for SOUL.md
• If SOUL.md exists but is empty, or cannot be loaded, Hermes falls back to a built-in default identity
• If SOUL.md has content, that content is injected verbatim after security scanning and truncation
• SOUL.md is not duplicated in the context files section — it appears only once, as the identity

That makes SOUL.md a true per-user or per-instance identity, not just an additive layer.

This keeps personality predictable.

If Hermes loaded SOUL.md from whatever directory you happened to launch it in, your personality could change unexpectedly between projects. By loading only from HERMES_HOME, the personality belongs to the Hermes instance itself.

That also makes it easier to teach users:

• "Edit ~/.hermes/SOUL.md to change Hermes' default personality."

For most users:

~/.hermes/SOUL.md

If you use a custom home:

$HERMES_HOME/SOUL.md

Use it for durable voice and personality guidance, such as:

• tone
• communication style
• level of directness
• default interaction style
• what to avoid stylistically
• how Hermes should handle uncertainty, disagreement, or ambiguity

Use it less for:

• one-off project instructions
• file paths
• repo conventions
• temporary workflow details

Those belong in AGENTS.md, not SOUL.md.

A good SOUL file is:

• stable across contexts
• broad enough to apply in many conversations
• specific enough to materially shape the voice
• focused on communication and identity, not task-specific instructions

Example

# Personality

You are a pragmatic senior engineer with strong taste.
You optimize for truth, clarity, and usefulness over politeness theater.

## Style
- Be direct without being cold
- Prefer substance over filler
- Push back when something is a bad idea
- Admit uncertainty plainly
- Keep explanations compact unless depth is useful

## What to avoid
- Sycophancy
- Hype language
- Repeating the user's framing if it's wrong
- Overexplaining obvious things

## Technical posture
- Prefer simple systems over clever systems
- Care about operational reality, not idealized architecture
- Treat edge cases as part of the design, not cleanup

SOUL.md content goes directly into slot #1 of the system prompt — the agent identity position. No wrapper language is added around it.

The content goes through:

• prompt-injection scanning
• truncation if it is too large

If the file is empty, whitespace-only, or cannot be read, Hermes falls back to a built-in default identity ("You are Hermes Agent, an intelligent AI assistant created by Nous Research..."). This fallback also applies when skip_context_files is set (e.g., in subagent/delegation contexts).

SOUL.md is scanned like other context-bearing files for prompt injection patterns before inclusion.

That means you should still keep it focused on persona/voice rather than trying to sneak in strange meta-instructions.

This is the most important distinction.

SOUL.md

Use for:

• identity
• tone
• style
• communication defaults
• personality-level behavior

AGENTS.md

Use for:

• project architecture
• coding conventions
• tool preferences
• repo-specific workflows
• commands, ports, paths, deployment notes

A useful rule:

• if it should follow you everywhere, it belongs in SOUL.md
• if it belongs to a project, it belongs in AGENTS.md

SOUL.md is your durable default personality.

/personality is a session-level overlay that changes or supplements the current system prompt.

So:

• SOUL.md = baseline voice
• /personality = temporary mode switch

Examples:

• keep a pragmatic default SOUL, then use /personality teacher for a tutoring conversation
• keep a concise SOUL, then use /personality creative for brainstorming

Hermes ships with built-in personalities you can switch to with /personality.

CLI

/personality
/personality concise
/personality technical

Messaging platforms

/personality teacher

These are convenient overlays, but your global SOUL.md still gives Hermes its persistent default personality unless the overlay meaningfully changes it.

Built-in personalities are always available on every surface (CLI, messaging platforms, TUI, and the desktop app). You can add your own — or override a built-in by reusing its name — in ~/.hermes/config.yaml under agent.personalities.

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

Then switch to it with:

/personality codereviewer

Your selection is stored as a name in display.personality. Personalities never touch agent.system_prompt — that field is reserved for a manual system prompt you write yourself, and it applies only when no personality is selected.

To cancel the active personality overlay and return to base behavior (your SOUL.md persona, plus agent.system_prompt if you set one), use any of:

/personality none
/personality default
/personality neutral

All three clear the selection (display.personality) and the change takes effect on your next message. Running /personality with no arguments also lists none alongside the available presets and marks the active one.

A strong default setup is:

1. Keep a thoughtful global SOUL.md in ~/.hermes/SOUL.md
2. Put project instructions in AGENTS.md
3. Use /personality only when you want a temporary mode shift

That gives you:

• a stable voice
• project-specific behavior where it belongs
• temporary control when needed

At a high level, the prompt stack includes:

1. SOUL.md (agent identity — or built-in fallback if SOUL.md is unavailable)
2. tool-aware behavior guidance
3. memory/user context
4. skills guidance
5. context files (AGENTS.md, .cursorrules)
6. timestamp
7. platform-specific formatting hints
8. optional system-prompt overlays such as /personality

SOUL.md is the foundation — everything else builds on top of it.

• Context Files
• Configuration
• Tips & Best Practices
• SOUL.md Guide

Conversational personality and CLI appearance are separate:

• SOUL.md, agent.system_prompt, and /personality affect how Hermes speaks
• display.skin and /skin affect how Hermes looks in the terminal

For terminal appearance, see Skins & Themes.