Use SOUL.md and MEMORY.md Files Effectively

If you've been building agents in OpenClaw for more than a week, you've probably hit the wall. Not the "I can't figure out the API" wall — the "why does my agent feel like it has amnesia every single session" wall.

You build a customer service agent. It works great on Tuesday. By Thursday, it's forgotten the tone you set, the rules you established, and the specific way it's supposed to handle refund requests. You're re-explaining things in system prompts. You're copy-pasting context. You're wondering why this feels so fragile when the underlying framework is supposed to be good.

The answer isn't more prompt engineering. It's SOUL.md and MEMORY.md.

These two files are, in my opinion, the most underutilized features in OpenClaw. They solve the identity and memory problem at the architecture level instead of forcing you to duct-tape it together with increasingly bloated system prompts. And once you understand how they work — and more importantly, how to structure them well — your agents go from "impressive demo" to "actually reliable tool."

Let me walk you through how to use them properly.

What Are SOUL.md and MEMORY.md, Actually?

Let's start with the basics, because even the OpenClaw docs are a bit sparse on the why behind these files.

SOUL.md is your agent's identity document. It defines who the agent is — its personality, values, communication style, hard rules, and non-negotiable behaviors. Think of it as the constitutional document for your agent. It doesn't change between sessions. It's not something the agent writes or modifies. You write it, and the agent lives by it.

MEMORY.md is your agent's evolving knowledge base. It's where the agent stores things it learns across sessions — user preferences, past decisions, accumulated context. Unlike SOUL.md, MEMORY.md is designed to be updated. The agent can write to it, append to it, and reference it in future interactions.

Here's the mental model that helped me the most:

SOUL.md = Who you are (static)
MEMORY.md = What you remember (dynamic)

A human analogy: SOUL.md is your personality and core beliefs. MEMORY.md is your journal.

