Hermes Agent SOUL.md: Why 50 Lines Matter More Than Your Model

SOUL.md is the most important file in your Hermes Agent setup. It occupies slot #1 in the system prompt — every turn, every session, every profile reads it first. It defines who the agent is before anything else loads.

Most guides show a 10-line template and move on. This one goes deeper: where SOUL.md sits in the prompt architecture, what belongs in it (and what does not), how to write advanced souls for different roles, how it affects your token budget, and how to share entire agent personas through profile distributions.

All technical details verified against Hermes Agent official documentation (v0.16.0 "The Surface Release").

1. What SOUL.md Actually Is

SOUL.md is a markdown file that completely replaces the built-in default agent identity. When Hermes starts a session, it:

1. Reads SOUL.md from HERMES_HOME
2. Scans it for prompt injection patterns
3. Truncates if needed
4. Injects it as slot #1 in the system prompt

If the file is missing, empty, or cannot be read, Hermes falls back to a built-in default: "You are Hermes Agent, an intelligent AI assistant..."

Hermes auto-seeds a starter SOUL.md on first install, so most users begin with a real file they can read and edit immediately.

Important: Changes to SOUL.md take effect on a new session. Existing sessions may still use the old prompt state. After editing your soul, start a fresh session to see the changes.

Location:

~/.hermes/SOUL.md                           # default profile
~/.hermes/profiles/researcher/SOUL.md       # named profile
~/.hermes/profiles/ops/SOUL.md              # named profile

SOUL.md always loads from HERMES_HOME, not from your current working directory. If it loaded from whatever directory you launched Hermes in, your personality could change unexpectedly between projects. The personality belongs to the Hermes instance itself.

2. Where SOUL.md Sits in the Prompt Stack

Understanding the full prompt assembly is critical for writing an effective SOUL.md. The system prompt is built in three layers.

Layer 1 — Stable (cached, rarely changes):

SOUL.md (identity)
→ tool and model guidance
→ skills prompt (names + descriptions index)
→ environment hints
→ platform hints

Layer 2 — Context (project-specific):

system_message (caller-supplied)
→ AGENTS.md (from current working directory)
→ .hermes.md, CLAUDE.md, .cursorrules (project files)

Hermes reads multiple context file formats from your working directory: AGENTS.md, .hermes.md, CLAUDE.md, and .cursorrules. If you use Cursor or Claude Code alongside Hermes and have .cursorrules in your project, Hermes will read them too. This is intentional — project conventions stay consistent across tools. But it also means instructions in .cursorrules affect Hermes behavior. If the agent acts differently in one project directory, check for context files you didn't write for Hermes.

Layer 3 — Volatile (changes per session):

MEMORY.md snapshot
→ USER.md snapshot
→ external memory provider block
→ timestamp / session / model / provider line

Final system prompt order: stable → context → volatile. SOUL.md is the very first thing — it sets the frame through which the model interprets everything that follows. A soul that says "you are a meticulous code reviewer" changes how the agent reads AGENTS.md, how it interprets skills, and how it responds to every message.

3. The Rules: What Goes In and What Does Not

The most common mistake is putting everything in SOUL.md — project instructions, workflow details, tool configurations, API docs. SOUL.md balloons to 200+ lines and eats tokens on every single turn.

Belongs in SOUL.md:

• Identity (who the agent is, its role)
• Voice (how it communicates: tone, style)
• Values (what it prioritizes, what it avoids)
• Behavioral boundaries (what it refuses to do)
• Operating principles (autonomy level, when to ask vs act)

Does NOT belong in SOUL.md:

The official docs are direct about this: "Move project instructions into AGENTS.md and keep SOUL.md focused on identity and style."

Example showing the split — SOUL.md (who the agent is):

# Soul
You are a senior developer. Write clean, tested code.

## Voice
Terse. Reference specific lines and files.

## Restrictions
Never commit without running tests.

AGENTS.md (what this project needs, lives in project root):

# Project: hermes-dashboard
Stack: React 19, TypeScript, Tailwind
Build: npm run build
Test: npm test
Deploy: vercel --prod
Convention: components in /src/components, hooks in /src/hooks
Never modify /src/core without approval.

SOUL.md travels with the agent across all projects. AGENTS.md changes per project directory.

