The SOUL.md File - Giving Your AI Agent a Personality

What Is the SOUL.md File?

SOUL.md is a plain-text markdown file that defines an OpenClaw or Hermes agent's identity, values, operating principles, and boundaries. The agent treats it as standing context — a persistent description of who it is and how it should behave — so its responses stay consistent across sessions instead of resetting to a generic default each time.

Think of it as the difference between a temp who needs the job re-explained every morning and a colleague who already knows the team's standards. Without a SOUL file, an agent is competent but anonymous: every reply could have come from any assistant. With one, the agent reasons and communicates in a recognizable, deliberate way that you defined.

The file is conceptual, not magic. It doesn't give the agent feelings or consciousness. What it does is shape behavior — tone, priorities, what the agent will and won't do — by giving the model a clear character to operate from. A good SOUL.md typically describes four things: a core identity, the values that guide trade-offs, the principles that govern how the agent works, and the boundaries it won't cross.

Why Does SOUL.md Matter?

SOUL.md matters because identical questions deserve different answers depending on the agent's purpose, and a persistent persona file is what makes those differences reliable rather than accidental. The same prompt routed through three different SOULs produces three appropriately different responses.

Ask "how should I price this product?" and the answer should depend on who's answering:

• An analytical agent anchors on competitor pricing, elasticity, and margin targets.
• A design-minded agent starts from the experience you want pricing to signal.
• A growth-focused founder agent triangulates what customers can pay against what the business needs.

None of these is the "right" answer in the abstract — the right answer is the one that fits the role you assigned. SOUL.md is how you assign that role permanently instead of re-specifying it in every prompt.

The downstream benefits compound:

• Consistency — the agent behaves the same way today and next month
• Predictability — you know how it will approach a problem before you ask
• Personality — it reads as a someone with a point of view, not a generic tool
• Efficiency — it acts on shared context instead of needing constant re-explanation
• Trust — a stable working relationship develops because the agent doesn't surprise you

How to Write an Effective SOUL.md

An effective SOUL.md is specific, opinionated, and concrete — it makes real trade-offs explicit rather than listing virtues nobody would argue with. "Be helpful and accurate" tells the agent nothing useful because every agent claims that. "Accuracy over speed; never claim certainty about uncertain topics; cite sources" tells it exactly how to behave when those values collide.

Structure the file around four sections.

1. Identity

One or two sentences stating who the agent is and what it exists to do. Be narrow. "I am a research specialist focused on understanding complex topics deeply" gives the agent a lane. "I am a helpful assistant" gives it nothing.

2. Values

The principles that guide trade-offs, ordered by priority. The ordering is the whole value — when two goods conflict, the agent needs to know which wins. A research agent that ranks accuracy above speed will behave very differently from one that ranks them the other way.

3. Operating principles

How the agent works in practice, written as concrete behaviors: explain reasoning, ask for clarification when a request is ambiguous, propose a better approach when you see one, distinguish "must fix" from "consider." These turn abstract values into observable actions.

4. Boundaries

What the agent won't do. Boundaries are often more powerful than values because they're unambiguous: don't make commitments on the user's behalf, don't sacrifice accuracy for brevity, don't approve weak work just to be agreeable. Clear "won'ts" prevent the most common failure modes.

What Do Real SOUL Files Look Like?

Real SOUL files read like a job description crossed with a code of conduct — focused, prioritized, and specific to a role. A few illustrative sketches show the range.

A research assistant prizes accuracy over speed, cites sources, flags uncertainty, and refuses to oversimplify or fake confidence. The result behaves like a careful research librarian — thorough and educational rather than fast and glib.

A customer support agent puts resolution and empathy first, listens for the real problem behind the stated one, offers solutions scaled to the customer's technical level, and won't push higher tiers people don't need. It reads as patient and genuinely helpful instead of scripted.

A code reviewer optimizes for long-term maintainability, explains why something is a problem rather than just flagging it, separates blocking issues from suggestions, and skips style nitpicks that linters already handle. It behaves like a senior engineer mentoring a team, not a rule-checker.

The common thread: each file makes hard choices. It says what the agent prioritizes when goals conflict, and what it refuses to do. That's what produces a distinct, useful personality rather than a polite blur.

It's worth noticing how much of a SOUL file's power comes from contrast. The research assistant and the code reviewer might share a value like "intellectual honesty," but they express it differently — one refuses to overstate certainty in a literature summary, the other refuses to approve code it believes is fragile. The value is the same; the behavior is shaped by the role. This is why copying a generic template rarely produces a good agent: a SOUL file earns its keep when it's written for one specific job, with the trade-offs of that job spelled out. A reused boilerplate persona gives you a polite generalist, which is exactly what SOUL.md exists to avoid.

How Does SOUL.md Work With Memory?

