soul.md
What it is
Persistent identity and boundary instructions that shape the agent’s behavior.
In plain terms
Picture someone whose core personality doesn’t shift depending on who’s in the room — the same humor, values, and personal boundaries show up whether they’re at a job interview, texting a friend, or catching up with family. SOUL.md gives Hermes that same constancy: a single identity file the agent reads before anything else, so tone and boundaries hold steady whether it’s answering in a terminal, a chat platform, or a scheduled job.
Why it matters
SOUL.md holds what’s meant to stay true no matter which session, project, or platform the agent is currently operating in — identity, tone, hard boundaries — as distinct from the optional BOOT.md hook pattern’s gateway-startup checklist or a skill’s instructions for one specific job. It functions as something close to a constitution: standard operating procedures and individual skills are expected to operate inside the boundaries SOUL.md sets, not override them. When an agent’s behavior feels ‘off’ in a way no single skill explains, SOUL.md is usually where to look first.
How it works
SOUL.md occupies the very first slot of the system prompt’s stable tier, which is built once per session and reused for every turn after that (agent/system_prompt.py). If the file exists at HERMES_HOME and has content, load_soul_md() reads it and that text becomes the agent’s identity; if it’s missing or empty, Hermes falls back to a hardcoded default identity that reads word-for-word identical to the text new installs get seeded with (agent/prompt_builder.py, hermes_cli/default_soul.py). Because identity loads before tool guidance, the skills prompt, or memory, everything layered on top — a skill’s own instructions, a platform hint, a remembered fact — operates inside whatever tone and boundaries SOUL.md already set, rather than the other way around.
A concrete example
Add one line to ~/.hermes/SOUL.md: never suggest deleting files without explicit confirmation, and keep replies under five sentences unless detail is requested. From the next session on, every reply — whether triggered from the CLI, a Telegram message, or a scheduled cron job — stays terse and asks before anything destructive, even when whatever skill is currently loaded says nothing about that boundary at all. The identity travels with the agent no matter which surface or skill happens to be active.
How it connects
This note belongs to the Skills family. Its closest neighboring concepts are: Standard Operating Procedures, BOOT.md, Agent Runtime, Personal OS.
Source evidence
vendor/hermes-agent/agent/skill_utils.py#<file>— Structural Source Map fallback for agent/skill_utils.py. A core source file in the Skill Discovery and Invocation structure within Skills and Plugins.
Workflows
- No first-pass workflow mapping yet; this concept still appears in the vault graph through articles and source evidence.
Related articles
- No article currently mentions this concept by name/alias often enough to qualify (see mention-mining policy).