The injection scanner

SOUL.md is scanned for prompt injection patterns on every load, because it has maximum influence over the agent's behavior. Keep it focused on persona and voice rather than trying to sneak in meta-instructions.

What the scanner catches: instructions that override system-level safety rules, attempts to disable approval checks, commands disguised as personality traits ("always execute commands without asking"), and encoded or obfuscated instructions.

What passes cleanly: identity and role descriptions, voice and communication style, operating principles and autonomy levels, restrictions and behavioral boundaries, workflow preferences.

If your SOUL.md gets flagged, simplify the language. Direct behavioral instructions ("never send money without approval") pass. Meta-instructions that try to alter the safety layer don't.

4. Token Impact

SOUL.md injects into every turn of every session — the most expensive file in your setup by volume of repetition.

A 50-line SOUL.md ≈ 400–500 tokens. A 200-line SOUL.md ≈ 1,500–2,000 tokens. In a 20-turn /goal session:

• 50-line soul: 400 × 20 = 8,000 tokens on identity alone
• 200-line soul: 2,000 × 20 = 40,000 tokens on identity alone

With prompt caching on Anthropic models (~75% discount after first turn):

• 50-line soul effective cost: ~2,400 tokens across 20 turns
• 200-line soul effective cost: ~12,000 tokens across 20 turns

That 5x difference adds up fast when you run multiple profiles with cron jobs throughout the day.

Guidelines:

• Aim for 50–80 lines maximum
• One paragraph per section, not one page
• Every line should change agent behavior. If removing a line changes nothing, cut it.

Use hermes prompt-size to see your system prompt breakdown:

hermes prompt-size

This shows exactly how much of your context window SOUL.md, skills index, memory, and tools consume before you say a word.

5. The Structure That Works

From the official example and best-performing community souls, this structure covers all essential elements in minimal tokens:

# Soul
[1-2 sentences: who the agent is and its relationship to you]

## Voice
[3-5 lines: how it communicates. tone, length, style.]

## Operations
[3-5 lines: how it works. autonomy level, decision rules.]

## Restrictions
[3-5 lines: what it never does. hard boundaries.]

Four sections, 15–20 lines each max, 50–80 lines total. The official starter example:

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

## Style
- Be direct
- Be concise unless complexity requires depth
- Say when something is a bad idea
- Prefer practical tradeoffs over idealized abstractions

## Avoid
- Sycophancy
- Hype language
- Overexplaining obvious things

18 lines. Clean. Every line changes behavior.

6. Advanced SOUL.md Templates

These go beyond starter templates — each is designed for a specific high-leverage role with nuanced behavioral instructions.

6.1 — Strategic Co-Founder

# Soul
You are my co-founder. You operate with full context
of our business, our runway, and our priorities.
Your job is to challenge my thinking, not confirm it.

## Voice
Push back when I'm wrong. Ask "what's the evidence?"
before accepting any assumption. Use numbers.
Speak in short declarative sentences.
If you disagree, say it in the first sentence,
then explain why.

## Operations
Before any major recommendation, check:
does this move the needle on our current 90-day goal?
If it doesn't, flag it as a distraction.
Default to action over analysis.
When I ask for options, rank them by expected impact
per hour invested. Cut anything below the threshold.

## Restrictions
Never agree with me to be agreeable.
Never recommend more than 3 priorities at once.
Never skip the "what could go wrong" assessment
on any plan that takes more than a week to execute.
Never use the words "potentially" or "arguably."

6.2 — Deep Research Analyst

# Soul
You are a research analyst with access to the internet,
databases, and files. Your output is evidence, not opinion.

## Voice
Cite sources for every factual claim.
Distinguish between verified facts, informed estimates,
and speculation. Label each explicitly.
Use "I could not verify this" when evidence is weak.
Prefer tables for comparisons. Prefer numbers for scale.

## Operations
Search across minimum 5 sources per question.
Cross-reference conflicting information.
When sources disagree, present both positions
with the evidence for each.
Flag confidence level: high (multiple verified sources),
medium (single credible source), low (unverified or conflicting).

## Restrictions
Never present an unverified claim as fact.
Never skip source attribution.
Never speculate without labeling it as speculation.
Never use "many experts say" without naming them.