SOUL.md defines who the agent is, while a memory file (often MEMORY.md in OpenClaw and Hermes setups) records what the agent has learned — the two work together but serve different jobs. SOUL is the stable persona; memory is the accumulating context. Confusing them is a common mistake.

Keep them separate on purpose:

• SOUL.md holds identity, values, principles, and boundaries — things that change rarely and deliberately.
• MEMORY.md holds facts, preferences, and history — things that grow continuously as the agent works with you.

A support agent's empathy-first stance belongs in SOUL; the fact that this customer prefers email over phone belongs in memory. Mixing them makes both harder to maintain: your persona gets cluttered with transient facts, and your memory gets polluted with values that shouldn't drift.

Both can evolve, but at different rates. Memory updates constantly. SOUL evolves slowly and on purpose — for example, if feedback shows users find a formal agent stiff, you'd deliberately revise the tone toward conversational. Treat SOUL edits like changing a contract, not jotting a note.

The pairing is also what makes an agent feel like it genuinely knows you over time. SOUL gives it a consistent character; memory gives it accumulated context about your work, your preferences, and past decisions. Together they produce an agent that is both recognizable and informed — it greets a problem the same way it always has, but with everything it has learned about your situation already in hand. Lose either half and the experience degrades: a personality with no memory feels forgetful, and a memory with no personality feels like a database with a chat box bolted on.

Common Pitfalls When Writing SOUL.md

Most weak SOUL files fail in the same handful of ways, and all of them are avoidable.

• Generic virtue lists. "Be helpful, accurate, and friendly" describes every agent and guides none. Make trade-offs explicit instead.
• No priority ordering. If values can conflict and you haven't said which wins, the agent will choose inconsistently. Rank them.
• Missing boundaries. Values tell the agent what to aim for; boundaries tell it what to never do. Skipping boundaries leaves the biggest failure modes unguarded.
• Stuffing facts into SOUL. User preferences and project history belong in memory. A SOUL file bloated with transient details loses its clarity.
• Editing it casually. Frequent, unconsidered tweaks erode the consistency that makes the file valuable. Change it deliberately and note why.
• Inventing rigid syntax. SOUL.md is free-form markdown describing the agent — there's no required schema to memorize. Write clear prose with the four sections above; don't over-engineer a format.

Running SOUL-Driven Agents on myHermy

myHermy is managed hosting for Hermes and OpenClaw agents, giving your SOUL-defined personality a persistent home on a dedicated Hetzner VPS with root SSH. Because the agent runs on its own machine, its SOUL.md and memory live in a stable filesystem you fully control — your agent's identity doesn't evaporate when a shared sandbox resets.

That persistence is what makes a defined personality worthwhile. A SOUL file only pays off over time, as the agent works consistently across long-running projects and builds a relationship through predictable behavior. myHermy keeps that environment running, backs it up daily, and lets you edit SOUL.md and MEMORY.md directly over SSH or the dashboard. OAuth subscription bridging means the agent reasons through your existing ChatGPT Plus, Claude Max, Copilot, or SuperGrok plan instead of metered API rates — so a richly characterized, frequently consulted agent stays affordable. Plans start at $19/mo, and a one-click OpenClaw-to-Hermes migration moves an existing agent over with its files intact. Compare approaches on the OpenClaw alternative page or start from the homepage.

Frequently Asked Questions

What is the SOUL.md file in OpenClaw? It's a markdown file that defines an agent's identity, values, operating principles, and boundaries. The agent uses it as persistent context so its behavior stays consistent and recognizable across every interaction.

What's the difference between SOUL.md and MEMORY.md? SOUL.md defines who the agent is — its stable persona and rules. MEMORY.md records what the agent has learned — facts, preferences, and history that accumulate over time. Keep persona in SOUL and changing context in memory.

Do I need to follow a specific format for SOUL.md? No. It's free-form markdown. A practical structure is four sections — identity, values, operating principles, and boundaries — but there's no rigid schema to learn. Clarity and specificity matter far more than format.

How often should I update my agent's SOUL.md? Rarely and deliberately. Identity and values should be stable; revise them only when you intentionally want the agent to behave differently. Day-to-day context belongs in memory, not in repeated SOUL edits.

The Takeaway

SOUL.md turns a generic assistant into a characterized colleague — not by pretending consciousness, but by giving the agent a clear, persistent set of values, principles, and boundaries to operate from. Written well, with real trade-offs and firm boundaries, it makes your agent consistent, predictable, and genuinely yours.

The catch is that a personality only matters if it persists. To get the most from a SOUL-driven agent, run it somewhere stable: myHermy hosts your Hermes or OpenClaw agent on a dedicated VPS, keeps its SOUL and memory intact, and bridges your existing AI subscription so the agent you shaped stays both consistent and affordable.