Prompt Assembly, Stability, and Context Layers

Hermes builds the system prompt from ordered layers rather than one mutable template. Understanding those layers prevents duplicated context, surprising precedence, and unnecessary cache invalidation.

Official documentation: https://hermes-agent.nousresearch.com/docs/developer-guide/prompt-assembly

Layered prompt design

Stable identity and tool-aware behavior form the reusable prefix. User-defined system text, skills, memory snapshots, and project context are assembled in a defined order. Session, timestamp, and platform guidance complete the session-level prompt, while truly per-call material stays outside the cached system prefix.

Project context uses a priority path rather than concatenating every compatible file. A Hermes-native context file can take precedence over AGENTS.md, CLAUDE.md, or Cursor rules. SOUL.md is loaded separately for identity so it is not duplicated as ordinary project context.

Mid-session memory writes update durable storage but do not necessarily rewrite an already-cached system prompt immediately. New sessions and defined rebuild paths refresh the snapshot.

Prompt checklist

• Put durable identity and tone in SOUL.md.
• Put stable user facts in user or memory storage.
• Put project rules in one intentional context-file format.
• Keep per-turn data in messages or supported ephemeral layers.
• Avoid editing prompt-builder code for ordinary customization.
• Keep platform hints specific and byte-stable.
• Check context-file size and sanitization limits.
• Test delegation paths that intentionally skip project context.

Pitfalls

• Creating several context files and assuming all will be combined.
• Duplicating SOUL.md content in project instructions.
• Expecting a memory write to mutate the current cached prompt instantly.
• Injecting dynamic status into the stable prefix every turn.
• Forking prompt assembly when supported configuration surfaces are sufficient.

Verification steps

1. Create a disposable profile and minimal project context.
2. Start a session and inspect which context source wins.
3. Confirm identity is loaded once.
4. Add a harmless durable memory fact and test it in a new session.
5. Add a platform-specific hint and verify only that platform changes.
6. Repeat equivalent turns and inspect prompt-cache behavior where supported.
7. Delegate a small task and verify its documented context boundary.