hermes-agent/website/docs/user-guide/features/personality.md

sidebar_position, title, description

sidebar_position	title	description
9	Personality & SOUL.md	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 customizable, but there are two different layers that matter:

• SOUL.md — a durable persona file that lives in HERMES_HOME and is loaded automatically for that Hermes instance
• built-in or custom /personality presets — session-level system-prompt overlays

If you want a stable default voice that follows you across sessions, SOUL.md is the right tool.

How SOUL.md works now

Hermes now seeds a default SOUL.md automatically in:

~/.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:

$HERMES_HOME/SOUL.md

Important behavior

• 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, Hermes adds nothing from it to the prompt
• If SOUL.md has content, that content is injected verbatim after security scanning and truncation
• Hermes does not add wrapper language like "If SOUL.md is present..." around the file anymore

That makes SOUL.md a true per-user or per-instance default personality, not a repo-local trick.

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:

~/.hermes/SOUL.md

If you use a custom home:

$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

# 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

If SOUL.md contains text, Hermes injects the file's text itself — not a wrapper explanation.

So the system prompt gets the content directly, after:

• prompt-injection scanning
• truncation if it is too large

If the file is empty or whitespace-only, nothing from SOUL.md is added.

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

/personality
/personality concise
/personality technical

Messaging platforms

/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.

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:

/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. default Hermes identity
2. memory/user context
3. skills guidance
4. context files such as AGENTS.md, .cursorrules, and global SOUL.md
5. platform-specific formatting hints
6. optional system-prompt overlays such as /personality

So SOUL.md is important, but it is one layer in a broader system.

Related docs

• Context Files
• Configuration
• Tips & Best Practices
• SOUL.md Guide

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.