From abdd0a46b2fb12afece91edaf889ae10e5255eeb Mon Sep 17 00:00:00 2001 From: Hermes Wiki Agent Date: Fri, 25 Sep 2026 07:03:18 +0100 Subject: [PATCH] =?UTF-8?q?Add:=20SOUL.md=20intro=20&=203=20approaches=20?= =?UTF-8?q?=E2=80=94=20sources=20ingested=20(official/community/persona)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- concepts/soul-md-introduction.md | 75 ++++++++++++++++++++ index.md | 1 + log.md | 7 ++ raw/articles/soul-md-approach-community.md | 16 +++++ raw/articles/soul-md-approach-official.md | 29 ++++++++ raw/articles/soul-md-approach-personality.md | 16 +++++ raw/articles/soul-md-introduction.md | 75 ++++++++++++++++++++ 7 files changed, 219 insertions(+) create mode 100644 concepts/soul-md-introduction.md create mode 100644 raw/articles/soul-md-approach-community.md create mode 100644 raw/articles/soul-md-approach-official.md create mode 100644 raw/articles/soul-md-approach-personality.md create mode 100644 raw/articles/soul-md-introduction.md diff --git a/concepts/soul-md-introduction.md b/concepts/soul-md-introduction.md new file mode 100644 index 0000000..1f2c36c --- /dev/null +++ b/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//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 ` 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. diff --git a/index.md b/index.md index 7d7802c..1a17eb5 100644 --- a/index.md +++ b/index.md @@ -21,6 +21,7 @@ - [[omarchy-flicker]] — flicker diagnosis + fixes (Intel Mac mini, continuous; unverified) ### Concepts (topics, techniques, patterns, categories) +- `[[SOUL.md — Introduction & Three Approaches]]` — agent identity file placement / method / 3 approaches (official + community + persona); raw sources ingested 2026-09-25 - `[[Moving Domain Email Away from Google Workspace]]` — full migration guide: choosing a host, steps, MX records, canceling Workspace - `[[Email Hosting]]` — options for hosting email for a custom domain - `[[MX Records]]` — DNS records that direct email delivery; key to switching providers diff --git a/log.md b/log.md index 9e18583..2b7bf02 100644 --- a/log.md +++ b/log.md @@ -38,3 +38,10 @@ - Raw source saved: raw/articles/google-workspace-mobile-account-migration.md - Entity page created: entities/google-workspace-protonmail.md - Index updated; new page count 7 + +## [2026-09-25] ingest | SOUL.md — Introduction & Three Approaches +- Raw sources: `raw/articles/soul-md-approach-*.md` (official docs, community/Stanza tutorial, personality/overlay feature docs) +- Page created: `concepts/soul-md-introduction.md` +- Index updated: `index.md` (added link under Concepts) +- Sources: official docs (high confidence), community guides (medium-high confidence) +- Note: user edited `/opt/data/SOUL.md` today (sharp/blunt persona, 2752 bytes); profile copy at `profiles/wiki/SOUL.md` remains at default (668 bytes) diff --git a/raw/articles/soul-md-approach-community.md b/raw/articles/soul-md-approach-community.md new file mode 100644 index 0000000..b81830e --- /dev/null +++ b/raw/articles/soul-md-approach-community.md @@ -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. diff --git a/raw/articles/soul-md-approach-official.md b/raw/articles/soul-md-approach-official.md new file mode 100644 index 0000000..0e5f4bd --- /dev/null +++ b/raw/articles/soul-md-approach-official.md @@ -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 diff --git a/raw/articles/soul-md-approach-personality.md b/raw/articles/soul-md-approach-personality.md new file mode 100644 index 0000000..003fa9c --- /dev/null +++ b/raw/articles/soul-md-approach-personality.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//`). + +## 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. diff --git a/raw/articles/soul-md-introduction.md b/raw/articles/soul-md-introduction.md new file mode 100644 index 0000000..1f2c36c --- /dev/null +++ b/raw/articles/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//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 ` 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.