You set up OpenClaw. You had an incredible first conversation —
configured your preferences, explained your projects, taught it your
workflows. It felt like magic. Then you came back the next day, and it
had no idea who you were.
Sound familiar? This is the single most common frustration for new
OpenClaw users, and it hits hard because the first session feels so
promising. You’re not imagining things. Your bot really did
forget everything. And no, it’s not broken.
It just needs a memory system.
Whether you’re running ClawdBot, MoltBot, or a custom OpenClaw agent,
the fix is the same. This guide walks you through the complete OpenClaw
memory architecture — what each file does, how to set it up, and the
advanced tricks that make your bot feel like it actually knows you.
Why OpenClaw Forgets
Everything
OpenClaw agents are stateless between sessions.
Every time you start a new conversation, the model wakes up with a blank
slate. There’s no magic database running in the background quietly
storing your preferences. There’s no implicit memory layer carrying
context forward.
Three things work against you:
- Session isolation. Each conversation starts fresh.
The model has no access to previous sessions unless you explicitly
provide it. - Context window limits. Even within a single
session, there’s a ceiling on how much text the model can hold. Long
conversations get compacted — older messages are summarized or
dropped to make room for new ones. - No built-in long-term memory by default. OpenClaw
ships with the memory infrastructure, but it doesn’t populate itself.
You have to tell it what to remember and where to put it.
This is actually a deliberate design choice. OpenClaw uses a
file-first philosophy: plain Markdown files in your
workspace are the source of truth. The agent only “remembers” what gets
written to disk. Nothing more, nothing less.
That means your memory system is completely transparent, fully
editable, and under your control. No black-box embeddings. No opaque
database you can’t inspect. Just files you can read, edit, and version
control.
The trade-off? You need to set it up.
The Complete OpenClaw
Memory Architecture
OpenClaw’s memory lives in your agent workspace (typically
~/.openclaw/workspace). Here’s every file that matters and
what it does.
MEMORY.md — Long-Term
Curated Memory
This is the big one. Think of MEMORY.md as your bot’s
long-term memory — the distilled, curated knowledge about you, your
projects, your preferences, and important decisions.
# MEMORY.md
## About Wayne
- Software engineer, based in London
- Runs AdTechLab (ad-tech consultancy)
- Prefers direct communication, hates fluff
- Morning person — most productive before noon
## Active Projects
- OpenClaw Pulse blog (openclawpulse.com)
- SA property management (26 Horizon Mews)
- Personal budget tracking via Google Sheets
## Preferences
- Use trash instead of rm
- Always push to git after significant changes
- Don't send emails without asking firstKey rules: – Only loaded in your private,
main session — never in group chats or shared contexts. This is
a security measure so personal details don’t leak to strangers. – You
curate this yourself over time. Think journal review, not auto-logging.
– Update it when things change. Outdated memory is worse than no
memory.
memory/YYYY-MM-DD.md — Daily
Notes
These are the raw daily logs. Each day gets its own file in the
memory/ directory. They capture what happened: decisions
made, tasks completed, conversations had, things to follow up on.
# 2026-02-11
## Morning
- Reviewed email — nothing urgent
- Started blog post on OpenClaw memory system
- Wayne confirmed: publish to openclawpulse.com
## Afternoon
- Finished draft, sent for review
- Updated personal budget spreadsheet
- Note: Wayne wants to set up automated memory review via heartbeatsHow they work: – OpenClaw reads today’s and
yesterday’s daily files at session start, giving the agent two
days of rolling context automatically. – They’re append-only in practice
— just keep adding to today’s file as things happen. – Create the
memory/ directory if it doesn’t exist. OpenClaw won’t
create it for you, and this is the number one reason daily notes don’t
work for new users.
CONTEXT.md — Active
Discussion Threads
This is your lifeline during context compaction. When OpenClaw
summarizes older messages to save tokens, CONTEXT.md
survives because it’s a file, not part of the conversation history.
# CONTEXT.md — Active Threads
## Blog Post: OpenClaw Memory Guide
- Status: drafting
- Target: 2,000 words, publish this week
- Keyword: "openclaw forgetting"
## SA Property
- Waiting on municipality invoice (expected Feb 15)
- Body corporate levy increase under review
## Recently Resolved
- ✅ Set up Google Drive shared folder (2026-02-09)Update this during conversations, not just at the
end of the day. When you start a multi-step task, add it immediately.
When a thread resolves, move it to “Recently Resolved.” This file is
what keeps your bot oriented when everything else gets compacted.
LESSONS.md — Principles and
Patterns
This is where your bot stores hard-won lessons — things that went
wrong, patterns that work, principles to follow. It’s the difference
between a bot that makes the same mistake twice and one that learns.
# LESSONS.md
## Process
- Always confirm before sending external communications
- When editing spreadsheets, use the drive_upload helper — rclone creates duplicates
- Batch heartbeat checks instead of creating multiple cron jobs
## Technical
- Telegram doesn't support markdown tables — use bullet lists
- Wrap Discord links in <> to suppress embeds
- WhatsApp: no headers, use **bold** for emphasisUSER.md — Info About You
A dedicated file for everything about the human. Name, role,
communication preferences, timezone, quirks. This keeps personal context
separate from project memory.
# USER.md
## Basics
- Name: Wayne
- Timezone: Europe/London
- Telegram ID: 6034907749
## Communication Style
- Direct and concise — skip the preamble
- Prefers solutions over explanations of problems
- Hates when I say "Great question!"AGENTS.md — Operating
Instructions
This is the bot’s playbook. It defines how the agent should
behave: what to read at startup, how to handle group chats, when to be
proactive, safety rules. Think of it as the constitution your bot
follows every session.
You typically set this up once and refine it over time. The default
AGENTS.md that ships with OpenClaw is already solid — it
instructs the agent to read SOUL.md, USER.md,
daily memory files, and MEMORY.md at the start of every
session.
Setting It Up: The
Five-Minute Version
Here’s the minimum viable memory system. Do this and your OpenClaw
bot will already feel dramatically more persistent:
Step 1: Create the memory directory.
mkdir -p ~/.openclaw/workspace/memoryStep 2: Create MEMORY.md with basic
info about yourself.
cat > ~/.openclaw/workspace/MEMORY.md << 'EOF'
# Long-Term Memory
## About the Human
- [Your name, role, key details]
- [Communication preferences]
- [Active projects]
EOFStep 3: Create CONTEXT.md for active
threads.
touch ~/.openclaw/workspace/CONTEXT.mdStep 4: Tell your bot to use them. In your next
conversation, say something like:
“From now on, write important things to MEMORY.md and daily notes to
memory/YYYY-MM-DD.md. Update CONTEXT.md when we start or finish
tasks.”
That’s it. Your bot now has a functioning memory system.
The “Tell It to Remember”
Trick
This is deceptively simple and wildly effective. If you want your
OpenClaw bot to remember something, literally tell it to
remember.
“Remember that I prefer dark mode on all my apps.”
“Remember: the SA property municipality account number is
12345678.”
“Add to memory: we decided to use Next.js for the blog redesign.”
When you say “remember this,” a well-configured OpenClaw agent writes
it to the appropriate memory file — either MEMORY.md for
durable facts or memory/YYYY-MM-DD.md for session context.
The default AGENTS.md explicitly instructs the bot to do
this. No plugins required. No configuration. Just ask.
This works for ClawdBot, MoltBot, and any OpenClaw-based agent
running the standard workspace setup.
Advanced: Memory
Maintenance and Automation
Once the basics are running, these techniques take your OpenClaw
memory system from functional to excellent.
Automatic Memory Flush
(Pre-Compaction)
OpenClaw has a built-in safety net. When a session approaches the
context window limit, it triggers a silent memory flush
— an internal prompt that tells the model to write any important unsaved
context to disk before compaction wipes it out.
This is enabled by default. You can tune it in your config:
{
"agents": {
"defaults": {
"compaction": {
"memoryFlush": {
"enabled": true,
"softThresholdTokens": 4000
}
}
}
}
}The flush fires when the session approaches compaction, giving the
model one last chance to persist anything important. It’s silent —
you’ll never see it happen.
Memory Review During
Heartbeats
If you run heartbeats (periodic check-ins), dedicate one every few
days to memory maintenance:
- Read through recent daily files.
- Identify significant events or lessons worth keeping long-term.
- Distill them into
MEMORY.md. - Remove outdated entries that are no longer relevant.
This is the equivalent of a human reviewing their journal and
updating their mental model. Daily files are raw notes;
MEMORY.md is curated wisdom.
Vector Memory Search
OpenClaw can build a vector index over your memory files, enabling
semantic search. Ask your bot something like “what did we decide about
the deployment strategy last week?” and it can find the relevant note
even if the wording doesn’t match exactly.
This uses a hybrid search approach — combining BM25 keyword matching
with vector similarity — and supports multiple embedding providers
(OpenAI, Gemini, Voyage, or local models). It’s enabled by default when
an embedding API key is available.
Common Mistakes (and How
to Avoid Them)
Not creating the memory/ directory.
OpenClaw won’t create it for you. If the directory doesn’t exist, daily
notes have nowhere to go. Run
mkdir -p ~/.openclaw/workspace/memory and move on.
Not loading MEMORY.md in sessions. If your
AGENTS.md doesn’t instruct the bot to read
MEMORY.md at startup, it won’t. The default
AGENTS.md handles this, but if you’ve customized yours,
make sure the instruction is there.
Putting secrets in memory files. API keys,
passwords, tokens — keep them out of MEMORY.md and daily
files. These files get loaded into the context window and potentially
passed to embedding APIs. Use your credentials directory or environment
variables instead.
Never curating MEMORY.md. If you only append and
never review, MEMORY.md grows into an unwieldy mess that
burns tokens without adding value. Periodically trim it. Remove things
that are no longer true. Consolidate duplicate entries. Treat it like a
living document, not an append-only log.
Forgetting that group chats don’t load MEMORY.md.
This is by design — you don’t want your personal context shared with
everyone in a group. If your bot seems forgetful in group settings,
that’s the security boundary working as intended.
Your Bot Isn’t Broken
OpenClaw’s memory system is deliberately file-based and
human-readable. That means it requires a small amount of setup, but it
gives you something no black-box solution can: complete
transparency and control over what your agent knows.
Set up MEMORY.md. Create the memory/
directory. Tell your bot to remember things. Review and curate
periodically. That’s the entire system.
Your bot was never broken. It just needed you to give it a
memory.
Building with OpenClaw? We cover agent architecture, memory
patterns, and practical guides every week. Follow OpenClaw Pulse for signal, not
noise.