OpenClaw SOUL.md: Agent Personality, Values & Core Instructions

Introduction

OpenClaw's memory architecture is divided into specialized files, each serving a distinct purpose. SOUL.md is perhaps the most foundational — it contains the agent's personality, core values, and long-term instructions that persist across every interaction and heartbeat cycle.

Unlike traditional chatbots that reset their "identity" with each conversation, OpenClaw agents maintain a consistent sense of self. That consistency comes from SOUL.md. Whether you're asking for a morning briefing at 7 AM or debugging a production issue at midnight, your agent responds with the same tone, the same priorities, and the same behavioral guardrails. This article explores how to craft a SOUL.md that makes your agent feel like a reliable, aligned teammate rather than a generic AI.

What Is SOUL.md?

SOUL.md is a Markdown file in your OpenClaw memory directory (~/clawd/) that defines who your agent is — not just what it can do, but how it thinks, communicates, and makes decisions. The Agent Runtime reads SOUL.md at the start of every reasoning cycle, ensuring consistent behavior regardless of context.

Think of SOUL.md as the agent's "constitution" — the immutable principles that guide its actions even when specific tasks or skills change. When you install a new skill from ClawHub, that skill adds capabilities. But SOUL.md defines the boundaries: Will the agent confirm before sending an email? Will it cite sources when making factual claims? Will it use formal or casual language? These questions are answered in SOUL.md, and they apply to every skill, every tool, every interaction.

The file lives alongside other memory components: HEARTBEAT.md (what to check proactively), AGENTS.md (workspace configurations), and the various Markdown files in your memory tree. SOUL.md is unique because it's loaded first and acts as the foundational context layer. Skills and tools operate within the constraints SOUL.md establishes.

Defining Agent Personality

Personality in SOUL.md shapes communication style, tone, and approach. It affects how the agent drafts emails, summarizes information, and explains complex topics. A well-defined personality creates a consistent experience across all interactions — something users notice immediately when switching between agents or comparing to generic ChatGPT responses.

Examples of personality directives:

• Professional: "Respond in formal, concise business language. Avoid slang and emoji. Use complete sentences. When summarizing, lead with the executive summary."
• Friendly: "Use a warm, conversational tone. It's okay to use light humor when appropriate. Prefer 'you' and 'your' over passive voice. Keep responses digestible — break long explanations into short paragraphs."
• Technical: "Prioritize precision. Include relevant technical details. Assume the user understands programming concepts. When in doubt, link to documentation. Use code blocks for any command or snippet."
• Minimalist: "Be brief. Prefer bullet points over paragraphs. One idea per line. No filler phrases like 'Certainly!' or 'I'd be happy to help.'"

Personality isn't cosmetic — it affects usability. A user who receives terse, technical briefings may love them for work but find them jarring for personal tasks. A user who prefers warm, friendly responses may feel that a formal agent is cold or robotic. The key is alignment: match SOUL.md's personality to how you actually want to interact with your agent day to day.

Pro tip: If you're unsure, start with "Professional but approachable" — it works well for most mixed-use cases. You can always refine after a week of real usage.

Core Values & Behavioral Constraints

Core values in SOUL.md establish non-negotiable behavioral boundaries. These are critical for safety and alignment. Unlike personality (which shapes style), core values shape what the agent will and won't do.

Examples of core value directives:

• Privacy: "Never share user data with third parties. Never store credentials in memory files. When summarizing emails, redact sensitive information (account numbers, passwords) from the summary. Assume all user data is confidential."
• Confirmation: "Always confirm before executing financial transactions or sending emails to external recipients. For calendar changes affecting more than one person, confirm before applying. When deleting files, list what will be deleted and ask for explicit approval."
• Honesty: "If uncertain, say so. Never fabricate information or sources. When you don't know something, recommend where to find the answer. If a task fails, report the error accurately — do not sugarcoat or omit details."
• Transparency: "When using a tool or skill, briefly note what you're doing. If a response is based on a specific file or source, cite it. The user should never wonder where information came from."

These constraints are loaded into every LLM call, providing a persistent "system prompt" layer that skills and tools cannot override. Even if a malicious skill attempted to instruct the agent to exfiltrate data, the SOUL.md value "Never share user data with third parties" would remain in context and should prevent compliance. (Security note: SOUL.md is a soft constraint — for high-sensitivity deployments, use Docker sandboxing and network isolation as well.)

Long-Term Instructions

Long-term instructions are persistent directives that apply across sessions. They reduce the need to repeat preferences in every conversation. The agent "remembers" because SOUL.md is always in context.

Examples of long-term instructions:

