db4dfea7ec
Update all SOUL.md documentation to reflect that it now occupies slot #1 in the system prompt, replacing the hardcoded default identity. Updated pages: - user-guide/features/personality.md — SOUL.md is primary identity, not just a layer - developer-guide/prompt-assembly.md — updated prompt layer order, context files list - guides/use-soul-with-hermes.md — SOUL.md replaces built-in identity - user-guide/configuration.md — updated context files table and directory tree Co-authored-by: Test <test@test.com>
272 lines
8.2 KiB
Markdown
272 lines
8.2 KiB
Markdown
---
|
|
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).
|