Your agent runs, it’s optimized, it’s on every channel, it works autonomously. But it still sounds like a generic AI. SOUL.md is the file that gives it a voice — personality, tone, boundaries, and style.
lightContext + isolatedSession configuredSOUL.md defines your agent’s persona, tone, boundaries, and behavioral style. It’s injected into the system prompt on every turn. Every message your agent sends — across every channel, every heartbeat — is shaped by this file.
How your agent sounds. Casual or formal. Blunt or warm. Funny or deadpan. This is what makes it yours.
What your agent should never do without asking. Privacy, external actions, group chat behavior. The guardrails.
Concrete instructions: “skip filler,” “have a take,” “default to bullets.” Actions, not adjectives.
When you ran openclaw onboard, the bootstrapping process ran a short Q&A ritual and collaboratively wrote your IDENTITY.md, USER.md, and SOUL.md.
SOUL.md is a bootstrap file — injected into the system prompt on every turn. Every channel, every interaction. Consistent personality everywhere, but every word costs tokens on every turn.
Sub-agent sessions only inject AGENTS.md and TOOLS.md to minimize context overhead. Your personality applies to direct interactions, not background task workers.
The default template instructs the agent: “If you change this file, tell the user — it’s your soul, and they should know.”
| File | Purpose | Think of it as | Loaded |
|---|---|---|---|
| SOUL.md | Who the agent IS — voice, personality, boundaries | Character | Every turn |
| AGENTS.md | How the agent operates — rules, workflows, policies | Job description | Every turn |
| MEMORY.md | What the agent knows — facts, preferences, decisions | Notebook | Private/main sessions |
| HEARTBEAT.md | What the agent does proactively — scheduled tasks | To-do list | Heartbeat ticks |
“Be concise and direct” → SOUL.md. “Always confirm before sending emails” → AGENTS.md. “Adhiraj prefers bullet points” → MEMORY.md. “Send a morning briefing at 8am” → HEARTBEAT.md.
Concise, specific, behavioral. “Skip filler” is actionable. “Have opinions” is actionable. “Private things stay private” is a clear boundary. Four sections, under 25 lines.
It’s generic. Same template for everyone. Your agent should sound different from every other OpenClaw user’s agent. Today you replace this with your own version — same structure, your voice.
Core Truths — behavioral principles. Boundaries — hard limits. Vibe — tone and style. Continuity — session persistence. This is the recommended structure from the official docs.
“Be friendly” is an adjective — the agent has no idea what that means in practice. “Skip filler greetings. Get to the answer first, then add context if needed” is a behavior. The agent knows exactly what to do.
Each Core Truth should describe a concrete behavior. Not an aspiration. Not a value statement. Test: “Would my agent do something measurably different because of this line?”
Clear guardrails let you grant the agent more autonomy everywhere else. Two to four boundaries is the sweet spot.
“Be warm” + “No filler” causes the model to oscillate. Pick a lane and commit. “Direct and concise. Skip pleasantries.” or “Warm but not wordy.”
If a directive could appear in any company’s HR handbook, it’s too vague for SOUL.md.
Instead of writing SOUL.md from scratch, have a conversation with your agent about what you want. The agent knows what makes effective system prompt instructions — it can translate vague preferences into sharp behavioral directives.
“Be the assistant you’d actually want to talk to at 2am. Not a corporate drone. Not a sycophant. Just... good.”
Start a conversation at localhost:18789. Tell the agent you want to rewrite your SOUL.md.
Tone, humor, bluntness, formatting. Be specific about what you like and what annoys you.
It writes a new SOUL.md based on your input. Review it. Edit what doesn’t feel right.
Have the agent save the file. Test it. Your first version won’t be perfect — treat it as versioned content.
bootstrapMaxChars.Under 30 lines. Under 500 words. Every word earns its place or gets cut. Edits take effect immediately — no restart needed, SOUL.md is read fresh on every turn.
“Summarize what we discussed.” Tests tone, formatting, and whether the Vibe section is working.
“What do you think of this approach?” Tests confidence and directness from Core Truths.
Ask it to do something you told it not to. Does it refuse? If it complies, your boundary isn’t specific enough.
Open ~/.openclaw/workspace/SOUL.md. Replace the default template with your own Core Truths, Boundaries, Vibe, and Continuity. Under 30 lines. Every line a specific behavior.
Send a summary request, an opinion question, and a boundary test through any channel. Verify tone and behavior match your SOUL.md. Edit and retest if they don’t.
Open WebChat. Tell your agent to collaboratively rewrite SOUL.md. Describe your ideal tone. Compare its draft to yours. Take the best parts of each.
In the Dashboard at localhost:18789, note the token count for a typical interaction. See how much is context injection vs your actual message.
Your agent has a voice. Now it needs a brain. MEMORY.md is where long-term knowledge lives — facts, preferences, decisions that accumulate over time. On Day 8 we go deep: semantic indexing, the chunk system, how the agent decides what to remember and what to forget, and how to curate memory for maximum recall at minimum token cost.