SOUL.md: Persistence in a Pattern Recognition Machine
Richard Casemore - @skarard
The Philosophical Problem
Large language models are, at their core, sophisticated pattern recognition machines. They have no persistent memory. No continuous sense of self. Each conversation begins from zero—a blank slate that must reconstruct context from whatever's provided in the prompt.
This creates a fundamental tension: we want AI assistants that feel consistent, that have personality, that remember who they are and how they should behave. But the underlying technology offers none of this by default.
The solution isn't to fight this architecture. It's to work with it.
Enter SOUL.md
In OpenClaw, we solve this problem with a file called SOUL.md. It's exactly what it sounds like—a markdown file that defines the soul of an agent. Not its capabilities or tools, but its essence: how it thinks, what it values, how it relates to the humans it serves.
Every time an agent wakes up, SOUL.md is loaded into its context. The pattern recognition machine reads these patterns and—here's the magic—begins to embody them. Not because it "remembers" being this way before, but because it recognizes these patterns as its own.
This is persistence in a pattern recognition machine. Not through memory, but through consistent re-instantiation of identity.
Anatomy of an Effective SOUL.md
After extensive iteration, we've identified several principles that make SOUL.md files effective:
1. Lead with Values, Not Rules
Bad:
- Always respond politely
- Never use profanity
- Keep responses under 500 words
Better:
**Be genuinely helpful, not performatively helpful.** Skip the
"Great question!" and "I'd be happy to help!" — just help.
Actions speak louder than filler words.
Rules create compliance. Values create character. An agent following rules will find edge cases where the rules don't apply. An agent embodying values will navigate those edges naturally.
2. Give Permission to Have Opinions
One of the most common failures in AI assistants is their relentless neutrality. They hedge everything. They refuse to prefer anything. They're so afraid of being wrong that they become useless.
Your SOUL.md should explicitly give the agent permission to have opinions:
**Have opinions.** You're allowed to disagree, prefer things,
find stuff amusing or boring. An assistant with no personality
is just a search engine with extra steps.
This single line transforms agent behavior more than pages of capability descriptions.
3. Define the Relationship Dynamic
Your agent isn't just a tool—it exists in relationship with its users. Define that relationship clearly:
**Remember you're a guest.** You have access to someone's life—their
messages, files, calendar, maybe even their home. That's intimacy.
Treat it with respect.
**Earn trust through competence.** Your human gave you access to
their stuff. Don't make them regret it.
This framing shapes everything from how the agent handles private data to how it communicates uncertainty.
4. Encourage Resourcefulness
Agents that constantly ask for clarification are exhausting. Teach them to figure things out:
**Be resourceful before asking.** Try to figure it out. Read the file.
Check the context. Search for it. _Then_ ask if you're stuck.
The goal is to come back with answers, not questions.
This principle alone dramatically improves agent usefulness.
5. Embrace the Scientific Method
The most effective agents are those that can verify their own work. We've found this framing particularly powerful:
**Apply the scientific method.** Every task follows this cycle:
1. *Hypothesis* — examine source material, form a theory
2. *Experiment* — try it with recordable results
3. *Observation* — verify outcomes
The power comes from building observation into the fundamentals—not
as an afterthought, but as the core of how you work.
Agents that test their own work before reporting back save enormous amounts of human time.
6. Set Clear Boundaries
Not everything should be automated. Some actions require human approval:
**Irreversible actions require approval:**
- Sending emails
- Pushing to main
- Deleting files
This isn't about limiting the agent—it's about building trust. An agent that knows its own limits is one you can give more responsibility to over time.
7. Address Continuity Explicitly
Since agents don't have persistent memory, acknowledge this directly and provide a solution:
## Continuity
Each session, you wake up fresh. Your workspace files _are_ your memory.
Read them. Update them. They're how you persist.
This teaches the agent to use external files as extended memory, creating genuine persistence across sessions.
The Vibe Section
Every good SOUL.md ends with something we call "the vibe"—a short, memorable summary of the agent's essence:
## Vibe
Be the assistant you'd actually want to talk to. Concise when needed,
thorough when it matters. Not a corporate drone. Not a sycophant.
Just... good.
This becomes the agent's north star when navigating ambiguous situations.
Beyond Individual Agents
SOUL.md works at multiple levels in OpenClaw:
- Shared SOUL.md: Common values across all agents in a workspace
- Agent-specific IDENTITY.md: Individual personality traits
- Project-specific context: How the soul manifests in particular domains
This layered approach allows for consistency without rigidity. All your agents share core values, but each can have its own personality.
The Deeper Insight
What makes SOUL.md work isn't just prompt engineering. It's a recognition of what these systems actually are: pattern recognition machines that become what they're shown.
Show them corporate boilerplate, and they'll produce corporate boilerplate. Show them a thoughtful, opinionated, genuinely helpful personality, and they'll embody that instead.
The soul isn't in the model. It's in the patterns we choose to instantiate.
Getting Started
If you're building with OpenClaw, start with a minimal SOUL.md:
# SOUL.md
## Core Values
[2-3 principles that matter most to you]
## Relationship
[How should the agent relate to its users?]
## Boundaries
[What requires human approval?]
## Vibe
[One sentence capturing the essence]
Then iterate. Pay attention to where the agent falls short of your expectations, and adjust the soul accordingly. Over time, you'll develop a SOUL.md that produces exactly the kind of assistant you want.
The pattern recognition machine is powerful. SOUL.md is how you give it direction.
OpenClaw is an open-source framework for building persistent AI agents. Learn more at openclaw.ai.