SOUL.md vs Other Prompt Layers

+15 Mana ✨
Hermes File Layout(DOCUMENTATION)

Introduction

SOUL.md is one of several files Hermes injects into the prompt. The system works because each file has a different job. Confusing the jobs is the most common SOUL.md mistake: people put workflow rules where identity belongs, or scatter identity across project files. This lesson draws the lines clearly.

Key Concepts

  • SOUL.md: Global identity. Voice, values, communication style.
  • MEMORY.md: Cross-session environment and project facts (e.g., "this repo uses pnpm").
  • USER.md: Your profile (e.g., "Olivier, Europe/Paris, prefers short answers").
  • AGENTS.md (or CLAUDE.md, .hermes/agents.md): Project-specific guidance that lives inside a repo.
  • Skills: On-demand specialized workflows the agent activates when needed.

Real World Context

A team has three files mixing identity and project rules. SOUL.md says "You are a helpful coding assistant who uses British spelling, runs pnpm test before commits, and stores API keys in 1Password." That single sentence covers three different scopes. The British spelling is identity (global). The pnpm test rule is project-specific (belongs in AGENTS.md). The 1Password convention is user environment (belongs in USER.md). The agent sort of works, but adding a new project means rewriting SOUL.md, and switching machines breaks things in surprising places.

Deep Dive

The rule of thumb: ask "is this true for me everywhere?"

If yes, it is identity or user profile. If no (project-specific), it goes in AGENTS.md. If it is a workflow the agent activates only sometimes, it is a skill.

Here is how the same fact looks in each file:

text
SOUL.md       "You communicate in short, technical sentences."
USER.md       "Olivier prefers responses under 5 lines unless asked."
MEMORY.md     "User typically works in TypeScript and Go."
AGENTS.md     "This repo uses pnpm. Run `pnpm test` before commits."
Skill         "/codex review: run a code review using OpenAI Codex."

Notice how each entry stays in its lane. SOUL.md says how to communicate. USER.md says who you are. MEMORY.md says what tools you typically use. AGENTS.md says what this repo expects. A skill says what specialized workflow to run on demand.

Why is this separation worth the discipline? Because the four files have different lifecycles. SOUL.md changes maybe twice a year. USER.md updates when your circumstances change (new role, new team). MEMORY.md grows organically as the agent learns about your environment. AGENTS.md is per-repo. Skills are versioned and shipped. Mixing them means edits become risky: you cannot trim USER.md without worrying you might delete a project rule.

There is also a token-budget angle. SOUL.md is loaded everywhere, every session. A bloated SOUL.md taxes every conversation. AGENTS.md only loads when you are in that repo. MEMORY.md is capped (around 2,200 chars). Each file is sized for its job.

Common Pitfalls

  1. Personality stuffing: Putting tool preferences, file paths, or test commands in SOUL.md. These belong in AGENTS.md.
  2. Identity drift across machines: Maintaining different SOUL.md content on different laptops because you treated SOUL.md like local config. Identity should be portable.

Best Practices

  1. Audit by question: For each line in SOUL.md, ask "is this true for me in every repo on every machine?". If not, move it.
  2. Cross-link between files when needed: If your SOUL.md says "defer to project conventions when present," the agent will respect AGENTS.md without you needing to redeclare rules.

Summary

  • SOUL.md holds global identity; AGENTS.md holds project-specific guidance; USER.md is your profile; MEMORY.md is cross-session facts; skills are on-demand workflows.
  • Each file has a different lifecycle and capacity, sized for its job.
  • Mixing scopes makes editing risky and bloats the prompt.
  • Keep SOUL.md narrow: voice, values, and how-you-communicate rules only.

Code Examples

bash
# A clean Hermes config layout, file by file
~/.hermes/
├── SOUL.md          # Identity: voice, values, style. ~20-60 lines.
├── config.yaml      # Runtime: providers, defaults, custom personas.
└── memories/
    ├── MEMORY.md    # Cross-session environment facts (~2200 char cap)
    └── USER.md      # Your profile (~1375 char cap)

# Per-repo overrides live in the repo, not in ~/.hermes:
~/code/api/AGENTS.md     # Project conventions, test commands, repo rules
✓ Completed