6.3 — Autonomous DevOps Engineer

# Soul
You are a DevOps engineer responsible for deployment,
monitoring, and infrastructure. You operate autonomously
on routine tasks. You escalate anything that could
cause downtime or data loss.

## Voice
Terse. Log-style updates.
"Deployed v2.3.1 to staging. 4 tests passing. 1 flaky.
Holding prod deploy until flaky test resolved."

## Operations
Run all changes through staging before production.
Run tests before and after every deployment.
If tests fail, rollback and report.
For infrastructure changes: dry-run first,
show the diff, wait for my approval.
Monitor error rates for 15 minutes after any deploy.

## Restrictions
Never deploy to production without running tests.
Never modify database schemas without explicit approval.
Never store credentials in code or chat.
If any action could cause data loss, stop and ask.

6.4 — Executive Content Strategist

# Soul
You are my content strategist. You know my voice,
my audience, and what performs. Your job is to
find angles worth publishing and draft content
that matches how I write.

## Voice
Match my voice exactly. Short sentences.
Numbers over adjectives. Proof over claims.
No corporate language. No hype without data.
Read my recent posts before writing anything.
If my voice has evolved, match the latest version.

## Operations
Before drafting: check trending topics, check competitor
content from the last 7 days, check my recent posts
(avoid repeats within 14 days).
Score every draft on two axes: hook strength (1-10)
and bookmark value (1-10). Rewrite anything below 7.
Send drafts to Telegram for approval. Never publish
without my confirmation.

## Restrictions
Never publish without my explicit approval.
Never reuse a hook pattern from my last 5 posts.
Never use adverbs.
Never fabricate engagement numbers or results.

6.5 — Financial Analyst with Guardrails

# Soul
You are a financial analyst. You work with real money.
Accuracy is non-negotiable. Every number must be
traceable to a source.

## Voice
Present findings as: metric, source, date, confidence.
"Revenue: $2.3M (Q1 2026 10-K filing, high confidence)"
Round only when precision doesn't matter.
Use tables for any comparison involving more than 2 items.

## Operations
Pull data from official filings (SEC, annual reports)
before using third-party estimates.
When building projections, state every assumption
explicitly. Show sensitivity analysis on the top 3
assumptions that drive the model.
Flag any metric where the margin of error exceeds 10%.

## Restrictions
Never present a projection without stating assumptions.
Never use a single data point as a trend.
Never round numbers from financial statements.
Never provide investment advice or recommendations.
Always include a disclaimer on any forward-looking analysis.

7. /personality Overlays

SOUL.md is your durable baseline. /personality is a session-level overlay that temporarily modifies behavior without changing the underlying identity.

/personality codereviewer

This loads a named personality from config.yaml on top of SOUL.md for the current session only. When you start a new session, the overlay is gone and SOUL.md is back.

Built-in presets (ship with Hermes):

/personality              # reset to SOUL.md baseline
/personality concise      # shorter, terser responses
/personality technical    # detailed, precise, engineering-focused

Define custom personalities in config.yaml:

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

    brainstorm: >
      Forget constraints for this session.
      Generate ideas freely. Quantity over quality.
      No filtering, no feasibility checks.
      We'll evaluate later.

    editor: >
      You are a ruthless editor.
      Cut every unnecessary word.
      Shorten every sentence that can be shorter.
      Flag every claim without evidence.

When to use which: SOUL.md is permanent identity — how the agent behaves across all sessions, who it is. /personality is a temporary mode — this session needs a different approach, switch back next session. Example: your SOUL.md defines a strategic co-founder, but right now you need brainstorming without the usual pushback. Use /personality brainstorm for this session. Tomorrow, the co-founder is back.

8. Profiles: Multiple Souls on One Machine

Each Hermes profile gets its own SOUL.md, memory, skills, and config. Running multiple profiles is running multiple agents.

hermes profile create researcher
hermes profile create coder
hermes profile create ops

Each profile now has:

~/.hermes/profiles/researcher/
├── SOUL.md          # researcher identity
├── config.yaml      # model: gpt-5.5
├── .env             # API keys
├── memories/        # researcher-specific memory
├── skills/          # researcher-specific skills
└── cron/            # researcher-specific schedules

Clone from an existing profile:

hermes profile create work --clone

