How Does OpenClaw Memory Work?
OpenClaw agents wake up with amnesia
OpenClaw agents wake up with amnesia. Start a new session and yesterday's context is gone unless it was written to a file — because that's the entire memory system. OpenClaw's canonical, durable memory is plain Markdown on disk — no hidden cloud profile, though indexes and search stores exist on top for retrieval.
Understanding that one fact explains both why OpenClaw memory works the way it does and why it fails the way it does.
What is OpenClaw's memory system?
Three layers, all built on Markdown files.
Bootstrap files — a fixed set of eight filenames that load into context at every session start: SOUL.md, AGENTS.md, USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, BOOTSTRAP.md, and MEMORY.md. Anything not named one of these is never auto-injected. USER.md and IDENTITY.md are where user-specific context lives — your role, preferences, who you are.
Daily notes — memory/YYYY-MM-DD.md, an append-only log of what happened on a given day. These are the working layer: raw session context, observations, summaries.
Semantic search — a SQLite-backed vector index over your memory files, queried through the memory_search tool. It lets the agent retrieve older notes by meaning rather than exact match — when it chooses to search.
Where does OpenClaw store memory?
On disk, in the agent's workspace, as files you can open in any text editor. MEMORY.md holds curated long-term knowledge. The memory/ directory holds daily notes. A SQLite index (memory/.sqlite) powers semantic search.
There's no state hidden anywhere else. As the configuration guides put it bluntly: if it isn't written to a file, it doesn't exist. That transparency is a genuine strength — you can inspect, edit, and version-control everything. It's also the root of every memory problem OpenClaw has.
How does OpenClaw decide what to remember?
The agent decides. That's the critical design choice.
OpenClaw doesn't automatically persist what you tell it. When something matters, the model has to choose to call a tool and write it to a file. The official guidance is explicit: if you want something to stick, ask the agent to write it down.
This works when the agent judges correctly. It fails when it doesn't — and models are inconsistent at this. Mention an important constraint mid-conversation and the model may never write it down. It's not stored, so next session it's gone, as if you never said it.
Why does OpenClaw forget things?
Three structural reasons, all downstream of file-based memory:
The daily notes window. Only today's and yesterday's daily notes load automatically. Anything older sits on disk but stays out of context unless the agent actively searches for it. Debugging something from three days ago? It's not in context unless the agent retrieves it. This is the default — you can extend search roots and raise limits, but out of the box, the window is two days.
Truncation. Each bootstrap file caps at 20,000 characters; the combined budget across all of them is 150,000. A MEMORY.md that grows past its limit gets silently truncated — the agent sees the start and nothing after. The file on disk stays intact, but the copy injected into context is cut.
Compaction. When a session approaches the model's context limit, OpenClaw compresses older context to save tokens. Anything loaded into the conversation — including memory files — can be summarized, rewritten, or dropped in the process.
None of these are bugs. They're the operating reality of managing memory in text files.
How is this different from personal context?
OpenClaw memory answers what did we discuss before? — and answers it only if the agent wrote it down and can find it again.
Personal context answers a different question: who is this person and what are they working on? It's structured, extracted from your real sources, and loaded deterministically at the start of every session. It doesn't depend on the agent deciding to save it, and it doesn't get truncated out of a daily note you forgot to prune.
The two are complementary. Memory is the right tool for session-to-session continuity within OpenClaw. Personal context is the right tool for the foundational layer — your identity, role, and priorities — that should be present from the first message, every time, without the agent having to remember to remember it. In OpenClaw terms, that's what USER.md and IDENTITY.md are for — and keeping them accurate is exactly what a personal context layer automates.
→ The distinction in depth: AI Memory vs. AI Context: What's the Difference?
→ What personal context is: What Is Personal Context for AI?
Can you make OpenClaw memory more reliable?
Yes — through curation, semantic search, and external memory engines. That's a guide of its own.
→ How to Make OpenClaw Memory Better
