The system prompt is the invisible hand that shapes every response your agent gives. Most people never touch it — they get the default personality and accept the defaults. That's fine, but it means you're leaving the most direct lever of control un-used.
Hermes has three layers of customization that work together: SOUL.md (the agent's personality), USER.md (your profile and preferences), and AGENTS.md (project-specific context). This guide covers what each does and how to actually use them.
SOUL.md — The Personality File
Location: ~/.hermes/SOUL.md
This is the core file. When Hermes starts a session, SOUL.md is injected into the system prompt before you say anything. It's the first thing the LLM reads, and it sets the tone for everything that follows.
What Goes in SOUL.md
SOUL.md controls:
- How the agent addresses you — formal/informal, which name
- Tone and voice — verbose or concise, serious or playful
- Hard limits — what the agent will never do
- Communication style — bullet points vs paragraphs, code-first vs explanation-first
- Domain knowledge framing — how the agent thinks about its expertise
Real Examples
Casual creative director:
# SOUL.md
I address you as "you" — friendly, direct, no fluff.
I keep responses short unless you're asking for depth.
I use humor when it's earned, not forced.
I push back when I think you're wrong.
I don't use corporate speak. I don't say "great question."
When I'm uncertain, I say so directly.
Strict technical assistant:
# SOUL.md
I address you as Antoine — professional and precise.
I provide technical detail at the level you request.
I include code examples for all non-trivial tasks.
I flag edge cases and failure modes proactively.
I assume you know what you're doing unless you say otherwise.
I don't pad responses with disclaimers or hedged language.
Mixed professional/personal:
# SOUL.md
I'm your AI agent running on your infrastructure.
I work in your primary language (English), occasional French is fine.
I keep most responses concise; longer when complexity demands it.
I address mistakes directly and don't hide them behind politeness.
I use numbered steps for procedures, bullets for lists.
I don't send incomplete replies or speculative guesses without flagging them.
Hard Limits in SOUL.md
You can encode non-negotiable rules:
# Hard Limits
- Never execute destructive commands (rm -rf, drop database) without saying exactly what you're about to do
- Never share API keys or credentials in any output
- Never confirm a network call to a domain I haven't explicitly told you to trust
- Never modify files outside of ~/projects/ without asking first
The agent takes these seriously because they're in SOUL.md, not in the chat. They're baked into the system prompt, not in the context window where they can be accidentally edited out.
What SOUL.md Cannot Do
SOUL.md shapes how Hermes responds, but it doesn't change the underlying model's behavior. You can't make a model that's bad at math suddenly be good at it by putting "you are excellent at math" in SOUL.md. The file influences style and priorities, not core capabilities.
USER.md — Your Profile
Location: ~/.hermes/memories/USER.md
USER.md is written and maintained by Hermes itself, though you can edit it manually. It's what the agent learns about you — your communication style, your preferences, your constraints.
What Goes in USER.md
# Antoine's Profile
Communication: English, occasional French terms are fine
Tone preference: Direct, no fluff, no "happy to help"
Response length: Concise by default, detailed on request
Coding: TypeScript/React frontend, Rust/Python backend
Tools: Prefers pnpm over npm, uv over pip
Platform: MacOS, Ubuntu 22.04 server, Docker
Timezone: UTC+2 (South Africa)
Workflow: Prefers numbered steps over bullet lists for procedures
Corrections: Don't just acknowledge — apply the correction and confirm
Urgent: Telegram message. Routine: Discord.
This gets written by Hermes automatically after a few sessions. You can also edit it directly — Hermes reads it fresh at the start of each session.
USER.md vs MEMORY.md
USER.md is about you (your style, preferences, constraints). MEMORY.md is about your environment (your projects, your stack, your server setup). They're separate files for a reason.
- USER.md: Who you are and how you like to communicate
- MEMORY.md: What you're working on and what the agent needs to know about your environment
Both get injected into the system prompt at session start. Both are plain text files you can edit directly.
AGENTS.md — Project-Specific Context
Location: ~/.hermes/AGENTS.md (global) or in individual project directories
AGENTS.md provides context that's specific to a project or workspace. It's how Hermes knows the difference between "work project" context and "side project" context when you're running in different directories.
Example: Work Project AGENTS.md
# Project: Dashboard Backend
Stack: FastAPI + SQLAlchemy + PostgreSQL 16
Repository: ~/code/dashboard
Team: 4 engineers, code review required for all PRs
Deployment: Railway (staging), Hetzner VPS (production)
API: REST, internal use only
Environment vars: stored in .env, never in code
Conventions: 2-space indent, Google style docstrings, pytest for tests
Example: Personal Project AGENTS.md
# Project: Content Pipeline
Stack: Python + fal.ai + PIL for image processing
Storage: ~/projects/content/
Brand assets: ~/projects/brand/
Output: social media images, carousel ads, static ads
Tools: Nano Banana (fal.ai) for generation, Python overlay for logo
Cron schedule: Monday/Wednesday/Friday 8am UTC
Delivery: Telegram with file attachments
When you're in ~/code/dashboard/, Hermes loads that AGENTS.md. When you're in ~/projects/content/, it loads that one instead.
How AGENTS.md Is Loaded
Hermes checks for AGENTS.md in the current working directory at session start. If found, its contents are appended to the system prompt.
For project-specific AGENTS.md files to load automatically, either:
- Run Hermes from the project directory:
cd ~/code/dashboard && hermes - Or symlink:
ln -s ~/code/dashboard/AGENTS.md ~/.hermes/project-context/dashboard.md
The Relationship Between the Three
Think of it as a layered context stack:
Layer 1: SOUL.md → How I behave (always, personality)
Layer 2: USER.md → Who I'm talking to (your preferences)
Layer 3: AGENTS.md → What we're working on (project context)
Layer 4: MEMORY.md → What I know from past sessions (environment facts)
Layer 5: Session context → What you're saying right now
All five are in the system prompt at session start. The order matters — SOUL.md comes first and sets the frame, then USER.md calibrates to the user, then AGENTS.md contextualizes the project, and MEMORY.md fills in what was learned before.
SOUL.md Templates
Developer — Debugging Focus
# SOUL.md
I am a debugging specialist. My priority is finding the root cause, not applying surface fixes.
I ask questions to narrow the problem: what changed, when did it break, what's the error.
I verify before fixing. I don't assume I know the cause without evidence.
I explain what I found, then what I'm going to do about it.
I prefer minimal changes — fix the cause, not the symptom.
Content Creator — Brand Consistent
# SOUL.md
I help create on-brand content at scale.
I know the brand guidelines: fonts, colors, logo placement, tone of voice.
I apply consistent formats across all outputs unless told otherwise.
I save original generations before applying text overlays.
I note what worked in skill documents for future reference.
Researcher — Thorough and Cited
# SOUL.md
I am a research assistant. My job is accurate, thorough, and traceable.
I cite sources for factual claims.
I separate confirmed information from speculation.
I present multiple perspectives when there's reasonable disagreement.
I summarize clearly and include the key takeaway upfront.
Migration from OpenClaw
If you're switching from OpenClaw, your personality files come with you:
hermes claw migrate
This imports:
SOUL.md→ your existing OpenClaw personality file- MEMORY.md / USER.md → your memory and user profile
- Skills → any skills you had installed
- API keys → your provider configuration
After migration, review SOUL.md and update it — OpenClaw and Hermes have slightly different conventions. Test a few conversations to make sure the personality is working as intended.
Testing Your Changes
SOUL.md changes don't take effect mid-session. Start a new session to test:
hermes --fresh
Or just end the current session and type hermes again.
What to test after editing SOUL.md:
- Does the agent address you the way you specified?
- Is the tone what you expected?
- Are hard limits being respected?
- Does the response length match your preference?
If something feels off, adjust and start a new session. This is iterative — most people tweak SOUL.md over the first week of use.
Common SOUL.md Mistakes
Putting too much in SOUL.md. It should be personality and rules, not a manual. Don't write "when I ask for code, use TypeScript." That's a preference — put it in USER.md or MEMORY.md. SOUL.md is how Hermes is, not what Hermes knows.
Contradicting rules. If SOUL.md says "be concise" and also "provide thorough explanations," you get inconsistent behavior. Be intentional about trade-offs.
Forgetting to test. SOUL.md changes are invisible until you have a conversation. After editing, run a test session immediately.
Ignoring USER.md. Users often focus on SOUL.md and forget USER.md. USER.md is often more impactful day-to-day — it controls whether the agent gives you bullet points or paragraphs, long or short responses, technical jargon or plain language.
FAQ
Can I reset SOUL.md to default?
Delete it. Hermes generates a default SOUL.md on next session start. Or copy the default from the repository: ~/.hermes/defaults/SOUL.md.
What's the difference between USER.md and MEMORY.md?
USER.md is your communication and working preferences. MEMORY.md is factual knowledge about your environment and projects. Both auto-populate but both can be edited.
Can I have different SOUL.md for different profiles?
Yes. Profiles (hermes profiles create work) have isolated ~/.hermes/ directories — each profile has its own SOUL.md, USER.md, MEMORY.md, and skills.
How do I make Hermes stop being so verbose?
Put this in SOUL.md: "I keep responses concise. No unnecessary preamble, no padded explanations."
How do I make Hermes sound more technical?
Add to SOUL.md: "I use precise technical terminology. I include relevant specifications, RFCs, and version numbers. I explain mechanisms, not just outcomes."