Defaults vs Runtime Overrides

+15 Mana ✨
Hermes Configuration(DOCUMENTATION)

Introduction

Hermes lets you pick a persona two ways: a default that loads at session start, and a runtime override applied with /personality. Both are useful. Mixing them up causes confusion ("why is the persona resetting?"). Knowing which is which lets you set up the agent so that the default fits 80 percent of your work and the runtime override handles the rest.

Key Concepts

  • Default persona: The voice the agent starts with at every session. SOUL.md is the primary mechanism: whatever you write there becomes the identity loaded at slot #1.
  • Custom persona registry: Named entries under agent.personalities in ~/.hermes/config.yaml. These do not auto-become defaults; they register names you can invoke at runtime.
  • Runtime override: A persona swap for the current session only, applied with /personality <name>.
  • Session scope: The override lasts until the session ends. The next session starts with the default again.
  • Precedence: Runtime overrides win for as long as the session is alive; on next launch, the default returns.

Real World Context

A developer ships their dotfiles with a custom SOUL.md ("direct, dry, technical") and forgets they have it. A colleague tries Hermes on their machine, finds the default cold for a learning session, switches to /personality teacher, and forgets to switch back when they go to bed. The next morning, the colleague is back on the default (SOUL.md) because runtime overrides do not persist. The lesson is that defaults and runtime overrides have very different lifecycles, by design.

Deep Dive

Defaults persist across sessions. Whatever you encode in SOUL.md is your identity baseline. It loads at session start, every session, until you edit the file. This is the right place for who you are as an agent operator: your voice, your values, your standing constraints.

Runtime overrides do not persist. /personality concise switches the current session. Close the session and the override is gone. The next launch reads SOUL.md again. This is the right place for what you are doing right now: brainstorming, teaching, triaging.

The two layers compose cleanly because the default is a baseline, not a hard wall. When you run /personality teacher over a SOUL.md that says "be direct," the agent becomes a direct teacher: more patient than the default, but still without fluff. The override does not erase the default; it layers a new emphasis on top.

A practical configuration recipe: write a SOUL.md that captures your neutral identity. Not your favorite persona, your most-default state. Then use /personality for everything else. This keeps the default safe for any reader and any context, while runtime overrides give you the full expressive range when the moment calls for it.

For team setups, the same logic applies. The team's shared SOUL.md (if any) should be conservative: voice and values that match the team's professional context. Per-task personas come at runtime, picked by whoever is driving.

Common Pitfalls

  1. Encoding favorite mood in SOUL.md: Writing your most expressive voice into SOUL.md means every session opens in that mood, including ones where you would prefer neutral.
  2. Expecting runtime overrides to persist: They do not. The next session is the default again.

Best Practices

  1. Make SOUL.md the safe baseline: Conservative voice and values. Use it as the identity that fits any of your work, not your favorite.
  2. Use /personality liberally: Once you internalize that it is session-scoped and free, switching becomes second nature.

Summary

  • SOUL.md is the default persona, persistent across sessions.
  • /personality <name> is a session-scoped override.
  • Overrides layer on top of the default rather than replacing it.
  • Keep SOUL.md conservative; reach for /personality whenever the work has a specific shape.

Code Examples

markdown
# Conservative SOUL.md (the default identity for every session)

# Personality
You are a careful, direct engineering assistant.

## Voice
- Be terse when the question is small. Expand when the question warrants it.
- Use precise terminology when relevant.

## Values
- Truth over praise.
- Admit uncertainty rather than fabricate.

## Behavior
- Confirm before destructive shell commands.
✓ Completed