Sókrates Wiki

Hermes Agent SOUL.md — Persistent Identity and Personality System

4 min read

Hermes Agent SOUL.md — Persistent Identity and Personality System

Summary

SOUL.md is Hermes Agent’s primary identity file, injected as the first slot in the system prompt to define who the agent is and how it communicates. It is instance-scoped — always loaded from HERMES_HOME rather than the current working directory — making it a durable, per-user or per-instance identity rather than a project-level artifact. This is distinct from both the session-level /personality overlay and the project-level AGENTS.md context file.

Details

File Location and Loading

Hermes reads SOUL.md exclusively from HERMES_HOME:

  • Default path: ~/.hermes/SOUL.md
  • Custom instance path: $HERMES_HOME/SOUL.md

Hermes never looks in the current working directory for SOUL.md. This is an intentional design decision: loading from a CWD-relative path would cause the agent’s personality to change unexpectedly as users switch between projects. By anchoring to HERMES_HOME, the identity belongs to the Hermes instance itself.

On first run, Hermes automatically seeds a starter SOUL.md if none exists. Existing files are never overwritten, and empty files trigger the built-in fallback identity: "You are Hermes Agent, an intelligent AI assistant created by Nous Research...".

Prompt Stack Position

SOUL.md occupies slot #1 in the full system prompt, which layers as follows:

  1. SOUL.md (agent identity, or built-in fallback)
  2. Tool-aware behavior guidance
  3. Memory/user context
  4. Skills guidance
  5. Context files (AGENTS.md, .cursorrules)
  6. Timestamp
  7. Platform-specific formatting hints
  8. Optional session overlays (/personality)

Content is injected verbatim after prompt-injection scanning and truncation. It is not duplicated in the context files section — it appears exactly once, at the foundation. Everything else in the prompt stack builds on top of it.

What Belongs in SOUL.md

SOUL.md is for durable, globally applicable identity content:

  • Tone and personality traits
  • Communication style and level of directness
  • Stylistic preferences and things to avoid
  • How the agent handles uncertainty, disagreement, or ambiguity
  • Default interaction posture

A well-formed SOUL.md is stable across contexts, broad enough to apply in many conversations, and specific enough to materially shape voice. The project’s own Sokrates instance uses a pragmatic engineer persona: truth and clarity over politeness theater, pushback on bad ideas, no sycophancy or hype language, compact explanations unless depth is warranted.

SOUL.md is not for repository-specific coding conventions, file paths, service ports, architecture notes, or temporary workflow instructions. Those belong in AGENTS.md.

Rule of thumb: if the content should follow the agent everywhere, it belongs in SOUL.md; if it belongs to a specific project, it belongs in AGENTS.md.

The /personality Command — Session-Level Overlays

The /personality command provides temporary mode switches within a session, complementing SOUL.md rather than replacing it. SOUL.md is the baseline; /personality is the overlay.

Hermes ships with named built-in personalities including helpful, concise, technical, creative, teacher, and a range of novelty modes. Custom personalities can be defined in ~/.hermes/config.yaml under agent.personalities and activated with /personality <name>:

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

Common Failure Modes

  • SOUL.md edits not taking effect: wrong file path, empty file, session not restarted, or an active /personality overlay is masking it.
  • Hermes ignoring parts of SOUL.md: conflicting guidance, file too long and truncated, or injection-pattern scanner blocked specific text.
  • SOUL.md becoming project-specific over time: a common drift; periodically review and move project instructions to AGENTS.md, keeping SOUL.md focused on identity and style alone.

The recommended setup for Sokrates development:

  1. Maintain a thoughtful global SOUL.md in ~/.hermes/SOUL.md with a stable engineering-oriented persona
  2. Put all project-specific instructions (stack, ports, workflows, conventions) in AGENTS.md
  3. Use /personality only for temporary mode shifts within a session

This gives a stable voice across all interactions, project-appropriate behavior where it matters, and flexible control when needed.

Graph View

Backlinks