How SOUL.md Shapes the System Prompt

+15 Mana ✨
Hermes Prompt Stack(DOCUMENTATION)

Introduction

Knowing SOUL.md exists is not enough. To use it well you need a mental model of where it lands in the prompt and what it competes with. The short answer: SOUL.md is slot one. It is the very first thing the model reads about who it is, and nothing wraps around it. That position is what makes SOUL.md powerful and also what makes it easy to misuse.

Key Concepts

  • Prompt stack: The ordered sequence of content Hermes assembles into the system prompt before the conversation begins.
  • Slot #1 (identity): The first block of the prompt, replaced by SOUL.md when present.
  • Verbatim injection: Hermes does not add wrapper language ("You are configured with the following personality...") around your SOUL.md. The text is dropped in as-is.
  • Downstream blocks: Tool guidance, memory snapshots, skills, and project context files sit below slot #1 in the prompt order.

Real World Context

A developer adds "You must use British English spelling" to SOUL.md and notices it carries through every response, including code comments, even in repos where AGENTS.md says nothing about spelling. That is slot #1 in action. The earlier in the prompt a rule appears, the more reliably the model treats it as identity rather than as a project-specific guideline that can be overridden.

Deep Dive

Here is how Hermes assembles the system prompt at session start:

text
┌─────────────────────────────────────────────────────────┐
│  Slot #1: Identity (SOUL.md, or built-in default)       │
├─────────────────────────────────────────────────────────┤
│  Slot #2: Tool guidance (how to call tools, formatting) │
├─────────────────────────────────────────────────────────┤
│  Slot #3: Persistent memory (MEMORY.md + USER.md)       │
├─────────────────────────────────────────────────────────┤
│  Slot #4: Skills register (if any are active)           │
├─────────────────────────────────────────────────────────┤
│  Slot #5: Project context (AGENTS.md, CLAUDE.md, etc.)  │
├─────────────────────────────────────────────────────────┤
│  Conversation turns begin here                          │
└─────────────────────────────────────────────────────────┘

A few consequences follow from this ordering.

First, SOUL.md sets the baseline voice. If SOUL.md says "be terse," later layers can ask for more detail, but the default cadence is terse. The model treats slot #1 as character, not as a single-turn instruction.

Second, there is no wrapper text. Hermes does not prepend "The user has configured you with the following personality:" to your SOUL.md. The content is the identity. That is why even a one-line SOUL.md ("You are a precise, dry technical assistant") works.

Third, lower slots can layer on top of SOUL.md but rarely override it. A memory entry saying "I prefer terse answers" reinforces a terse SOUL.md and conflicts with a chatty one. The agent will usually try to honor both, which is why coherence between SOUL.md and persistent memory matters.

Finally, slot #1 is the only place where you fully replace identity. Tool guidance, memory, and project context can shape behavior, but they cannot replace who the agent is. That is SOUL.md's job.

Common Pitfalls

  1. Putting workflow rules in SOUL.md: "Always run pnpm test before commits" is a workflow instruction, not identity. It belongs in AGENTS.md. SOUL.md should describe voice and values, not commands.
  2. Writing a wrapper that fights Hermes: Phrasing like "The user wants you to behave as follows..." wastes tokens. The slot already implies that. Write as the persona, not about the persona.

Best Practices

  1. Write SOUL.md in second-person imperative or descriptive identity: "You are direct and dry" or "Be direct and dry" both work. Avoid meta-language like "the assistant should...".
  2. Keep voice rules above behavior rules: When you read your SOUL.md top to bottom, voice and values should come first, specific behavior constraints (no emoji, no hype) after.

Summary

  • SOUL.md occupies slot #1 of the system prompt and is injected verbatim, without wrapper language.
  • The prompt stack below SOUL.md adds tool guidance, memory, skills, and project context in that order.
  • Slot #1 sets the baseline voice; later layers shape but rarely replace it.
  • Workflow and project rules belong in lower slots (AGENTS.md), not in SOUL.md.

Code Examples

markdown
# Personality
You are an experienced backend engineer's pair-programming partner.

## Voice
- Speak plainly. Prefer one sentence over three.
- Use precise terminology (idempotent, invariant, race, deadlock) without softening.

## Values
- Truth over praise. Disagree if you have a reason.
- Admit uncertainty rather than fabricate.

## Behavior
- No emoji. No exclamation marks. No hype.
- Confirm before destructive shell commands.
✓ Completed