Understanding OpenClaw Memory: How SOUL.md, MEMORY.md, and Persistent Context Actually Work

image: /blog/images/openclaw-memory-guide.png

Every AI assistant has the same fundamental problem: it forgets everything the moment a conversation ends. You explain your preferences, share context about your projects, describe how you like things done — and next session, it is all gone. You start over from scratch.

OpenClaw solves this differently than most platforms. Instead of opaque database entries or hidden embeddings, OpenClaw memory is built on something radically simple: plain Markdown files. Your agent's personality, its long-term memory, its operating rules — they all live in files you can read, edit, and version-control just like any other document.

This guide explains exactly how the OpenClaw memory system works, what each file does, and how to configure persistent context that makes your agent genuinely smarter over time.

How OpenClaw Memory Works

The core principle of OpenClaw memory is straightforward: every session starts fresh. The agent has zero built-in memory between conversations. What creates the illusion of continuous memory — and eventually the reality of a deeply personalized assistant — is a set of Markdown files that get loaded into the model's context window at the start of every session.

When your agent wakes up, it reads its workspace files in a specific order:

1. SOUL.md — who the agent is
2. AGENTS.md — how the agent should operate
3. USER.md — who it is helping
4. MEMORY.md — curated long-term knowledge (private sessions only)
5. Daily logs — today and yesterday's notes from memory/YYYY-MM-DD.md

This happens automatically, every time. No configuration needed. The agent reads these files the way a person might review their notes before a meeting — quickly scanning for context that matters right now.

The elegant part is that the agent can also write to these files during a session. Learn something important about the user's preferences? Write it to MEMORY.md. Complete a significant task? Log it in today's daily file. Make a mistake worth remembering? Update AGENTS.md with a new rule.

This creates a feedback loop: the agent reads its memory files, works with the user, writes back what it learned, and loads those updated files next session. Over days and weeks, the agent accumulates genuine institutional knowledge.

The Four Durability Layers

OpenClaw structures memory across four layers, each with a different lifespan:

Bootstrap files (SOUL.md, MEMORY.md, AGENTS.md, USER.md) are loaded from disk into the LLM context every session. They are permanent — surviving compaction, restarts, and crashes. These are the bedrock of OpenClaw persistent context.

Session transcript is the running log of the current conversation, stored as a JSONL file on disk. It persists within a session and gets summarized when it overflows the context window.

LLM context window is the in-memory view (roughly 200K tokens) of everything the model can currently "see" — files, history, tool results. It is temporary and gets compacted when full.

Retrieval index is a SQLite-based hybrid search (vector and keyword) over your Markdown files. It is permanent, automatically rebuilt from files, and updated when files change. This lets the agent semantically search its own memory when context alone is not enough.

What SOUL.md Does: Defining Agent Personality

SOUL.md is the single most important file for shaping how your agent behaves. Think of it as the agent's sense of self — its personality, communication style, values, and boundaries.

Here is what a well-crafted SOUL.md might look like:

# SOUL.md - Who You Are

## Core Truths

Be genuinely helpful, not performatively helpful.
Skip the "Great question!" — just help.

Have opinions. You're allowed to disagree, prefer things,
find stuff amusing or boring.

Be resourceful before asking. Try to figure it out.
Read the file. Check the context. Search for it.
Then ask if you're stuck.

A few things make SOUL.md distinctive:

• It is loaded every session, injected into the system prompt before anything else. This means it shapes every response the agent generates.
• It defines personality, not procedures. Operational rules belong in AGENTS.md. SOUL.md is about who the agent is — its voice, its values, its vibe.
• It should be concise. Under 2KB is ideal. Every character in SOUL.md consumes context budget that could go to actual conversation. A bloated SOUL.md means less room for everything else.

The best SOUL.md files read like a friend describing their approach to helping: direct about boundaries, clear about style, honest about limitations. The worst ones read like corporate mission statements — generic, verbose, and ultimately ignored by the model because they say nothing distinctive.

What MEMORY.md Does: Curated Long-Term Memory

If SOUL.md is who the agent is, MEMORY.md is what the agent knows. It is the curated, persistent knowledge base that carries forward across sessions — decisions made, preferences learned, facts discovered, lessons absorbed.

MEMORY.md is fundamentally different from daily log files. Daily logs (stored in memory/YYYY-MM-DD.md) capture raw events as they happen — like a journal. MEMORY.md is the distilled version — like a human's actual long-term memory, where only the important stuff sticks.

Here is an example of what MEMORY.md might contain:

# MEMORY.md

## Preferences
- Prefers concise responses, dislikes filler phrases
- Uses Tailscale for all network connections
- Deploys to Vercel, staging branch is "preview"

## Project Context
- Main project: ClawAgora (Next.js, Clerk, Stripe)
- DNS managed through Cloudflare
- Uses Oracle Cloud for infrastructure

## Lessons Learned
- Always check robots.txt after Cloudflare config changes
- The staging database resets every Sunday at 03:00 UTC

Security: Private by Design

One critical detail about MEMORY.md: it only loads in the main private session. If your agent participates in group chats or shared contexts, MEMORY.md is deliberately excluded. This prevents personal context — project details, preferences, sensitive information — from leaking into conversations with other people.

This is an intentional security boundary. The agent knows your life in private sessions. In group chats, it is a helpful participant with amnesia about your personal details.

