---
title: SOUL.md — Introduction, Placement, and Three Approaches
type: concept
created: 2026-09-25
updated: 2026-09-25
tags: [kb, domain-ai, meta-reference, layer-concept]
sources: [raw/articles/soul-md-approach-official.md, raw/articles/soul-md-approach-community.md, raw/articles/soul-md-approach-personality.md]
confidence: high
contested: false
---

# SOUL.md — Agent Identity File (Hermes)

> Primary identity layer for Hermes Agent. Durable persona, not project rules. Slot #1 of the system prompt.

## What it is

`SOUL.md` is a plain Markdown file that defines the agent's identity — tone, style, boundaries, and communication defaults. It lives at the instance's `HERMES_HOME` (default `~/.hermes/SOUL.md`, here `/opt/data/` since `$HERMES_HOME=/opt/data`). Hermes loads it at session start, scans for injection patterns, truncates if too large, and injects verbatim into slot #1 of the system prompt (replacing the built-in default).

## Where it lives (in this environment)

- Global: `/opt/data/SOUL.md` (user-edited; replaced with sharp/blunt persona today — 2,752 bytes, 78 lines)
- Profile (isolated wiki profile): `/opt/data/profiles/wiki/SOUL.md` (667 bytes — original default text, untouched)
- Never loaded from CWD; only from `$HERMES_HOME`

## What belongs in SOUL.md vs elsewhere

Per official docs ([personality guide](https://hermes-agent.nousresearch.com/docs/user-guide/features/personality)):

| Belongs in SOUL.md | Belongs elsewhere |
|---|---|
| Tone, personality, style | Project conventions → `AGENTS.md` |
| Communication defaults | File paths/tools → `AGENTS.md` / `config.yaml` |
| Boundaries / "what to avoid" | Memory / user context → `MEMORY.md` / `USER.md` |
| Default behavior under ambiguity | Temporary mode → `/personality` overlay |

A useful rule: if it should follow you everywhere, SOUL.md; if it belongs to a project, AGENTS.md.

## Three contrasting approaches (sources ingested)

### Approach A — Official / Pragmatic ([official docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/personality))
- Stable identity, broad enough for many conversations, specific enough to shape voice.
- Focused on communication and identity, not task instructions.
- Uses `HERMES_HOME` exclusively; no CWD lookup.

### Approach B — Community / Template-Based ([Stanza course](https://www.stanza.dev/courses/hermes-personality/soul-md/hermes-personality-soul-identity-layer), [Dev Genius](https://blog.devgenius.io/how-to-play-with-soul-md-in-hermes-agent-135d1a36c9f9))
- Structured sections encouraged: Identity → Style → Technical Preferences → Ethical Boundaries.
- Size guideline: keep under ~1KB; 2,000-token cap enforced by framework.
- Workspace-level SOUL.md overrides allowed (highest-priority over global).
- Hard limits as prompt-injection defense emphasized.

### Approach C — Persona / Overlays ([official personality feature](https://hermes-agent.nousresearch.com/docs/user-guide/features/personality))
- SOUL.md = durable baseline; `/personality` = session-level overlay.
- Custom presets via `agent.personalities` in `config.yaml`.
- Profile isolation via `profiles/<name>/SOUL.md`.
- Personality name stored in display metadata; file stays in SOUL.md.

## Method (how to edit / use)

1. Edit `/opt/data/SOUL.md` with a text editor (current content is the sharp/blunt persona written by the user today).
2. Start a new session (`hermes` fresh) to apply — edits do NOT take effect in running sessions because the system prompt is cached at session start.
3. Verify with `cat /opt/data/SOUL.md`; use `hermes doctor` if behavior seems wrong.
4. For temporary mode switch (e.g., teacher, creative), use `/personality <name>` rather than editing SOUL.md.

## Related pages

- [[Moving Domain Email Away from Google Workspace]] — task where user asked to save reference docs; this profile's SOUL.md is part of that context
- [[Email Hosting]] — related config work
- `[[SOUL.md — User's Edited Version]]` (see /opt/data/SOUL.md directly — the user's sharp/blunt text from today's session)

## Notes / contradictions

- User's edited SOUL.md (2,752 bytes, 78 lines) is significantly longer than the default (668 bytes, 1 line) — matches Approach B's "long when load-bearing" philosophy.
- Profile SOUL.md (`profiles/wiki/`) remains at default — confirms profile isolation works as documented.
- No contradictions found between the three approaches; they describe different layers of the same system.