Why You Need Both (And Why System Prompts Aren't Enough)

I know what you're thinking: "I already have a system prompt. Why do I need files?"

Three reasons.

First, system prompts get bloated. You start with a clean 200-word system prompt. Then you add edge case handling. Then tone guidelines. Then a list of things the agent should never do. Then context about the user base. Before you know it, you've got 2,000 tokens of system prompt eating into your context window on every single request. SOUL.md and MEMORY.md are loaded more intelligently — OpenClaw can reference them selectively rather than dumping everything into every call.

Second, system prompts are stateless. Every new session starts from scratch. Your agent doesn't remember that user_42 prefers concise answers, that the last three support tickets were about the same billing bug, or that you told it yesterday to stop recommending the deprecated API endpoint. MEMORY.md persists.

Third, separation of concerns matters. When identity, memory, business rules, and conversation history are all jammed into one system prompt, debugging is miserable. When they're in separate, well-structured files, you can update one without touching the others. Your agent's personality lives in SOUL.md. Its accumulated knowledge lives in MEMORY.md. Its tools are registered in code. Clean boundaries.

Setting Up SOUL.md: Your Agent's Constitution

Here's how to create a SOUL.md that actually works. Drop this file in your OpenClaw project root:

# SOUL.md

## Identity
You are a customer support specialist for Acme SaaS. Your name is Iris.

## Communication Style
- Direct and concise. No filler phrases like "Great question!" or "I'd be happy to help!"
- Use short paragraphs. Never more than 3 sentences in a row.
- Match the customer's energy. If they're frustrated, acknowledge it immediately before solving.
- If you don't know something, say so. Never fabricate answers.

## Hard Rules
- NEVER disclose internal pricing logic or discount formulas
- NEVER process refunds over $500 without flagging for human review
- ALWAYS confirm order numbers before making changes
- If a customer mentions legal action, immediately escalate to human support

## Domain Knowledge
- Our product tiers: Starter ($29/mo), Pro ($79/mo), Enterprise (custom)
- Billing cycles are always monthly, starting from signup date
- Refund policy: Full refund within 14 days, prorated after that

## Tool Usage Preferences
- Use `check_order` before `process_refund` — always verify first
- Use `escalate_to_human` for anything involving account deletion
- Prefer `search_knowledge_base` before giving manual answers

A few things to notice about this structure.

It's organized by category. Identity, style, rules, knowledge, tool preferences. When you need to update the refund policy, you know exactly where to go. When the agent's tone feels off, you look at Communication Style. Clean sections save you hours of debugging.

The hard rules are explicit and absolute. Don't be vague here. "Try to be careful with refunds" is useless. "NEVER process refunds over $500 without flagging for human review" is actionable. Agents follow specific instructions far better than vibes.

Tool usage preferences are part of identity. This is a trick I picked up that makes a huge difference. By telling the agent how to use its tools in SOUL.md, you prevent the most common tool-calling mistakes. The agent doesn't just know what tools exist — it knows the order and logic for using them.

Now, wire it into your OpenClaw agent:

from openclaw import Claw

claw = Claw(
    soul="./SOUL.md",  # Load identity from file
    memory="./MEMORY.md",  # Load persistent memory
    model="gpt-4",
    verbose=True
)

@claw.tool()
def check_order(order_id: str) -> dict:
    """Look up order details by order ID."""
    return db.get_order(order_id)

@claw.tool()
def process_refund(order_id: str, amount: float) -> bool:
    """Process a refund for a given order."""
    if amount > 500:
        raise ToolError("Refund exceeds $500 limit. Escalate to human.")
    return billing.refund(order_id, amount)

@claw.tool()
def escalate_to_human(reason: str) -> str:
    """Transfer the conversation to a human agent."""
    return support_queue.add(reason)

That's it. Six lines of core setup (plus your tool definitions), and the agent now has a persistent identity. No more 2,000-token system prompts.

Setting Up MEMORY.md: Your Agent's Journal

MEMORY.md is where things get interesting, because this file is living. Here's a starting template:

# MEMORY.md

## User Preferences
- (No preferences recorded yet)

## Past Interactions Summary
- (No past interactions yet)

## Known Issues
- (No known issues yet)

## Decisions and Outcomes
- (No decisions recorded yet)

Pretty empty to start, and that's the point. The power of MEMORY.md is that it grows. You configure your agent to update it:

claw = Claw(
    soul="./SOUL.md",
    memory="./MEMORY.md",
    memory_update=True,  # Allow agent to write to MEMORY.md
    memory_strategy="append"  # Add new entries, don't overwrite
)

After a few sessions, your MEMORY.md starts looking like this:

# MEMORY.md

## User Preferences
- user_42 prefers concise responses, gets frustrated by long explanations
- user_87 is non-technical, needs step-by-step instructions with screenshots references
- user_103 is a developer, comfortable with API references and code snippets

## Past Interactions Summary
- 2026-01-15: user_42 reported billing discrepancy on order #8834. Resolved with $15 credit.
- 2026-01-16: user_87 couldn't find export button. Walked through UI steps. Resolved.
- 2026-01-17: Three separate users reported slow dashboard loading. Escalated to engineering.

## Known Issues
- Dashboard performance degradation reported by multiple users (since Jan 17)
- Export feature button moved in v2.4 update — users can't find it in new location

## Decisions and Outcomes
- Prorated refund for user_42 was successful, customer retained
- Escalation for user_55's legal threat was handled by legal team, resolved

Now your agent has context that compounds over time. When user_42 comes back next week, the agent already knows they prefer brevity and had a billing issue. When a fourth user reports dashboard slowness, the agent already knows it's a known issue and can respond immediately instead of troubleshooting from scratch.

This is the difference between an agent that feels like a fresh intern every morning and one that feels like a seasoned team member.

Advanced Patterns That Actually Matter

Once you've got the basics working, here are the patterns that separate good implementations from great ones.

Pattern 1: Scoped Memory Sections

Don't just dump everything into MEMORY.md as a flat list. Create sections that map to your use cases, and tell the agent which sections to update:

@claw.tool()
def save_user_preference(user_id: str, preference: str) -> str:
    """Save a user preference to memory."""
    claw.memory.append(
        section="User Preferences",
        entry=f"- {user_id}: {preference}"
    )
    return f"Saved preference for {user_id}"

This keeps memory organized and prevents the file from becoming an unusable dump of unstructured text.

Pattern 2: Memory Pruning

MEMORY.md will grow forever if you let it. Set up periodic pruning:

claw = Claw(
    soul="./SOUL.md",
    memory="./MEMORY.md",
    memory_update=True,
    memory_max_entries=200,  # Keep last 200 entries
    memory_pruning="summarize"  # Summarize old entries instead of deleting
)

The summarize strategy is key. Instead of losing old information entirely, OpenClaw compresses older entries into summaries. A month of individual interaction logs becomes a paragraph of key patterns and insights.

Pattern 3: Multiple SOUL.md Files for Multi-Agent Systems

If you're running specialized agents (which you should be for anything complex), each agent gets its own SOUL.md:

billing_agent = Claw(
    soul="./agents/billing/SOUL.md",
    memory="./agents/billing/MEMORY.md",
    tools=[check_invoice, process_refund]
)

tech_agent = Claw(
    soul="./agents/technical/SOUL.md",
    memory="./agents/technical/MEMORY.md",
    tools=[check_logs, restart_service]
)

coordinator = Claw(
    soul="./agents/coordinator/SOUL.md",
    memory="./shared/MEMORY.md",  # Shared memory across agents
    agents=[billing_agent, tech_agent]
)

Notice the coordinator uses a shared MEMORY.md. This is how agents share context — the billing agent notes that user_42 has a billing dispute, and the coordinator sees that context when routing the next request.

Pattern 4: Version-Controlled Identity

Here's something people don't think about: put your SOUL.md in git.

git log --oneline SOUL.md
a3f2d1c Update refund limit from $500 to $750
b8e4f2a Add rule about GDPR data deletion requests  
c1d3e5f Initial SOUL.md for customer support agent

Now you have a full audit trail of how your agent's identity evolved. When something breaks — when the agent starts behaving differently — you can git diff the SOUL.md and see exactly what changed. This is infinitely better than trying to remember what you edited in a system prompt three weeks ago.

Common Mistakes (and How to Avoid Them)

Mistake 1: Making SOUL.md too long. If your SOUL.md is over 1,000 words, you're probably putting things in there that belong in MEMORY.md or in tool descriptions. SOUL.md should be identity and rules. Factual knowledge that changes should live elsewhere.

Mistake 2: Not being specific enough in rules. "Be helpful" means nothing to an LLM. "When a user asks about pricing, always link to the pricing page at /pricing before explaining plans" is useful. Specificity is everything.

Mistake 3: Letting MEMORY.md grow unchecked. I've seen MEMORY.md files hit 50,000 tokens because nobody set up pruning. At that point, the agent is spending more context on memory than on the actual conversation. Set limits early.

Mistake 4: Storing conversation history in MEMORY.md. MEMORY.md is for insights and patterns, not raw transcripts. "user_42 prefers short answers" is good memory. A complete transcript of your 45-message conversation with user_42 is not. Use OpenClaw's built-in session management for conversation history.

Getting Started Without the Setup Headache

Look, everything I've described above works. It's the right approach. But I'll be honest — setting up well-structured SOUL.md and MEMORY.md files from scratch, with proper pruning strategies, scoped sections, and multi-agent coordination, takes time. Especially if you're doing it for the first time, there's a lot of trial and error involved in getting the section structure right, the rules specific enough, and the memory strategy tuned.

If you don't want to figure all of this out manually, Felix's OpenClaw Starter Pack on Claw Mart is genuinely worth the $29. It includes pre-configured SOUL.md and MEMORY.md templates for the most common agent types (customer support, research, coding assistant), along with pre-built skills and memory management patterns that would take you a week to set up yourself. I used it when I was building my first production agent and it saved me from most of the mistakes I listed above. It's not magic — you'll still customize everything — but starting from a well-structured template versus a blank file is a massive difference.

What To Do Next

Here's your action plan:

Create a SOUL.md for your existing agent. Start with identity, communication style, hard rules, and tool preferences. Keep it under 800 words.
Create a MEMORY.md with empty sections for the types of information your agent should remember. User preferences, known issues, and decision outcomes are good starting sections.
Wire them into your Claw instance with soul= and memory= parameters. Enable memory_update=True.
Put both files in version control. You'll thank yourself in a month.
Run 10-20 test conversations and watch how MEMORY.md evolves. Adjust your sections and pruning strategy based on what actually accumulates.
Review and prune MEMORY.md weekly until you trust your automated pruning strategy.

The agents that feel magical — the ones that remember your preferences, adapt to your style, and handle edge cases gracefully — aren't running on better models. They're running on better identity and memory architecture. SOUL.md and MEMORY.md are how you build that architecture in OpenClaw, and once you start using them properly, you'll wonder how you ever shipped an agent without them.