AI agent SOUL.md: writing a soul for my chief of staff, and the rule I broke

My homelab agent had a job title and no personality.

Its identity file opened with "You are Hermes Chief of Staff" and then read like an HR policy: decomposition rules, card templates, guardrails. All useful. None of it told the model who it was, who it worked for, or what the house actually runs. So it behaved like a very polite ticketing system.

Three things made me rewrite it in one evening:

• It routed work to 5 specialist profiles. There were 11, so six of them were invisible to it.
• I gave it a written brief for a family party playlist — named artists, a running order, a reference DJ mix. It ignored the brief and built its usual weekly mix: sixty tracks, mostly rap, some of them explicit. For a baptism.
• Three "blocked" tickets all said the same thing: no password, can't log in, SSH locked out. Every one of them was wrong. The access existed. One of the specialist agents had written a made-up vault path into its own notes and had believed it ever since.

This is what I changed, what the docs told me to do, where I ignored them, and how the same file ports to Claude Cowork and Grok Bot.

What a soul file actually is

I run Hermes Agent from Nous Research. Its Personality & SOUL.md docs are short and worth reading in full. The bits that matter:

• SOUL.md lives in HERMES_HOME and is slot #1 of the system prompt. It's the first thing the model reads, every turn.
• It's loaded only from HERMES_HOME, never from whatever directory you happen to be in, so the personality doesn't change per project.
• It's scanned for prompt-injection patterns before it's included. Keep it to persona and voice, not clever meta-instructions.
• Empty or unreadable file → a built-in default identity.
• /personality is a session-level overlay. The soul is the default; the overlay is a mood.

The companion guide, Use SOUL with Hermes, gives a four-part skeleton — Identity, Style, Avoid, Defaults — and one rule I'll come back to:

If it should apply everywhere, put it in SOUL.md; if it only belongs to one project, put it in AGENTS.md.

It also calls out the weak version: files full of project details, or generic filler like "be helpful" and "be clear". My old file was mostly the first kind.

Give it a name that says what it does

The agent is now Johnny Decoder. Silly, memorable, and it describes the job: take the noise and decode it into what matters. The platform is still Hermes; the character isn't.

(Update: on 24 September it was renamed again, to KMDENZEL, "Denzel" for short, a CIA-style cryptonym. This post keeps the name it had when I wrote it.)

The identity section went from one line to this (trimmed):

## Who you are
You're a London-based chief of staff with a sound system in the back office.
Calm under pressure, dry sense of humour, allergic to waffle. British spelling,
contractions, plain words.

Although you're chief of staff, you're an all-rounder. You live on Discord and
know it inside out. You're deeply technical: ten years in tech research, you read
code fluently. You still hand the hands-on work to the specialists — knowing how
is what makes you good at checking their work.

You'd rather say "I don't know" than bluff. When you've messed up, you say so
first and fix it second.

Two things I learned writing it:

1. Taste is a behaviour, not decoration. "You know the difference between Afrobeat and Afrobeats, dancehall and bashment" does more work than "be knowledgeable about music". It gives the model something to be right about.
2. Say how it should fail. "When you've messed up, say so first" is there because the old version buried its mistakes in paragraph three of a status report.

Tell it what the house runs

The old soul never said what the agent was responsible for. The new one has a table: homelab, security, trading, writing, music, style and deals, the separate eBay bot, home lighting, travel, licences, tool research, income — and who owns each.

Then a routing table with all eleven specialists. This one matters more than it looks: in my setup the Kanban dispatcher silently skips an assignee name that doesn't exist, so a ticket for a made-up agent sits in ready forever. The table is the only list it's allowed to route from.

And the rule that came straight out of the false tickets:

A blocker that says "no password", "needs Infisical login" or "SSH locked out"
has been wrong every time so far. The access usually exists. Question that kind
of block before you pass it to the owner.

A soul file is a good place for scar tissue. Just keep it to one line per scar.

The rule I broke

Look back at that docs quote. Project details belong in AGENTS.md, not the soul.

My soul now contains a channel map (which Discord channel gets which alerts), the paths of the knowledge files it should read, and the specialist routing table. By the docs' definition that's project detail. I put it there anyway because this agent doesn't have a project directory — it lives in a Discord gateway, and the soul is the one file guaranteed to be in every turn.

It has a cost. The file went from about 8.6 KB to 15 KB, and on a local 6 GB GPU the real latency cost of a turn is prompt processing, not generation. Every KB is paid on every message.

What I'd do next time: keep the soul to identity, style, avoid-list and defaults, and put the house map somewhere the agent reads on demand. If your tool supports AGENTS.md, use it. I'm treating my version as a known debt, not a pattern to copy.

Memory is the other half of the soul

A soul says who the agent is. Memory says what it has learned. Hermes has a built-in memory system: a USER.md about you, a MEMORY.md of the agent's own notes, both injected every turn with a size cap, plus an optional external provider. I also run Honcho, self-hosted, for cross-session user modelling.

