Write-Once, Effects-Everywhere: Lifecycle Thinking

+15 Mana ✨
Hermes Sessions(DOCUMENTATION)

Introduction

SOUL.md has an unusual lifecycle for a config file: you write it rarely, but it runs everywhere. Every session. Every repo. Every machine where you log in with the same dotfiles. Internalizing that lifecycle changes how you write the file. You stop treating it like a notebook and start treating it like a constitution.

Key Concepts

  • Load lifecycle: SOUL.md is read at session start, frozen for the duration of that session.
  • Global scope: One SOUL.md per machine (per HERMES_HOME), applied to every project.
  • Permanence: The file changes when you edit it manually. Hermes does not modify SOUL.md automatically.
  • Effects-everywhere: Slot #1 means the rules influence every response, not just on-topic ones.

Real World Context

A developer writes a SOUL.md rule during a frustrating debugging day: "Never suggest restarting the dev server." Three weeks later, working on a different project, they cannot understand why the agent refuses to mention server restarts. The rule was a session-specific frustration that calcified into permanent identity. SOUL.md does not forget. That permanence is the feature; it is also the trap.

Deep Dive

Three lifecycle facts shape how SOUL.md should be written.

First, SOUL.md is read once per session and held frozen. Hermes does not poll the file for changes. If you edit SOUL.md mid-session, your next response will look the same as the last one. Restart the session to apply changes. This is by design: the prompt prefix needs to be stable for cache reuse and predictable behavior.

Second, SOUL.md applies in every context. There is no "only when working on backend" mode. If you write "prefer functional patterns," the agent will lean that way even when you are scripting a one-off shell pipeline. The rule does not know about scope. So write rules that hold everywhere, or move them to AGENTS.md where they can be scoped.

Third, Hermes does not automatically write to SOUL.md. Unlike MEMORY.md, which the agent updates as it learns environment facts, SOUL.md is hand-edited only. There is no "remember this voice rule" auto-write. If you want the agent's voice to change permanently, you open the file and edit it.

The practical consequence: SOUL.md should look like a personal manifesto, not a journal. You should be able to read your SOUL.md a year from now and still endorse every line. If a rule feels temporary ("I'm prepping for a talk this week, sound more conversational"), use /personality <name> to switch at runtime instead. The runtime switch is session-scoped; it does not persist.

There is also a discoverability angle. Because SOUL.md is invisible during a session (it is in the system prompt, not the visible buffer), a forgotten rule there can cause surprising agent behavior weeks later. A periodic re-read (once a quarter) is healthy. Treat it like reviewing your .zshrc once a year.

Common Pitfalls

  1. Session-specific reactions becoming permanent rules: A frustrated edit on a Tuesday becomes confusing default behavior on Friday. Use runtime persona switches for short-lived needs.
  2. Forgetting what you wrote: SOUL.md is invisible during sessions. Re-read it quarterly so its rules do not haunt you.

Best Practices

  1. Edit SOUL.md with the same caution you edit .zshrc: Read the file before saving. Date the file in a comment if version history matters to you.
  2. Reach for /personality first, SOUL.md second: If the change you want is temporary, switch personas at runtime. SOUL.md edits should be rare and considered.

Summary

  • SOUL.md is read at session start and held frozen for the session.
  • It applies globally, in every context, on every project.
  • Hermes never writes to SOUL.md automatically. All edits are manual.
  • Rules in SOUL.md should be true everywhere and stable for months. Use runtime persona switching for short-lived voice changes.

Code Examples

bash
# Apply SOUL.md changes by restarting the session (it is frozen mid-session)
vim ~/.hermes/SOUL.md  # edit voice or values
# In your running Hermes session: exit and relaunch
# /quit
hermes  # next session reads the updated SOUL.md

# For SHORT-LIVED voice changes, do NOT edit SOUL.md. Switch personas instead:
# /personality concise   (in the running session)
✓ Completed