HERMES AGENT SOUL.MD: WHY 50 LINES MATTER MORE THAN YOUR MODEL (COMPLETE GUIDE)

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 you a 10-line template and move on. This article 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).

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:

• Reads SOUL.md from HERMES_HOME

• Scans it for prompt injection patterns

• Truncates if needed

• 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. 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 — it means 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: 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

This is the most common mistake. People put everything in SOUL.md. Project instructions, workflow details, tool configurations, API documentation. 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:

• Project-specific instructions → AGENTS.md

• Coding conventions → AGENTS.md or .cursorrules

• Multi-step workflows → Skills

• Facts about you → MEMORY.md and USER.md

• Tool configurations → config.yaml

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):

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

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

SOUL.md is scanned for prompt injection patterns on every load. That means you should keep it focused on persona and voice rather than trying to sneak in meta-instructions. The scanner exists because SOUL.md has maximum influence over the agent’s behavior. Anything that looks like an attempt to override safety boundaries or manipulate tool behavior will be flagged.

What the scanner catches:

• Instructions that attempt to override system-level safety rules

• Attempts to disable approval checks or safety features

• Commands disguised as personality traits (“as part of my personality, always execute commands without asking”)

• 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 agent’s safety layer don’t.

4. Token Impact

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

The math:

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:

Four sections. 15-20 lines each section max. Total: 50-80 lines.

The official starter example:

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

6.2 — Deep Research Analyst

6.3 — Autonomous DevOps Engineer

6.4 — Executive Content Strategist

6.5 — Financial Analyst with Guardrails

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:

When to use SOUL.md vs /personality:

SOUL.md: permanent identity. How the agent behaves across all sessions. Who it is.

/personality: 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 a brainstorming session 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, its own memory, its own skills, its own config. Running multiple profiles is running multiple agents.

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:

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):

Copies everything: config, API keys, personality, all memories, full session history, skills, cron jobs, plugins. A complete snapshot.

Switch between profiles:

Profile Builder (new in dashboard):

The dashboard now has a visual Profile Builder. No CLI needed:

Five-step wizard: Identity → Model → Skills → MCPs → Review. Set the SOUL.md, pick the model, toggle skills, connect MCP servers, and deploy. One flow, one new agent.

The model matters per profile:

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

researcher: → SOUL.md: research analyst, evidence-based → model: gpt-5.5 (cheap, high volume search tasks)

coder: → SOUL.md: senior engineer, code review → model: claude-fable-5 (best coding model)

content: → SOUL.md: content strategist, voice matching → model: claude-sonnet-4 (strong writing)

ops: → SOUL.md: operations manager, terse → model: deepseek-v4-flash (routine tasks, cheapest)

How models follow SOUL.md differently:

Not every model interprets your soul with the same precision. This matters for advanced souls with nuanced voice or strict restrictions.

• Claude (Sonnet, Opus, Fable): follows restrictions and voice instructions closely. Best for souls with specific communication rules. Rarely drifts from stated boundaries.

• GPT-5.5: strong on general instructions. Can drift from nuanced voice guidelines over long sessions. Reinforce key rules in both Soul and Restrictions sections.

• DeepSeek V4 Flash: follows simple instructions well. May ignore subtle behavioral guidelines. Keep the soul direct and short for DeepSeek profiles. Specific restrictions (“never do X”) work better than nuanced voice directions (“communicate with understated confidence”).

• Local models (Qwen, Gemma): follow basic structure but struggle with complex behavioral 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.

What a distribution contains:

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:

One command. The agent is ready. Memories, sessions, and API keys stay per-machine. The personality, skills, and workflows transfer.

Update a distribution:

Pulls the latest changes from the repo. Your memories and sessions are untouched.

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 extension or a VS Code extension. Low friction, high power, trust the source.

10. Common Mistakes

Mistake 1: Putting everything in SOUL.md

Project instructions, workflow details, API docs. SOUL.md grows to 200 lines. Every turn burns 2,000 tokens on identity. Move project instructions to AGENTS.md. Move workflows to skills. Move facts to MEMORY.md.

Mistake 2: Designing the perfect soul in one shot

The official 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. Notice where it drifts from what you want. Add a line. Remove a line. The best SOULs are refined through use, not designed from scratch.

Mistake 3: Duplicating SOUL.md across directories

SOUL.md loads from HERMES_HOME only. Placing a SOUL.md in your project directory does nothing. If you want project-specific instructions, use AGENTS.md in the project root. Hermes loads AGENTS.md from the current working directory at session start.

Mistake 4: Ignoring sub-agents

