SOUL.md: Official Scope and Best Use

What SOUL.md is really for

The official guide defines SOUL.md as the primary identity file for a Hermes instance. That sounds simple, but many users still overload it with project policy that should live elsewhere.

What belongs there

• Tone and personality
• Communication style
• High-level behavioral boundaries

What does not belong there

Repo-specific commands, file paths, ports, and workflow rules should live in AGENTS.md, not in SOUL.md. In practice, keeping that boundary clean reduces cross-project confusion and makes long-lived behavior easier to reason about.

A strong SOUL.md usually contains

• A communication style that stays stable across projects
• A few durable behavioral constraints instead of a giant rulebook
• Enough identity to make the assistant recognizable without becoming rigid

Why people get this wrong

SOUL.md looks like the obvious place to put "everything important." But the more repo-specific detail you push into it, the harder it becomes to preserve a stable agent identity across different projects. The official split is useful because it keeps personality and project policy from contaminating each other.

Operator takeaway

If a rule should follow Hermes everywhere, consider SOUL.md. If it should only apply inside one repo or workspace, it probably belongs in AGENTS.md. That single filter prevents a lot of configuration drift.