Case Study: OpenClaw's Memory

Concept. An AI agent like OpenClaw consists of a loop and a memory. The loop reads context, calls the model, runs tools, and writes new state. The memory persists state across loop iterations. OpenClaw stores memory as a folder of Markdown files (MEMORY.md for curated facts, dated files for a daily log) plus a small SQLite file for search.

Intuition. MEMORY.md loads at the start of every session; the day's note is appended as the agent works. When the notes pile up, a background "dreaming" pass folds the keepers into MEMORY.md and drops the rest. To recall something, the agent searches the SQLite index of chunked text and embeddings. The files are the truth; the index is derived and rebuildable. Append fast, compact later, search an index: you have seen every move already.

An agent is a loop and a memory

OpenClaw is an open-source agent: hand it a goal and it acts on your behalf, wiring a model to your files, tools, and messages. Strip away the branding and an agent is two parts. A loop runs the same four steps until the work is finished: read the context, call the model, run tools, write to memory. A memory holds what has to outlive one turn, and it is just a folder of plain files on disk. MEMORY.md keeps curated facts and preferences and loads at session start. Dated files under memory/ are the daily log, appended as the agent goes. Next to the files sits agent.sqlite, a search index the agent builds from them.

On the left, the agent loop reads context, calls the model and tools, and writes to memory. In the center, the memory is a folder: MEMORY.md holds curated facts, dated daily-note files hold the appended log, and a dreaming arrow folds notes up into MEMORY.md as compaction. On the right, agent.sqlite is a derived search index rebuilt from the files.

Figure 1. OpenClaw stores memory in a folder on disk plus a derived SQLite index. The loop reads, acts, and writes each turn; each claw uses its own folder. The files are the canonical state: MEMORY.md holds curated facts loaded at session start, and daily notes store an append-only log. The dreaming pass merges retained notes into MEMORY.md and deletes the rest. agent.sqlite indexes chunked text and embeddings and can be rebuilt from the files.

That is the whole system: a loop, a folder of files, and an index over them. Every part of it maps onto an idea you already learned.

Where you have seen this before

Read the figure again with the course in mind, and the agent stops looking new.

  • The SQLite file is an index, not a second memory. The Markdown files are the source of truth; agent.sqlite is built from them and can be thrown away and rebuilt. That is an index over base data, and the embeddings half of it is a vector index, so search finds a memory by meaning as well as by keyword. → Module 3, indexing.

  • "Dreaming" is compaction. Notes append fast to the daily log; a background pass merges the keepers into MEMORY.md and discards the rest. Append fast, consolidate later, is the same move an LSM tree makes when it compacts, the structure Spotify uses to absorb a million writes a second. → Module 3, LSM.

  • The context window is RAM; the files are disk. When the session ends, the context is gone. Only what the loop wrote to the folder survives. State that has to outlive the end of a session is durability, the same reason a database writes to disk before it calls a transaction done. → Module 4B, durability.

Three parts of the agent, three ideas from earlier in the course. The fourth shows up only when you run more than one agent.

Share the memory, and Module 4 is back

By default, OpenClaw sidesteps concurrency: run several claws and each keeps its own folder. Nothing is shared, so nothing can conflict. The newer pattern is to let claws share one memory, and the moment they do, the anomalies from Module 4 come straight back.

Two claws both write to one shared MEMORY.md; both edits hit the same file and claw B saves last, so claw A's earlier edit is struck through and labeled a lost update; the fix on the right is a file lock so one writer touches the file at a time, or append-only files and conditional writes.

Figure 2. Two claws write one shared MEMORY.md. Both read and both save; claw B saves last and overwrites claw A's edit. The overwrite creates a lost update. A fix applies Module 4 techniques to files: take a file lock so one writer updates at a time, or use append-only, idempotent writes so replay stays safe. Module 4, concurrency control.

The frontier agents are re-deriving locking and conflict resolution in real time, working out the same trade you studied in Module 4: isolate for safety, or share for coordination and pay for it with locks.

Files for a few agents, a database for many

The real question is how many agents share the memory. For one agent, or a few that each keep their own folder, files are hard to beat: plain text, git-diffable, zero-ops, and with isolation there is nothing to conflict. That is the world OpenClaw was built for.

A split by number of agents: a few agents (each with its own folder, plain text, git-diffable, nothing to conflict, so files win) on the left; many agents (one shared store, transactions serialize the writes, Postgres with pgvector or Tencent's agent memory, so a database wins) on the right; a right-pointing arrow shows multi-agent systems and autonomous research pushing from few agents toward many.

Figure 3. The agent count drives the memory design. A few agents can use separate folders: plain text, git-diffable, no conflicts. Many agents require one shared store with concurrent writes. A database (Postgres with pgvector, or Tencent's agent memory) serializes writes with Module 4 transactions, and a pipeline maintains a readable copy. Multi-agent systems and autonomous research push deployments toward the many-agent end.

But the field is moving toward many agents at once. Multi-agent systems, like autonomous research fleets, put dozens of agents against one shared store, and every write becomes a concurrent write. Locking a Markdown file by hand stops scaling, and this is what a database is for: let it hold the source of truth, and its transactions serialize the writers for you, the concurrency control from Module 4 running underneath. Keep the memory in Postgres with the pgvector extension and one store holds the facts and the embeddings; Tencent's agent memory splits it, a database for facts, logs, and traces with a readable Markdown layer on top.

You still owe a pipeline to keep the readable copy and the database in sync, the same OLTP-to-OLAP plumbing as big-tech design. But past a handful of agents, that is the price of memory that many writers can share without stepping on each other.

Takeaway

The most talked-about system in computing right now keeps its memory in a folder of Markdown files with a SQLite index, small enough to sit on a laptop. It appends fast and compacts later like an LSM tree, searches a derived index instead of scanning, writes to disk so its state survives, and takes a lock when two of them share. An agent is a loop over a memory, and the memory is this course.