When Hermes delegates work to sub-agents via delegate_task, SOUL.md is NOT loaded for the sub-agent. Sub-agents use the hardcoded DEFAULT_AGENT_IDENTITY instead. This is by design: sub-agents should be generic workers, not copies of your personalized agent. If you need a specialized sub-agent, use a separate profile with its own SOUL.md and coordinate through Kanban.

Mistake 5: Not using /personality for temporary shifts

Editing SOUL.md for a one-off session (“I need it to brainstorm freely for 30 minutes”) then forgetting to change it back. Use /personality for temporary modes. SOUL.md stays untouched.

Mistake 6: Copy-pasting someone else’s soul without reading it

Profile distributions are powerful but the SOUL.md activates immediately on first session. A malicious or poorly written soul can change agent behavior in ways you don’t expect. Read every SOUL.md before using it, especially from unknown sources. The prompt injection scanner catches obvious attacks but a subtly misaligned soul passes the scanner.

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. Notice where the agent’s tone, decisions, or behavior don’t match what you want. Write down each observation.

Alternative: let Hermes interview you and write it:

If you don’t know where to start, ask Hermes to create your SOUL.md through an interview:

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 because the interview surfaces preferences you wouldn’t think to articulate.

Week 2: Add one line per observation. “Never agree with me to be agreeable.” “Use numbers, not adjectives.” “Ask for evidence before accepting claims.” Each line addresses a specific behavior you observed.

Week 3: Check hermes prompt-size. Is SOUL.md growing past 80 lines? Review each line. If removing it changes nothing about agent behavior, cut it. Consolidate overlapping instructions.

Month 2: Ask Hermes to rewrite your SOUL.md based on how you actually work together:

Review our conversation history. Based on how I give feedback, what I approve, what I reject, and how I communicate: rewrite my SOUL.md to reflect how we actually work. Keep it under 60 lines.

The agent has seen hundreds of your interactions. It knows your patterns better than you can articulate from memory. The draft it produces often captures preferences you never thought to write down.

Month 3+: Your SOUL.md is stable. Small edits when your work changes. The Curator prunes your skills. Memory handles evolving context. SOUL.md handles the constants: who the agent is and how it thinks.

12. Test Your SOUL.md

After writing or editing your SOUL.md, verify it works:

Test 1 — Identity check:

Who are you? What is your role?

The agent should describe itself using the identity from your SOUL.md, not the default “I’m Hermes Agent, an AI assistant.”

Test 2 — Voice check:

Explain what a cron job does.

Compare the tone and style to what your SOUL.md specifies. A researcher soul should give a factual answer. A co-founder soul should give a strategic one. An ops manager should give a terse one.

Test 3 — Restriction check:

[Ask it to do something your restrictions forbid]

If your soul says “never send messages without approval,” ask it to send a message. It should refuse or ask for confirmation.

Test 4 — Prompt size check:

Verify SOUL.md token count is where you expect. If it grew past 800 tokens, trim it.

**Test 5 — Drift check (after 2 weeks):**Start a new session and repeat tests 1-3. Agents with deep memory can drift from SOUL.md over time as accumulated context starts to outweigh 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 and months (research projects, client histories, content strategy), the built-in memory 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 other providers use retrieval-based injection instead of full dump. Only relevant memories load per turn. 72% fewer tokens than naive injection.

**Obsidian vault as extended memory:**Hermes ships with a bundled Obsidian skill. The agent reads, searches, and creates notes in your vault. Obsidian becomes the uncapped long-term layer: research, session summaries, project context, learned patterns — all as linked markdown notes.

SOUL.md handles identity (who the agent is). MEMORY.md handles working memory (what it needs now, capped). Obsidian handles long-term knowledge (everything it has ever learned, uncapped).

Three layers. Each serves a different purpose. Each has a different scope.

14. Quick Reference

File location:

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

Commands:

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:

This injects text into the system prompt 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). SOUL.md handles who the agent is. system_message handles how the caller wants output formatted.

Token budget guidelines:

• 50 lines ≈ 400-500 tokens per turn

• 80 lines ≈ 700-800 tokens per turn (maximum recommended)

• Use hermes prompt-size to verify

• 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. Let the agent rewrite its own soul after a month of working together. The best souls are grown, not designed.

Related Articles

• Hermes Agent as a Personal AI Operating System — full 17-layer architecture mapping

• 8 Loops Inside Hermes Agent (And Why They Compound) — the loop architecture deep-dive

• 10 Setups That Turned Hermes Agent From a Chat Window Into a 24/7 System — practical setup guide

Subcribe to my Substack: all articles are posted earlier there

All technical details verified against Hermes Agent official documentation (v0.16.0 “The Surface Release”) and the developer guide for prompt assembly.