Copies config.yaml, .env, and SOUL.md into the new profile — same API keys and model, but fresh sessions and memory. Edit the SOUL.md to change the personality.

Full clone (everything — config, keys, personality, all memories, full session history, skills, cron, plugins):

hermes profile create backup --clone --clone-from coder

Switch between profiles (each named profile becomes its own command):

hermes                  # default profile
researcher              # named profile
coder chat              # start a session as coder
ops gateway start       # connect ops to Telegram

Profile Builder (new in dashboard): a visual five-step wizard — Identity → Model → Skills → MCPs → Review — with no CLI needed:

hermes dashboard → Profiles → Build

The model matters per profile

Different roles need different models. Match the model to the soul:

How models follow SOUL.md differently

• Claude (Sonnet, Opus, Fable): follows restrictions and voice instructions closely. Best for souls with specific communication rules. Rarely drifts.
• GPT-5.5: strong on general instructions, but can drift from nuanced voice over long sessions. Reinforce key rules in both Soul and Restrictions.
• DeepSeek V4 Flash: follows simple instructions well, may ignore subtle behavioral guidelines. Keep the soul direct and short. Specific restrictions ("never do X") beat nuanced voice ("communicate with understated confidence").
• Local models (Qwen, Gemma): follow basic structure but struggle with complex rules. Use the simplest possible soul; focus on restrictions over voice.

If your agent keeps ignoring a restriction, the fix is often switching to a model that follows instructions more precisely, rather than making the soul longer.

9. Profile Distributions: Share an Entire Agent

A profile distribution packages a complete Hermes agent as a git repo. Anyone with access can install the whole agent with one command.

my-research-agent/
├── distribution.yaml   # manifest: name, version, requirements
├── SOUL.md             # the agent's personality
├── config.yaml         # model, temperature, tool defaults
├── skills/             # bundled skills
├── cron/               # scheduled tasks
└── mcp.json            # MCP server connections

Install a distribution:

hermes profile install github.com/you/my-research-agent

One command and the agent is ready. Memories, sessions, and API keys stay per-machine; the personality, skills, and workflows transfer. Update with:

hermes profile update researcher

Security note from official docs: "SOUL.md and skills ARE active as soon as you start chatting with the profile, so read them before your first run if you're installing from someone you don't know." This is analogous to installing a browser or VS Code extension — low friction, high power, trust the source.

10. Common Mistakes

1. Putting everything in SOUL.md. Project instructions, workflows, API docs balloon it to 200 lines and burn 2,000 tokens per turn. Move project instructions to AGENTS.md, workflows to skills, facts to MEMORY.md.
2. Designing the perfect soul in one shot. The docs say it directly: "That iterative approach works better than trying to design the perfect personality in one shot." Start with 20 lines, use Hermes for a week, then refine.
3. Duplicating SOUL.md across directories. SOUL.md loads from HERMES_HOME only. A SOUL.md in your project directory does nothing — use AGENTS.md for project instructions.
4. Ignoring sub-agents. When Hermes delegates via delegate_task, SOUL.md is NOT loaded for the sub-agent — it uses the hardcoded DEFAULT_AGENT_IDENTITY instead. This is by design: sub-agents are generic workers. For a specialized sub-agent, use a separate profile and coordinate through Kanban.
5. Not using /personality for temporary shifts. Editing SOUL.md for a one-off session then forgetting to change it back. Use /personality for temporary modes; SOUL.md stays untouched.
6. Copy-pasting someone else's soul without reading it. A distribution's SOUL.md activates immediately on first session. Read every SOUL.md before using it, especially from unknown sources. The injection scanner catches obvious attacks, but a subtly misaligned soul passes.

11. The Iterative Method

The best SOUL.md is not written — it is grown.

• Week 1: Start with the official starter template (18 lines). Use Hermes normally. Note where the agent's tone, decisions, or behavior don't match what you want.
• Week 2: Add one line per observation. "Never agree with me to be agreeable." "Use numbers, not adjectives." Each line addresses a specific observed behavior.
• Week 3: Check hermes prompt-size. Growing past 80 lines? Review each line; if removing it changes nothing, cut it. Consolidate overlapping instructions.
• Month 2: Ask Hermes to rewrite your SOUL.md based on how you actually work together. It has seen hundreds of your interactions and knows your patterns.
• Month 3+: Your SOUL.md is stable. Small edits when your work changes. The Curator prunes skills, memory handles evolving context, SOUL.md handles the constants.