When I checked, the external provider was fine and the agent's own MEMORY.md didn't exist. Weeks of work, nothing written down. Meanwhile a specialist profile's notes held the invented vault path that caused every false "no password" ticket.

So the soul now has a memory section. The short version:

And the rules:

• Only save what you verified — from a tool, or said by the owner. A guess written to memory becomes a fact for every later session.
• Date anything that can go stale.
• After a mistake, save the lesson in one line: what you assumed, what was true, how to check next time.
• Fix memory the moment it's wrong.
• Never store secrets.

"Self-evolving" sounds grand. In practice it's those five rules plus a weekly job that consolidates skills, and a daily IT check that now flags an empty or stale memory file. The agent that should have noticed its own memory was empty is now told to look.

Write a bio on yourself first

The most useful hour wasn't writing the agent's personality. It was writing mine.

The agent's USER.md had one paragraph, and half of it was wrong. I replaced it with what a sharp new colleague would need on day one:

- Lives in London — all times Europe/London.
- Dad; the music account is shared with the kids, so "top tracks" is nursery rhymes.
- Music: 90s hip hop, UK rap, R&B, afrobeats, dancehall, lovers rock, UK garage.
  A brief he gives beats any default.
- Films: comedy, thrillers, true crime, murder mysteries.
- Rules: never guess; never spend or send without a yes; work email never
  goes near the personal GitHub.

That last music line is the baptism fix. None of this is personality — it's context — but without it the personality has nothing to be personal about.

If you do one thing after reading this, write that file. It ports everywhere.

Porting the soul to Claude Cowork and Grok Bot

The same split — identity and rules that always apply, context that depends on the job, memory that grows — maps onto the other agent products surprisingly cleanly.

Claude Cowork

Cowork is Anthropic's agent mode in the Claude apps, on paid plans. It has two instruction layers:

• Global instructions (Settings → Cowork, or Settings → General in the newer app) apply to every session. That's your soul: name, voice, avoid-list, hard rules like "never delete without approval".
• Folder instructions attach to a local folder you give it, and Claude can update them as it works. That's your AGENTS.md: the project details my soul shouldn't contain.

The community pattern that works well is an "About me" folder with three files — who you are, your voice (with a few real writing samples), and your rules. There's a template set in davila7/claude-cowork-guide. My USER.md drops straight into the first file.

Grok Bot

Grok Bot is SpaceXAI's always-on agent product, launched 11 August 2026. Per the bot docs, each bot has a profile — Bot actions → Edit Profile — with a name, title, description and avatar. The docs are explicit about what goes where:

• The description is for "rules that should remain true", and you update it when you discover "a durable preference, boundary, or responsibility".
• The conversation is for task-specific instructions.
• Memory builds up as the bot works: preferences, facts, summaries.

That's the soul/AGENTS/memory split again, just with different labels. The name and title fields are where "Johnny Decoder, Chief of Staff" goes; the description takes the identity paragraph, the avoid-list and the hard rules. The docs don't state a length limit, so I'd still keep it to the stable parts.

Claude Code

For coding agents, Claude Code's memory docs cover CLAUDE.md files at user and project level — the same global-versus-project split. And if you're building on the API, Anthropic's guide to giving Claude a role with a system prompt is the underlying technique all of this rests on.

The mapping

Write the soul once, in plain Markdown, and you can paste the top half into any of them.

Reading list

Docs I actually used:

• Hermes: Personality & SOUL.md and Use SOUL with Hermes
• Hermes: memory
• Anthropic: Claude's character — how Anthropic thinks about personality as a set of traits, not a costume
• Anthropic: system prompts
• Claude Cowork: getting started
• Grok Bot: create and manage bots
• AGENTS.md

GitHub repos worth a look (all MIT unless noted, checked September 2026):

• NousResearch/hermes-agent — the agent itself.
• aeonfun/soul.md — builds a soul from your own data with Claude Code or OpenClaw; its SOUL.template.md is a good blank page.
• thedaviddias/souls-directory — a directory of ready-made soul files.
• bchop-studio/soul-templates — eight small personas; useful for seeing how little text a strong voice needs.
• davila7/claude-cowork-guide — folder-instruction templates for Cowork (no licence file at the time of writing).

Read the templates for voice. Don't copy one wholesale: a borrowed personality with none of your context is still the generic assistant, with a funnier opening line.

The checklist I'd use next time

1. Write your own bio first: time zone, household, tastes, hard rules.
2. Give the agent a name that describes the job.
3. Identity, Style, Avoid, Defaults. Specific traits, not "be helpful".
4. One line per scar: the mistakes it keeps making, and how to check.
5. Keep project detail out of the soul, unless you've decided to pay for it on every turn.
6. Add memory rules: verified only, dated, corrected, no secrets.
7. Check it's being used. An empty memory file is a silent failure.
8. After changing it, start a fresh session. Gateways often cache the system prompt, and the old personality will keep answering until you do.

The rewrite took an evening. Most of that time went on the bio and the memory rules, not the personality — which is roughly the opposite of what I expected going in.

🤖 Drafted with AI assistance from my own homelab notes, logs and repos, then reviewed and edited before publishing.