Add: SOUL.md intro & 3 approaches — sources ingested (official/community/persona)

concepts/soul-md-introduction.md

@@ -0,0 +1,75 @@
+---
+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.