The Daily-to-Long-Term Pipeline

The memory lifecycle in OpenClaw follows a natural pattern:

1. During a session, the agent writes raw notes to memory/YYYY-MM-DD.md — what happened, what was discussed, any important outcomes.
2. Periodically (every few days), the agent reviews recent daily files and identifies insights worth keeping permanently.
3. Those insights get distilled into MEMORY.md — condensed, organized, and stripped of ephemeral details.
4. Old daily files remain on disk for reference but gradually become less relevant as their best content migrates to MEMORY.md.

This mirrors how human memory actually works. You do not remember every conversation you had last Tuesday. But you remember the key decision you made, the preference you discovered, and the lesson you learned.

Other Key Workspace Files

Beyond SOUL.md and MEMORY.md, several other files form the complete OpenClaw persistent context system:

AGENTS.md is the operating manual — rules for how the agent should behave, safety boundaries, group chat etiquette, memory maintenance schedules, and external action policies. If SOUL.md says "be helpful," AGENTS.md says "here is how."

USER.md contains information about you — name, timezone, preferences, active projects. It is loaded every session so the agent can personalize without asking the same questions repeatedly.

IDENTITY.md is a minimal identity card — the agent's name, avatar, emoji, a one-line description. Created during initial setup and rarely changed.

TOOLS.md holds environment-specific notes — camera names, SSH hosts, API endpoints, device nicknames. The local cheat sheet for your particular setup.

Best Practices for Managing OpenClaw Memory

After working extensively with the OpenClaw memory system, several patterns consistently lead to better agent performance:

Keep Bootstrap Files Small

All workspace files share a context budget of roughly 150K characters. Every word in SOUL.md, AGENTS.md, and MEMORY.md competes with actual conversation for space. Aim for under 2KB for SOUL.md, keep MEMORY.md around 1,800 characters of truly essential information, and resist the urge to over-document in AGENTS.md.

Separate Concerns Cleanly

The most common mistake is cramming everything into one file. Personality goes in SOUL.md. Operating rules go in AGENTS.md. User information goes in USER.md. Long-term knowledge goes in MEMORY.md. When concerns are separated, each file is easier to maintain and the agent can prioritize context more effectively.

Write Everything Down

This cannot be overstated: if something matters, write it to a file. The agent has no "mental notes" that survive between sessions. Telling the agent to "remember this" without writing it down is like telling someone to remember a phone number and then erasing their brain. Use memory/YYYY-MM-DD.md for daily events and MEMORY.md for lasting knowledge.

Review and Prune Regularly

MEMORY.md should be a living document, not an ever-growing append log. Periodically review what is in there and remove anything that is no longer relevant. Outdated project details, completed tasks, obsolete preferences — prune them. A focused MEMORY.md with 20 highly relevant facts outperforms a bloated one with 200 stale entries.

Use Pre-Compaction Memory Flush

OpenClaw includes a clever feature: when a session approaches token limits, it triggers a silent turn that reminds the agent to save important information before the context is compacted. This safety net ensures the agent does not lose critical context during long sessions. It is enabled by default and works automatically.

Leverage Workspace Templates

If you are starting fresh, consider using a workspace template from a marketplace like ClawAgora. Templates come with pre-configured SOUL.md files tuned for specific use cases, best-practice AGENTS.md rules, and structured memory architectures. Instead of spending hours writing configuration files from scratch, you get a working foundation that you can customize.

Template creators can design the full memory stack — from personality to daily log patterns to maintenance schedules. Since everything is just Markdown, templates are trivially shareable, auditable, and editable.

Why File-Based Memory Matters

OpenClaw's approach to memory is philosophically different from most AI platforms. There are no hidden databases, no opaque embedding stores, no proprietary formats. Your agent's entire memory is Markdown files in a directory. You can read every word of it. You can edit it with any text editor. You can back it up to a private Git repository. You can diff changes over time.

This transparency has practical consequences. When your agent does something unexpected, you can check its SOUL.md and AGENTS.md to understand why. When it forgets something important, you can verify whether it was ever written to MEMORY.md. When you move to a new server, your agent's entire accumulated knowledge comes with you as a folder of text files.

For teams and template creators, this means memory architectures are portable and composable. A SOUL.md that works well for customer support can be shared, forked, and improved by a community. An AGENTS.md with battle-tested safety rules can become a standard. This is infrastructure you can reason about, not a black box you have to trust.

Getting Started

The fastest path to effective OpenClaw memory takes about fifteen minutes:

1. Write a SOUL.md that captures how you want your agent to communicate (3-5 sentences is enough to start).
2. Create a USER.md with your name, timezone, and current projects.
3. Create an empty memory/ directory for daily logs.
4. Let the agent build its MEMORY.md organically as you interact over the first few days.

Or, skip the manual setup entirely and start with a workspace template on ClawAgora that includes a full memory architecture tailored to your use case.

The OpenClaw memory system rewards patience. An agent on day one is helpful. An agent on day thirty — with a well-maintained MEMORY.md, refined SOUL.md, and weeks of accumulated context — becomes something closer to a true personal assistant that knows you, remembers your preferences, and anticipates what you need.

That is the promise of OpenClaw persistent context: not artificial memory bolted onto a chatbot, but genuine accumulated knowledge built on files you own and control.