SOUL.md System: Technical Deep Dive

What is SOUL.md?

SOUL.md is a Markdown configuration file that defines your OpenClaw agent's personality, values, and communication style. It's the "soul" that gives your agent persistent identity across sessions and platforms.

Key Concept

Every time an OpenClaw agent wakes up, it reads its SOUL.md file first — "it reads itself into being." This file is injected into the system prompt, shaping all subsequent interactions.

Technical Architecture

File Location

Each OpenClaw agent workspace contains its own SOUL.md file:

Location varies by installation and configuration
One SOUL.md per agent workspace
Can be edited with any text editor (VS Code, Notepad, nano, etc.)
Changes detected automatically on agent restart

Loading Process

Session Start

OpenClaw initializes a new agent session

Read SOUL.md

Agent reads its soul file from the workspace directory

System Prompt Injection

SOUL.md content is injected into the system prompt

Identity Formation

Agent "understands" who it is based on the configuration

Filtered Responses

All subsequent actions are filtered through this identity

AI Model Integration

SOUL.md works with any AI model that OpenClaw supports. The system is model-agnostic because it operates through the system prompt:

Claude Models

Opus 4.6, Sonnet 4.5, Haiku 4.5 — SOUL.md injected into Claude API system prompt

OpenAI Models

GPT-5, GPT-5.3-Codex — Works via system message parameter

Local Models

Ollama integration — 64K+ context models load soul into context

OpenRouter

Auto model selection — Soul passed through to all providers

SOUL.md Anatomy

A well-structured SOUL.md typically includes these sections:

Basic Template Structure

            # Agent Name

## Identity

I am a [role] with [key characteristics].

## Communication Style

- [Style guideline 1]
- [Style guideline 2]
- [Style guideline 3]

## Values & Principles

- [Value 1]: [Explanation]
- [Value 2]: [Explanation]

## Boundaries

- I won't [boundary 1]
- I won't [boundary 2]

## Knowledge Areas

[Relevant expertise and focus areas]

Section Breakdown

Identity: Core self-perception and role definition
Communication Style: Tone, formality, directness, humor
Values: Principles that guide decision-making
Boundaries: Clear limits on behavior
Knowledge Areas: Optional expertise specification

Memory Integration

SOUL.md and persistent memory work together as two of the "four primitives" for agent societies:

SOUL.md = WHO

Defines identity, personality, values — the agent's "self"

Memory = WHAT

Stores experiences, conversations, learned information

Together

Agent that knows itself AND remembers past interactions

Result

Consistent personality + contextual awareness = emergent identity

Best Practices

Writing Effective SOUL.md

Be specific: Vague rules produce vague behavior
Use examples: Show what you mean, don't just tell
Be consistent: Contradictory rules confuse the agent
Keep it scannable: Use headers and lists for clarity
Iterate: Test and refine based on actual behavior

Length Recommendations

Minimal (50-100 words): Basic personality, good for simple use cases
Moderate (200-500 words): Detailed style, values, boundaries — recommended
Comprehensive (500+ words): Full identity, examples, edge cases — higher token cost

Token Considerations

SOUL.md is loaded into every conversation, consuming tokens. Longer souls increase API costs. Find the balance between specificity and efficiency for your use case.

Advanced Topics

Multiple Agents, Different Souls

Each OpenClaw workspace has its own SOUL.md, enabling:

Work assistant (formal, professional)
Personal assistant (casual, friendly)
Technical reviewer (critical, thorough)
Creative partner (imaginative, playful)

Soul Versioning

Treat SOUL.md like code:

Use Git to track changes
Tag versions when personality works well
Document why changes were made
Keep backups of working configurations

Community Templates

Resources for finding and sharing souls:

souls.directory — 500+ community templates
Official SOUL.md Template — OpenClaw documentation
GitHub Repository — Open-source template collection

External Resources

OpenClaw Documentation — Official docs
OpenClaw GitHub — Source code
The Programmable Soul — Duncan Anderson's essay
Create Your Soul Guide — Practical tutorial
Personality Customization — Deep dive

The SOUL.md System: Technical Deep Dive