--- title: SOUL.md description: "A Markdown workspace convention for an agent's persona, tone, values, and behavioral boundaries, loaded as instructions by a compatible harness." canonical_url: 'https://darkfactory.dev/glossary/soul-md' markdown_url: 'https://darkfactory.dev/glossary/soul-md.md' collection: glossary date_published: '2026-10-07T00:00:00-04:00' date_modified: '2026-10-07T00:00:00-04:00' --- # SOUL.md ## Definition SOUL.md is a Markdown workspace convention for instructions about an agent's persona, tone, values, and behavioral boundaries. A compatible agent harness reads the file and supplies its contents to the model. In OpenClaw, the workspace documentation assigns SOUL.md the persona-and-tone role, and the personality guide recommends concise, specific instructions with an observable effect on behavior. The filename alone has no execution semantics. Another application can adopt the name while loading it differently, or can ignore the file altogether. Its effect depends on the harness, the instruction layer used, and the other instructions in the request. ## Origin and attribution The convention is documented in the project now called OpenClaw. A repository commit dated December 19, 2025 contains a workspace template for SOUL.md that describes the assistant's persona and boundaries. That is a dated public example, not proof of the filename's first use anywhere. Peter Steinberger created the surrounding project, but the repository evidence does not establish a sole inventor of the broader idea of recording an agent's character in a document. The project-linked soul.md essay, credited to its Clawd assistant persona, describes a soul document as continuity of identity across sessions. It connects that framing to reports about a training document used for Claude. Anthropic's January 2026 constitution announcement separately confirms that its constitution shapes Claude through training. A local SOUL.md file supplies runtime instructions; editing it does not rewrite the model's weights or replace its training constitution. ## Scope and terminology OpenClaw's template includes guidance on communication, privacy, and keeping the user informed when the agent changes the file. The personality guide warns against turning it into an activity log or a long security-policy document. Detailed task procedures and user information have other workspace locations. The word soul is a metaphor for specified behavior and continuity. A file can preserve a description of identity without demonstrating subjective experience, consciousness, or moral status. The philosophical language in the soul.md essay goes beyond what the workspace-loading mechanism establishes. Harnesses choose their own loading rules for this convention. OpenClaw's prompt documentation distinguishes normal sessions, native Codex delivery, and subagent context. A file loaded for the main assistant should not be assumed to reach every child agent. Check the active harness and its current loading rules. ## Operational significance Write behavior a person can recognize and evaluate: how directly the agent should answer, when it should admit uncertainty, and how it should represent itself in shared conversations. Keep the file versioned so a change in behavior can be traced to an instruction change. Review agent-written edits because changing persona instructions can also change future decisions. Treat behavioral boundaries as guidance to the model. File access, spending limits, and permission to send messages need enforcement in the surrounding application. SOUL.md is not a secure place for credentials, and a rule in prose does not confine a tool that already has broader access. ## Distinguish it from nearby terms - A system prompt is a runtime instruction layer. SOUL.md is a possible input to its assembly; provider roles and harness delivery determine its actual authority. - Agent memory retains prior state for later use. SOUL.md usually supplies a compact behavior contract, while event history and learned user facts belong in the memory system. - AGENTS.md carries operating instructions in OpenClaw. SOUL.md concentrates on persona and tone; other harnesses can draw these boundaries differently. - Alignment concerns how a model or system behaves relative to intended goals and constraints. Editing a persona file is one intervention, with an effect that still needs evaluation. - Anthropic's constitution is a training artifact and declared behavioral framework for Claude. A workspace persona file is configured at runtime by the agent operator. ## Check your understanding An agent's SOUL.md says it must ask before sending email, but the email tool accepts any call without an approval check. What does the file change, what remains unenforced, and how would you verify whether a delegated child agent received the same instruction? ## Also called SOUL.md file ## Related terms - [OpenClaw](https://darkfactory.dev/glossary/openclaw) - [Personal agent](https://darkfactory.dev/glossary/personal-agent) - [System prompt](https://darkfactory.dev/glossary/system-prompt) - [Context engineering](https://darkfactory.dev/glossary/context-engineering) - [Agent harness](https://darkfactory.dev/glossary/agent-harness) - [Agent memory](https://darkfactory.dev/glossary/agent-memory) - [Durable memory](https://darkfactory.dev/glossary/durable-memory) - [Anthropomorphism](https://darkfactory.dev/glossary/anthropomorphism) - [Prompt injection](https://darkfactory.dev/glossary/prompt-injection) - [Least privilege](https://darkfactory.dev/glossary/least-privilege) - [AI alignment](https://darkfactory.dev/glossary/alignment) - [Claude](https://darkfactory.dev/glossary/claude) - [Hermes Agent](https://darkfactory.dev/glossary/hermes-agent) ## Related factory areas - [Context, memory, knowledge & skills](https://darkfactory.dev/factory/context-memory-skills) - [Intent capture & requirements](https://darkfactory.dev/factory/intent-requirements) - [Security, privacy & software supply chain](https://darkfactory.dev/factory/security) ## Evidence and further reading - [OpenClaw lineage: December 2025 SOUL.md template](https://github.com/openclaw/openclaw/blob/590f3d0e8f285d02e594cd718bfe9350ea5ee267/docs/templates/SOUL.md) - [OpenClaw: SOUL.md template](https://docs.openclaw.ai/reference/templates/SOUL) - [OpenClaw: SOUL.md personality guide](https://docs.openclaw.ai/concepts/soul) - [OpenClaw: agent workspace](https://docs.openclaw.ai/concepts/agent-workspace) - [OpenClaw: system prompt assembly](https://docs.openclaw.ai/concepts/system-prompt) - [OpenClaw: security trust model](https://docs.openclaw.ai/gateway/security/trust-model) - [SOUL.md: project-linked identity essay](https://soul.md/) - [Anthropic: Claude’s new constitution](https://www.anthropic.com/news/claude-new-constitution)