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

2026-09-25 07:03:18 +01:00
parent 7e9e77e161
commit abdd0a46b2
7 changed files with 219 additions and 0 deletions
@@ -0,0 +1,16 @@
+# Raw Source: SOUL.md — Approach B (Community / Template-Based)
+
+Source: https://www.stanza.dev/courses/hermes-personality/soul-md/hermes-personality-soul-identity-layer
+Source: https://blog.devgenius.io/how-to-play-with-soul-md-in-hermes-agent-135d1a36c9f9
+Type: community tutorials / educational guides
+Confidence: medium-high (secondary sources referencing official docs)
+Date collected: 2026-09-25
+
+## Summary
+Community tutorials emphasize that SOUL.md is an "identity layer" — separate from preferences (USER.md), operating procedures (AGENTS.md), tool notes (TOOLS.md), and memory (MEMORY.md). The recommended structure: Identity → Style → Technical Preferences → Ethical Boundaries. Keep it under ~1KB / 2,000 tokens; it competes for context window space.
+
+## Key differences from official guidance
+- More structured section headings encouraged (Identity, Communication Style, Technical Preferences, Ethical Boundaries).
+- Explicit size guideline: under 1KB preferred; 2,000 token cap enforced by framework.
+- More emphasis on per-project workspace-level SOUL.md overrides (workspace SOUL.md wins over global).
+- Stronger focus on "hard limits as prompt-injection defense" — using negative rules ("Never do X") as security layer.
@@ -0,0 +1,29 @@
+# Raw Source: SOUL.md Introduction & Methods — Approach A (Official / Pragmatic)
+
+Source: https://hermes-agent.nousresearch.com/docs/user-guide/features/personality
+Source: https://hermes-agent.nousresearch.com/docs/guides/use-soul-with-hermes
+Type: official documentation (Nous Research / Hermes Agent)
+Confidence: high (primary source)
+Date collected: 2026-09-25
+
+## Summary
+SOUL.md is the agent's primary identity file at `~/.hermes/SOUL.md` (or `$HERMES_HOME/SOUL.md`). It lives at slot #1 of the system prompt — the first text the model sees before any user message. It defines tone, personality, communication style, and how the agent handles uncertainty, disagreement, and ambiguity.
+
+## Key rules
+- Load path: ONLY from `HERMES_HOME` (never from cwd).
+- Never overwritten by Hermes; starter file auto-seeded if missing.
+- Empty/missing file → falls back to built-in default identity.
+- Scanned for prompt injection before inclusion; content injected verbatim after truncation.
+- Stable identity: durable voice, not project-specific rules.
+
+## What goes in SOUL.md (official recommendation)
+- Identity / who the agent is
+- Style / how it communicates
+- Avoid / stylistic prohibitions
+- Defaults / behavior under ambiguity
+
+## What does NOT go in SOUL.md
+- Project conventions → AGENTS.md
+- File paths, repo rules → AGENTS.md
+- Tool preferences / commands → AGENTS.md or config.yaml
+- Memory / user context → MEMORY.md / USER.md
@@ -0,0 +1,16 @@
+# Raw Source: SOUL.md — Approach C (Persona / Personality-Driven)
+
+Source: https://hermes-agent.nousresearch.com/docs/user-guide/features/personality (built-in personalities / /personality overlay section)
+Source: https://hermes-agent.nousresearch.com/docs/guides/use-soul-with-hermes (SOUL.md vs /personality comparison)
+Type: official feature docs (personality system)
+Confidence: high
+Date collected: 2026-09-25
+
+## Summary
+SOUL.md defines the durable baseline identity. `/personality` provides session-level overlays. The framework supports custom personality presets defined in `config.yaml` (`agent.personalities`). Each profile can have its own `SOUL.md` (via profile directory under `profiles/<name>/`).
+
+## Key differences
+- SOUL.md = durable identity; /personality = temporary mode switch.
+- Profile-level SOUL.md isolation: `hermes profile create --clone` creates independent persona files.
+- Personality presets defined in YAML (`agent.personalities:`) apply to the whole session without touching SOUL.md file.
+- Personality names are stored in display metadata; personal files stay in SOUL.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.