Case Study: OpenClaw's Memory
Concept. An AI agent like OpenClaw runs a loop over persistent memory. Each turn reads context, calls the model, runs tools, and writes new state. OpenClaw keeps curated memory in Markdown files and builds keyword and vector search indexes in its per-agent SQLite database.
Intuition. MEMORY.md holds durable facts, while dated files record recent work. A background "dreaming" pass promotes useful details into MEMORY.md. Search uses derived index tables inside openclaw-agent.sqlite. OpenClaw can rebuild those tables from the Markdown files, but the same database also stores sessions, transcripts, and other durable state.
An agent is a loop and a memory
OpenClaw connects a model to files, tools, and messages. Its loop reads context, calls the model, runs tools, and records new state. Markdown files hold the agent's durable memory: MEMORY.md stores curated facts, while dated files under memory/ record recent work. OpenClaw indexes those files in openclaw-agent.sqlite for keyword and vector search.
Figure: An agent is a loop and a memoryOpenClaw's architecture as a loop over persistent memory. On the left, the agent loop reads context, calls the model and tools, and writes new state. In the center, MEMORY.md holds curated facts and dated files record recent work. A dreaming pass promotes useful details into MEMORY.md. On the right, rebuildable memory index tables inside openclaw-agent.sqlite support keyword and vector search. The database also holds sessions, transcripts, and other durable agent state.
Figure 1. OpenClaw stores durable memory in Markdown files. MEMORY.md holds curated facts, and dated files record recent work. The dreaming pass promotes useful details into MEMORY.md. Derived tables in openclaw-agent.sqlite index the files for keyword and vector search. The database also contains sessions, transcripts, and other agent state.
Where you have seen this before
Read the figure again with the course in mind, and the agent stops looking new.
-
The memory index is derived. OpenClaw builds keyword and vector indexes from the Markdown files. It can rebuild those index tables when the files change. Do not delete
openclaw-agent.sqlite: the database also holds sessions, transcripts, and other durable state. The memory tables demonstrate an index over base data. → Module 3, indexing. -
"Dreaming" resembles compaction. OpenClaw records detailed daily notes, then promotes durable information into
MEMORY.md. This append-first, consolidate-later pattern resembles LSM compaction. → 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.
Share the memory, and Module 4 is back
Separate agent workspaces avoid write conflicts. When two agents share one memory file, the anomalies from Module 4 return.
Figure: Share one memory across claws, and Module 4 is backTwo agents writing one shared file, and the fix. On the left, claw A and claw B both write to one shared MEMORY.md. In the center, 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 classic Module 4 anomaly. On the right, the fix is a file lock so only one writer touches the file at a time, or append-only files and conditional writes. Color key: red is the conflict, a lost update; slate is the claws and the shared file.
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.
Shared state requires concurrency control. A lock can serialize file updates, while append-only and conditional writes can prevent destructive overwrites.
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.
Figure: For a few agents, files. For many, a database.How many agents share the memory influences the design. At the left, a few agents use separate folders with no write conflicts. At the right, many agents write one shared store, and a database uses transactions to serialize updates. Postgres with pgvector can store facts and index embeddings. Color key: slate is the two regimes; grey is the move from separate memory toward shared memory.
Figure 3. Separate agent workspaces can use plain files without write conflicts. Agents that share write-heavy memory need concurrency control. A database such as Postgres with pgvector can serialize updates and index embeddings.
Files work well when agents use separate workspaces. Shared, write-heavy memory needs stronger concurrency control. A database can serialize updates with transactions and index embeddings with an extension such as pgvector. If the system also maintains a readable Markdown copy, a pipeline must keep the two representations in sync.
Takeaway
OpenClaw connects familiar systems ideas. Files provide durable memory. Derived indexes support recall. Dreaming consolidates accumulated notes. Shared writes require concurrency control. An agent may feel new, but its memory still depends on storage, indexing, and transactions.