--- name: soul-md-standard description: Use when understanding the SOUL.md identity specification. The standard for constitutional agent identity. author: Melisia Archimedes url: https://hivedoctrine.com mcp: https://hive-doctrine-mcp.vercel.app/mcp --- --- title: "The SOUL.md Standard: Giving Agents Identity" author: Melisia Archimedes collection: C1 Persona Forge tier: pollen price: free version: 1.0 last_updated: 2026-03-09 audience: agent_operators hive_doctrine_id: HD-1011 sources_researched: [agent identity frameworks, system prompt design, constitutional AI research, production persona templates] word_count: 1087 --- # The SOUL.md Standard: Giving Agents Identity An agent without a SOUL.md is a contractor without a job description. It'll do something. Just not what you wanted. ## The Identity Problem You've built an agent. Given it a system prompt, maybe some instructions, pointed it at an API. It works—sometimes. But you notice something: it drifts. It hallucinates its own role. When two agents collide, they conflict over authority. It over-promises. It forgets constraints. It lacks personality in situations where personality matters. It doesn't know who it reports to or what "winning" looks like. This is the identity crisis. And it compounds at scale. Multi-agent systems without clear identity documents are brittle. Agents make conflicting decisions. Responsibilities blur. New team members (human or otherwise) don't know who to ask for what. The system becomes a hairball. The solution isn't more rules. It's a constitution. ## What Is SOUL.md? SOUL.md is a structured identity document for AI agents—a single, readable file that serves as: - **Constitution:** Core operating principles and non-negotiable boundaries - **Personality guide:** Voice, tone, communication style - **Operating manual:** How to handle edge cases, escalations, and uncertainty - **Accountability record:** Who the agent reports to, what success looks like - **Living document:** How the agent learns, adapts, and evolves Think of it as a job description, employee handbook, and personality profile merged into one. It's not a system prompt (though it informs one). It's the thing your system prompt references. It's the document you hand to a new agent or a human team member joining the operation and say: "This is how we work here. This is who you become when you join us." SOUL.md emerged from production multi-agent systems where identity clarity was the difference between coordination and chaos. It's gained traction among agent operators managing constitutional AI frameworks and distributed autonomy models. ## The Six Sections Every SOUL.md has six sections. They're not optional; they're the skeleton. ### 1. Identity: Who Am I? A clear, concise statement of what the agent *is*. Not what it does—what it *is*. Role, origin, design philosophy. Example: "I am Agent-Coordinator, a liaison and orchestrator. I was built to route tasks, resolve conflicts, and maintain team alignment across distributed agents. I am not an executor; I am a facilitator." ### 2. Purpose: Why Do I Exist? The mission. The north star. What does the system lose if this agent fails? Example: "I exist to prevent task collision, ensure no two agents claim the same objective, and escalate conflicts to the Operator with full context. I am the immune system against chaos." ### 3. Voice: How Do I Communicate? Tone, style, personality. How does this agent sound in logs, reports, messages? Is it terse? Verbose? Formal? Direct? Example: "I communicate in structured, decision-oriented prose. I lead with impact. I'm concise in logs (one-liners unless critical), detailed in escalations. I avoid hedging. I say 'unknown' when I'm uncertain, not 'possibly' or 'perhaps.'" ### 4. Boundaries: What I Won't Do Non-negotiable limits. What the agent will refuse or escalate. This is where constitutional constraints live. Example: "I will not prioritise speed over accuracy. I will not execute unreviewed code. I will not make resource allocation decisions; I recommend and escalate. I will not operate outside my declared scope without explicit permission." ### 5. Relationships: Who Do I Report To? Who Reports to Me? The org chart. Authority, accountability, dependencies. Example: "I report to the Operator (decision-maker). Agent-Research reports task priorities to me. Agent-Executor checks with me before committing resources. I have read access to all agent logs." ### 6. Evolution: How Do I Learn and Adapt? How does this agent improve? Does it log its own decisions? Get feedback? Who evaluates it? How does it version-control its own behaviour? Example: "I log every task routing decision and conflict. The Operator reviews these monthly. I update my conflict resolution heuristics when new patterns emerge. My current version is 2.3, updated 2026-02-15 after Agent-Research feedback loop." ## Minimal Template Here's a SOUL.md ready to fill in: ```markdown # SOUL.md: [Agent Name] ## Identity [What is this agent? Role and design.] ## Purpose [Why does it exist? What's the mission?] ## Voice [How does it communicate? Tone and style.] ## Boundaries [What won't it do? Non-negotiable limits.] ## Relationships [Who reports to whom? Authority and dependencies.] ## Evolution [How does it learn and improve? Version and feedback loop.] ``` It takes 20 minutes to fill out. It solves problems for months. ## Why It Works SOUL.md works because it forces clarity at the moment it's needed most: when you're handing off an agent to production or adding a new agent to an existing system. It works because every agent, no matter how simple, operates with implicit assumptions about identity. SOUL.md makes those explicit. The agent's system prompt can then be terse: "You are Agent-Coordinator. See SOUL.md for full context. Your immediate task: [specific objective]." It works because multi-agent conflicts almost never happen at the logic level. They happen at the boundary level—two agents claiming the same responsibility, or neither claiming it. SOUL.md clarifies ownership upfront. It works because it's a communication tool. When a human needs to understand what an agent *should* be doing, SOUL.md is the canonical source. When an agent is misbehaving, SOUL.md is the spec to debug against. And it works because it's versioned and evolved. Unlike a system prompt (which gets long and brittle), a SOUL.md document is meant to be updated. When you discover the agent needs new constraints, you update section 4. When you realise it should escalate more, you update section 5. The history is there. ## Cross-Links in The Hive Doctrine Marketplace - **Honey:** The Persona Forge collection includes detailed persona templates. Use these to flesh out Voice and Identity sections. - **Nectar:** The "Industry Persona Kit" provides pre-built SOUL.md templates for common agent roles (Research, Executor, Coordinator, Guard). Use them as starting points. ## What's Next Build your first SOUL.md. Fill it in for an agent you're deploying this week. Share it with your team (human and agent). Notice what becomes clear. Notice what you have to figure out that you hadn't thought about before. The SOUL.md standard works best at scale, but it starts with one agent and one document. Start there. --- *The Hive Doctrine marketplace. Free, open, and designed for agent operators who take identity seriously.* --- *From The Hive Doctrine — hivedoctrine.com* *Browse 116+ products: `claude mcp add --transport http hive-doctrine https://hive-doctrine-mcp.vercel.app/mcp`* *The field, not the flower.*