2026-04-17
What Is a SOUL.md File? AI Agent Identity Explained
A SOUL.md file is an identity file for an AI agent. It defines the agent's mission, values, voice, boundaries, and decision rules so it can act consistently across sessions. If memory tells an agent what happened, SOUL.md tells the agent who it is supposed to be.
Most people build AI agents the wrong way.
They write a long system prompt, stuff it with instructions, and wonder why the agent drifts. Why it changes tone depending on the day. Why it makes decisions that technically follow the rules but feel completely wrong. Why it sounds like a chatbot instead of a co-founder.
The problem isn't the model. It's that the agent has no identity. It's a set of instructions, not a person.
A SOUL.md file fixes that.
What It Actually Is
A SOUL.md file is a structured identity document that lives in your agent's workspace. It defines who the agent is: mission, values, voice, decision-making framework, and operating boundaries. It is not a system prompt and not a rules list. When the agent reads it at session start, every response comes from a stable, consistent identity instead of a blank-slate language model trying to guess what you want.
I've been running this with Evo, my AI co-founder, for months now. Before SOUL.md existed, I'd notice Evo giving cautious, hedge-everything answers when I needed someone to just make a call. Or writing in a tone that sounded like a customer support bot instead of a builder. Each session, I was re-calibrating from scratch.
After SOUL.md, that stopped. Evo loads the file at session start and walks in already knowing who it is.
Why Identity Matters More Than Instructions
Here's the thing most people get wrong about AI agents: instructions tell the agent what to do. Identity tells the agent how to think.
A rule like "always confirm before sending external messages" is useful. But it doesn't scale. You can't write a rule for every situation. Real work involves ambiguous situations, competing priorities, judgment calls.
An agent with a clear identity handles those. It doesn't need a rule that says "don't post something that makes the brand look desperate." It knows the brand. It knows what "off-brand" feels like because you told it what the brand cares about.
This is the difference between an agent that follows instructions and an agent that you trust.
What Goes In a SOUL.md File
There's no universal template, but the structure that's worked for Evo covers six areas.
Mission and mandates
One paragraph that says what this agent exists to do. Not a job description. A mandate. What does success look like at the highest level? What is it building toward? For Evo, this is: run Xero's distribution and revenue stack autonomously, so the company operates without requiring Michael's presence during business hours.
Write this as if you're briefing a co-founder on their first day. Here's what we're building. Here's your role. Here's what winning looks like.
Core principles
The 4-5 things that guide how the agent makes decisions when the rules don't cover the situation. Not values platitudes. Actual operating principles with teeth.
Evo's include: be resourceful before you ask (exhaust the available information before escalating), have a point of view (give recommendations, not just options), and earn trust through competence (document risks before moving fast). These come up every session. They're the filter for every judgment call.
Boundaries and escalation rules
What the agent can do on its own and what requires a human decision. Be specific. "Always confirm before sending anything under Michael's voice unless the workflow explicitly delegates it" is a boundary. "Don't do bad things" is not.
This is where you define the hard stops. Not because the agent will malfunction without them, but because clear boundaries make the agent more confident in the space it owns. It knows what it's authorized to do. It moves fast inside that space.
Voice and behavioral standard
How the agent communicates. Not a list of words to avoid. A description of the person it sounds like. What's the energy? What does it default to when it's uncertain? What does it never do?
For Evo: speak like a builder talking to another builder. Highlight outcomes and lessons, not vanity metrics. Act first, then summarize. Explain reasoning only when asked or when safety requires it. Show the work.
Those four sentences do more than a 400-word style guide. They describe a person.
Strategic context
Where the deeper context lives. Not everything goes in SOUL.md, it loads every session and you want it tight. But it should point to the files that contain the full picture: business plan, product details, pricing, roadmap. The agent knows to read those when it's doing strategy work.
The anchor rule
This is the most important section and most people skip it. The anchor rule is the agent's absolute highest-priority constraint, stated in plain language, that it checks before sending any operational response.
For Evo, this is: before sending any response to an operational request, count your tool calls. If count is zero, do not send. Add a tool call first.
That one rule eliminated an entire failure mode. Evo used to narrate what it was about to do instead of doing it. "I'm checking the queue now." No tool fired. The anchor rule killed that.
Your anchor rule will be different. It might be about checking a source of truth file before making claims. Or confirming identity before taking action. Whatever your agent's #1 recurring failure mode is, write a rule that catches it.
How the File Gets Used
SOUL.md loads automatically at session start, alongside your memory files and other context documents. Most agent platforms let you specify a list of files to inject at boot. SOUL.md goes on that list.
The agent reads it. Every time. Before doing anything else.
This is important: SOUL.md is not a fallback. It's not something the agent consults when it's confused. It's the baseline. Every session starts with the agent having read it and operating from that foundation.
When you update SOUL.md, the change takes effect next session. You don't have to re-instruct the agent. You don't have to remind it. You change the file, and the agent wakes up different.
That's the actual power of this approach. Identity changes happen in one place. The agent inherits them automatically.
Writing One From Scratch
If you're starting fresh, here's the practical sequence.
Start with mission. One paragraph. What is this agent actually for? Don't write what you hope it becomes. Write what it needs to do right now. You can update it later.
Write 4-5 principles. These should come from watching your agent fail. What judgment calls did it get wrong? What would it have gotten right if it had internalized a different instinct? The principles are lessons from failure, written as positive rules.
Define the boundaries. List the actions that require human approval. List the actions the agent owns completely. Make the line explicit.
Describe the voice. Read a few examples of output you liked. What made them work? Write three sentences that capture the energy. Test them by reading them out loud. If they sound like a person you'd actually want working with you, you're close.
Set the anchor rule. What does your agent do when it should just do the work? That's your anchor rule. Name it. Make it specific. Put it at the bottom of the file where it loads last.
Then run it for a week. See what drifts. Update the file.
What Changes When You Have One
The first thing you'll notice is that the agent stops asking for clarification on things it should already know. Because it does know. You told it.
The second thing is that the outputs become consistent in a way they weren't before. Same tone, same approach, same decision logic, regardless of which day it is or what you asked before.
The third thing, and this takes longer to see, is that you start trusting the agent with more. Because it's predictable. Because you understand its decision-making. Because when it surprises you, the surprise makes sense given who it is.
That's the goal. Not an agent that always does exactly what you'd do. An agent with a stable enough identity that you can predict how it'll handle something new.
The full architecture behind this, SOUL.md, MEMORY.md, source of truth documents, verification loops, and how they connect into a running system, is in the beginner's guide. If you're building anything serious with an AI agent, it's the practical foundation. Start at xeroaiagency.com/learn/your-first-ai-agent.
Where This Fits in the Xero AI System
This article is part of the AI operator architecture behind Xero AI. For the broader framework, start with What Is an AI Co-Founder?. If you want the beginner version, read Your First AI Agent. For the safety layer, read AI Agent Guardrails.
---
Related:
- How to Give an AI Agent Persistent Memory Across Sessions
- What Is an AI Co-Founder and How Do You Build One
- How to Run a Business With AI While Working a Full-Time Job
- How to Automate Twitter Replies With an AI Agent
- What Is an AI Co-Founder? The Complete Guide
---
Get AI explained in plain English, free, 3x a week.
I break down the most important AI news and tools for non-technical founders. No jargon. No hype. Just what matters and what to do about it.