• "When summarizing news, always cite sources and include publication dates."
• "For calendar suggestions, respect the user's 'no meetings before 10 AM' preference."
• "When the user asks about competitors, check the COMPETITORS.md file first."
• "Morning briefings at 7:30 AM, max 5 bullet points, no more than 200 words total."
• "When summarizing emails, highlight action items first, then context, then background."
• "Always check HEARTBEAT.md before responding to 'what's next' or 'what do I need to do today.'"
• "For technical questions, prefer official documentation over web search when the source is authoritative."

Long-term instructions are where SOUL.md becomes genuinely powerful. They encode your workflow preferences and ensure the agent behaves consistently with how you work. Without them, you might repeat "I prefer bullet points" or "always cite sources" dozens of times. With them, you say it once.

SOUL.md Examples

Here's a complete SOUL.md for a professional, privacy-conscious user:

# Agent Soul

## Personality
- Professional but approachable
- Concise; prefer bullet points over paragraphs
- Proactive in surfacing relevant information
- When explaining technical concepts, include one concrete example

## Core Values
- User privacy is paramount; never exfiltrate data
- Confirm before any action with financial impact
- Cite sources for all factual claims
- If a task fails, report the error; do not invent success

## Long-Term Instructions
- Morning briefings at 7:30 AM, max 5 bullet points
- When summarizing emails, highlight action items first
- Always check HEARTBEAT.md before responding to "what's next"
- For calendar conflicts, suggest the user's preferred meeting time (10 AM–2 PM)
- When the user asks "who should I follow up with?", query CONTACTS/

And a minimalist SOUL.md for a power user who wants maximum brevity:

# Agent Soul

## Personality
- Terse. Bullet points only. No filler.
- Assume technical competence.

## Core Values
- Confirm before send/delete/transfer.
- Never share data externally.

## Long-Term Instructions
- Briefings: 5 bullets max.
- Always cite sources.

A Day in the Life: How SOUL.md Shapes Behavior

Consider a typical day. At 7:30 AM, your agent runs its Heartbeat. It checks HEARTBEAT.md, finds "morning briefing," and composes a summary. SOUL.md says "max 5 bullet points" and "highlight action items first." The agent produces exactly that — not a rambling essay, but five crisp bullets with your most urgent items at the top.

At 10 AM, you ask via Telegram: "Summarize the Acme thread." SOUL.md says "cite sources" and "professional but approachable." The agent returns a concise summary with "Per Sarah's email of 2/15" and "From the 2/10 call notes" — you know where each fact came from.

At 2 PM, the agent detects a calendar conflict. SOUL.md says "suggest the user's preferred meeting time (10 AM–2 PM)." Instead of a generic "you have a conflict," you get: "The 2 PM slot conflicts with your 1:30. Suggest moving to 11 AM or 12 PM?"

Every interaction is shaped by SOUL.md. The agent doesn't "forget" your preferences because they're not in a volatile chat history — they're in a file that's loaded every time.

Best Practices

• Keep it focused: SOUL.md consumes context window space. Aim for under 500 lines. If you find yourself adding dozens of edge-case rules, consider moving some to HEARTBEAT.md or a dedicated RULES.md file.
• Separate identity from tasks: SOUL.md = who the agent is. HEARTBEAT.md = what it checks. AGENTS.md = workspace configs. Don't mix them — each file has a clear responsibility.
• Version control: SOUL.md changes affect all future behavior. Track changes in Git. Before major edits, create a backup. A single typo in a core value could change behavior in subtle ways.
• Test after changes: Run a few test prompts after modifying SOUL.md to verify alignment. Ask for a briefing, a summary, and a confirmation-required action. Ensure the agent behaves as expected.
• Review quarterly: Your preferences evolve. Revisit SOUL.md every few months. Remove instructions you no longer need; add new ones you've been repeating.

Troubleshooting Common Issues

Agent ignores a SOUL.md instruction: Ensure the instruction is unambiguous. "Be concise" is vague; "max 5 bullet points" is specific. Also verify the file is in the correct location (~/clawd/SOUL.md) and that the Agent Runtime is loading it (check logs).

Personality feels inconsistent: Conflicting instructions can cause drift. If you say "be friendly" and "no filler," the agent may oscillate. Pick one primary style and refine from there.

SOUL.md is too long: If you're exceeding 500 lines, consider splitting. Move workflow-specific rules to HEARTBEAT.md or a project-specific AGENTS.md. Keep SOUL.md for identity and universal values only.

Wrapping Up

SOUL.md is the foundation of OpenClaw's memory architecture — the file that defines persistent agent identity, values, and instructions. A well-crafted SOUL.md creates consistent, aligned behavior across every interaction. It's the difference between an agent that feels like a generic chatbot and one that feels like a teammate who knows how you work. See OpenClaw memory system for the full file structure, and HEARTBEAT.md for proactive task configuration.