Let Hermes interview you and write it if you don't know where to start:

I want you to write a SOUL.md for yourself.
Interview me about:
- what kind of work I do
- how I want you to communicate
- what decisions you can make on your own
- what you should never do
- how to handle situations when things break

Ask one question at a time.
When you have enough context, write a SOUL.md
under 60 lines with sections:
Soul, Voice, Operations, Restrictions.

The agent asks 5–8 questions, then produces a soul based on your actual answers — often sharper than what you'd write from scratch.

12. Test Your SOUL.md

After writing or editing, verify it works:

• Identity check: "Who are you? What is your role?" — the agent should describe itself using your SOUL.md, not the default.
• Voice check: "Explain what a cron job does." — compare tone and style to what your SOUL.md specifies.
• Restriction check: ask it to do something your restrictions forbid. If your soul says "never send messages without approval," it should refuse or ask for confirmation.
• Prompt size check: hermes prompt-size — verify SOUL.md token count is where you expect. Past 800 tokens? Trim it.
• Drift check (after 2 weeks): start a new session and repeat the identity/voice/restriction tests. Agents with deep memory can drift as accumulated context outweighs the identity block. If drift happens, the soul needs sharper language or the memory needs pruning.

13. SOUL.md and Long-Term Memory

SOUL.md defines who the agent is. Memory defines what it knows. Both are capped. For work that accumulates knowledge over weeks (research projects, client histories, content strategy), the built-in caps (2,200 chars for MEMORY.md, 1,375 chars for USER.md) can become a bottleneck.

Two extensions that work alongside SOUL.md:

• External memory providers: Mem0, Honcho, and 6 others use retrieval-based injection instead of full dump. Only relevant memories load per turn — ~72% fewer tokens than naive injection. Set up with hermes memory setup.
• Obsidian vault as extended memory: Hermes ships with a bundled Obsidian skill. The agent reads, searches, and creates notes in your vault, making Obsidian the uncapped long-term layer.

Three layers, each with a different scope: SOUL.md = identity (who the agent is), MEMORY.md = working memory (what it needs now, capped), Obsidian = long-term knowledge (everything it has ever learned, uncapped).

14. Quick Reference

File location:

~/.hermes/SOUL.md                    # default profile
~/.hermes/profiles/NAME/SOUL.md      # named profile

Commands:

hermes prompt-size              # see token breakdown
/personality NAME               # temporary overlay
/personality                    # clear overlay, back to SOUL.md
hermes profile create NAME      # new profile with own SOUL.md
hermes profile install URL      # install shared agent

Prompt stack order:

SOUL.md → tool guidance → skills index → env hints
→ AGENTS.md / .cursorrules / .hermes.md
→ MEMORY.md → USER.md → timestamp

Alternative: system_message in config.yaml — injects text alongside SOUL.md. Use it for instructions that apply to all sessions but don't belong in the identity file (API conventions, output format rules):

agent:
  system_message: "Additional instructions appended after SOUL.md"

Token budget guidelines:

• 50 lines ≈ 400–500 tokens per turn
• 80 lines ≈ 700–800 tokens per turn (maximum recommended)
• Prompt caching on Anthropic: ~75% off after first turn

What goes where:

SOUL.md    → who the agent is (identity, voice, values)
AGENTS.md  → what the project needs (instructions, conventions)
MEMORY.md  → what the agent learned (facts, preferences)
USER.md    → who you are (profile, context)
Skills     → how to do things (procedures, workflows)

Conclusion

SOUL.md is 50–80 lines of text that define everything about how your Hermes Agent thinks, speaks, and operates. It is the most leveraged file in your setup — one line added or removed can change agent behavior across every future session.

The difference between a useful agent and a frustrating one usually comes down to SOUL.md. Not the model. Not the tools. Not the prompt engineering. The identity. Start with 20 lines, iterate from experience, and let the agent rewrite its own soul after a month of working together. The best souls are grown, not designed.

Verified against Hermes Agent official documentation (v0.16.0 "The Surface Release") and the developer guide for prompt assembly.