forked from Zakaria/hermes-agent
Hermes-agent
This commit is contained in:
Zakaria
@@ -0,0 +1,271 @@
|
||||
---
|
||||
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](/user-guide/features/context-files)
|
||||
- [Configuration](/user-guide/configuration)
|
||||
- [Tips & Best Practices](/guides/tips)
|
||||
- [SOUL.md Guide](/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).
|
||||
Reference in New Issue
Block a user