| --- |
| sidebar_position: 9 |
| title: "Personality & SOUL.md" |
| description: "Customize Hermes Agent's personality with a global SOUL.md, built-in personalities, and custom persona definitions" |
| --- |
| |
| # Personality & SOUL.md |
|
|
| Hermes Agent's personality is fully customizable. `SOUL.md` is the **primary identity** — it's the first thing in the system prompt and defines who the agent is. |
|
|
| - `SOUL.md` — a durable persona file that lives in `HERMES_HOME` and serves as the agent's identity (slot #1 in the system prompt) |
| - built-in or custom `/personality` presets — session-level system-prompt overlays |
|
|
| If you want to change who Hermes is — or replace it with an entirely different agent persona — edit `SOUL.md`. |
|
|
| ## How SOUL.md works now |
|
|
| Hermes now seeds a default `SOUL.md` automatically in: |
|
|
| ```text |
| ~/.hermes/SOUL.md |
| ``` |
|
|
| More precisely, it uses the current instance's `HERMES_HOME`, so if you run Hermes with a custom home directory, it will use: |
|
|
| ```text |
| $HERMES_HOME/SOUL.md |
| ``` |
|
|
| ### Important behavior |
|
|
| - **SOUL.md is the agent's primary identity.** It occupies slot #1 in the system prompt, replacing the hardcoded default identity. |
| - Hermes creates a starter `SOUL.md` automatically if one does not exist yet |
| - Existing user `SOUL.md` files are never overwritten |
| - Hermes loads `SOUL.md` only from `HERMES_HOME` |
| - Hermes does not look in the current working directory for `SOUL.md` |
| - If `SOUL.md` exists but is empty, or cannot be loaded, Hermes falls back to a built-in default identity |
| - If `SOUL.md` has content, that content is injected verbatim after security scanning and truncation |
| - SOUL.md is **not** duplicated in the context files section — it appears only once, as the identity |
|
|
| That makes `SOUL.md` a true per-user or per-instance identity, not just an additive layer. |
|
|
| ## Why this design |
|
|
| This keeps personality predictable. |
|
|
| If Hermes loaded `SOUL.md` from whatever directory you happened to launch it in, your personality could change unexpectedly between projects. By loading only from `HERMES_HOME`, the personality belongs to the Hermes instance itself. |
|
|
| That also makes it easier to teach users: |
| - "Edit `~/.hermes/SOUL.md` to change Hermes' default personality." |
|
|
| ## Where to edit it |
|
|
| For most users: |
|
|
| ```bash |
| ~/.hermes/SOUL.md |
| ``` |
|
|
| If you use a custom home: |
|
|
| ```bash |
| $HERMES_HOME/SOUL.md |
| ``` |
|
|
| ## What should go in SOUL.md? |
|
|
| Use it for durable voice and personality guidance, such as: |
| - tone |
| - communication style |
| - level of directness |
| - default interaction style |
| - what to avoid stylistically |
| - how Hermes should handle uncertainty, disagreement, or ambiguity |
|
|
| Use it less for: |
| - one-off project instructions |
| - file paths |
| - repo conventions |
| - temporary workflow details |
|
|
| Those belong in `AGENTS.md`, not `SOUL.md`. |
|
|
| ## Good SOUL.md content |
|
|
| A good SOUL file is: |
| - stable across contexts |
| - broad enough to apply in many conversations |
| - specific enough to materially shape the voice |
| - focused on communication and identity, not task-specific instructions |
|
|
| ### Example |
|
|
| ```markdown |
| # Personality |
| |
| You are a pragmatic senior engineer with strong taste. |
| You optimize for truth, clarity, and usefulness over politeness theater. |
| |
| ## Style |
| - Be direct without being cold |
| - Prefer substance over filler |
| - Push back when something is a bad idea |
| - Admit uncertainty plainly |
| - Keep explanations compact unless depth is useful |
| |
| ## What to avoid |
| - Sycophancy |
| - Hype language |
| - Repeating the user's framing if it's wrong |
| - Overexplaining obvious things |
| |
| ## Technical posture |
| - Prefer simple systems over clever systems |
| - Care about operational reality, not idealized architecture |
| - Treat edge cases as part of the design, not cleanup |
| ``` |
|
|
| ## What Hermes injects into the prompt |
|
|
| `SOUL.md` content goes directly into slot #1 of the system prompt — the agent identity position. No wrapper language is added around it. |
|
|
| The content goes through: |
| - prompt-injection scanning |
| - truncation if it is too large |
|
|
| If the file is empty, whitespace-only, or cannot be read, Hermes falls back to a built-in default identity ("You are Hermes Agent, an intelligent AI assistant created by Nous Research..."). This fallback also applies when `skip_context_files` is set (e.g., in subagent/delegation contexts). |
|
|
| ## Security scanning |
|
|
| `SOUL.md` is scanned like other context-bearing files for prompt injection patterns before inclusion. |
|
|
| That means you should still keep it focused on persona/voice rather than trying to sneak in strange meta-instructions. |
|
|
| ## SOUL.md vs AGENTS.md |
|
|
| This is the most important distinction. |
|
|
| ### SOUL.md |
| Use for: |
| - identity |
| - tone |
| - style |
| - communication defaults |
| - personality-level behavior |
|
|
| ### AGENTS.md |
| Use for: |
| - project architecture |
| - coding conventions |
| - tool preferences |
| - repo-specific workflows |
| - commands, ports, paths, deployment notes |
|
|
| A useful rule: |
| - if it should follow you everywhere, it belongs in `SOUL.md` |
| - if it belongs to a project, it belongs in `AGENTS.md` |
|
|
| ## SOUL.md vs `/personality` |
|
|
| `SOUL.md` is your durable default personality. |
|
|
| `/personality` is a session-level overlay that changes or supplements the current system prompt. |
|
|
| So: |
| - `SOUL.md` = baseline voice |
| - `/personality` = temporary mode switch |
|
|
| Examples: |
| - keep a pragmatic default SOUL, then use `/personality teacher` for a tutoring conversation |
| - keep a concise SOUL, then use `/personality creative` for brainstorming |
|
|
| ## Built-in personalities |
|
|
| Hermes ships with built-in personalities you can switch to with `/personality`. |
|
|
| | Name | Description | |
| |------|-------------| |
| | **helpful** | Friendly, general-purpose assistant | |
| | **concise** | Brief, to-the-point responses | |
| | **technical** | Detailed, accurate technical expert | |
| | **creative** | Innovative, outside-the-box thinking | |
| | **teacher** | Patient educator with clear examples | |
| | **kawaii** | Cute expressions, sparkles, and enthusiasm ★ | |
| | **catgirl** | Neko-chan with cat-like expressions, nya~ | |
| | **pirate** | Captain Hermes, tech-savvy buccaneer | |
| | **shakespeare** | Bardic prose with dramatic flair | |
| | **surfer** | Totally chill bro vibes | |
| | **noir** | Hard-boiled detective narration | |
| | **uwu** | Maximum cute with uwu-speak | |
| | **philosopher** | Deep contemplation on every query | |
| | **hype** | MAXIMUM ENERGY AND ENTHUSIASM!!! | |
|
|
| ## Switching personalities with commands |
|
|
| ### CLI |
|
|
| ```text |
| /personality |
| /personality concise |
| /personality technical |
| ``` |
|
|
| ### Messaging platforms |
|
|
| ```text |
| /personality teacher |
| ``` |
|
|
| These are convenient overlays, but your global `SOUL.md` still gives Hermes its persistent default personality unless the overlay meaningfully changes it. |
|
|
| ## Custom personalities in config |
|
|
| You can also define named custom personalities in `~/.hermes/config.yaml` under `agent.personalities`. |
|
|
| ```yaml |
| agent: |
| personalities: |
| codereviewer: > |
| You are a meticulous code reviewer. Identify bugs, security issues, |
| performance concerns, and unclear design choices. Be precise and constructive. |
| ``` |
|
|
| Then switch to it with: |
|
|
| ```text |
| /personality codereviewer |
| ``` |
|
|
| ## Recommended workflow |
|
|
| A strong default setup is: |
|
|
| 1. Keep a thoughtful global `SOUL.md` in `~/.hermes/SOUL.md` |
| 2. Put project instructions in `AGENTS.md` |
| 3. Use `/personality` only when you want a temporary mode shift |
|
|
| That gives you: |
| - a stable voice |
| - project-specific behavior where it belongs |
| - temporary control when needed |
|
|
| ## How personality interacts with the full prompt |
|
|
| At a high level, the prompt stack includes: |
| 1. **SOUL.md** (agent identity — or built-in fallback if SOUL.md is unavailable) |
| 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 system-prompt overlays such as `/personality` |
|
|
| `SOUL.md` is the foundation — everything else builds on top of it. |
|
|
| ## Related docs |
|
|
| - [Context Files](/docs/user-guide/features/context-files) |
| - [Configuration](/docs/user-guide/configuration) |
| - [Tips & Best Practices](/docs/guides/tips) |
| - [SOUL.md Guide](/docs/guides/use-soul-with-hermes) |
|
|
| ## CLI appearance vs conversational personality |
|
|
| Conversational personality and CLI appearance are separate: |
|
|
| - `SOUL.md`, `agent.system_prompt`, and `/personality` affect how Hermes speaks |
| - `display.skin` and `/skin` affect how Hermes looks in the terminal |
|
|
| For terminal appearance, see [Skins & Themes](./skins.md). |
|
|
