From 27a8ba42ed73d6c8af98ace165c853dbbedad97c Mon Sep 17 00:00:00 2001 From: Brandon Zarnitz Date: Mon, 4 May 2026 22:00:57 -0400 Subject: [PATCH] docs(prompt): clarify supported customization surfaces --- .../docs/developer-guide/prompt-assembly.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/website/docs/developer-guide/prompt-assembly.md b/website/docs/developer-guide/prompt-assembly.md index 047117fa7e..f23705870e 100644 --- a/website/docs/developer-guide/prompt-assembly.md +++ b/website/docs/developer-guide/prompt-assembly.md @@ -230,6 +230,30 @@ Long files are truncated before injection. The skills system contributes a compact skills index to the prompt when skills tooling is available. +## Supported prompt customization surfaces + +Most users should treat `agent/prompt_builder.py` as implementation code, not a configuration surface. The supported customization path is to change the prompt inputs Hermes already loads, rather than editing Python templates in place. + +### Use these surfaces first + +- `~/.hermes/SOUL.md` — replace the built-in default identity block with your own agent persona and standing behavior. +- `~/.hermes/MEMORY.md` and `~/.hermes/USER.md` — provide durable cross-session facts and user profile data that should be snapshotted into new sessions. +- Project context files such as `.hermes.md`, `HERMES.md`, `AGENTS.md`, `CLAUDE.md`, or `.cursorrules` — inject repo-specific working rules. +- Skills — package reusable workflows and references without editing core prompt code. +- Optional system prompt config / API overrides — add deployment-specific instruction text without forking Hermes. +- Ephemeral overlays such as `HERMES_EPHEMERAL_SYSTEM_PROMPT` or prefill messages — add turn-scoped guidance that should not become part of the cached prompt prefix. + +### When to edit code instead + +Edit `agent/prompt_builder.py` only if you are intentionally maintaining a fork or contributing upstream behavior changes. That file assembles the prompt plumbing, cache boundaries, and injection order for every session. Direct edits there are global product changes, not per-user prompt customization. + +In other words: + +- if you want a different assistant identity, edit `SOUL.md` +- if you want different repo rules, edit project context files +- if you want reusable operating procedures, add or modify skills +- if you want to change how Hermes assembles prompts for everyone, change Python and treat it as a code contribution + ## Why prompt assembly is split this way The architecture is intentionally optimized to: