How OpenClaw memory works

OpenClaw remembers by writing Markdown files into the agent’s workspace, and nothing else: the model only knows what was saved to disk, and there is no hidden state. That one design decision explains most of what people find surprising about its memory, good and bad, and it is the place to start if yours forgets things or repeats itself.

The four files

• USER.md, optional: stable preferences, communication style and active-project context, written as directives and loaded at the start of a session with its own small budget.
• MEMORY.md: long-term memory. Durable facts and decisions, curated rather than transcribed, loaded at the start of every session.
• memory/YYYY-MM-DD.md: daily notes and running context. Today’s and yesterday’s load automatically on a fresh session; older ones are indexed for search rather than injected.
• DREAMS.md, optional: the diary of the background consolidation sweeps, kept for a human to review.

If you want it to remember something, you ask: say that you prefer TypeScript, and it writes the note to the right file. Over time, useful material from the daily notes is distilled into MEMORY.md by a background process the docs call dreaming, which scores candidates and promotes only those that pass recall-frequency and diversity gates. Untrusted input never enters that promotion path.

Why it forgets, and why it repeats

MEMORY.md has a budget. When it grows past the bootstrap limit, the file on disk stays intact but the copy injected into context is truncated, silently from the model’s point of view. The docs treat that as the signal to move detail into the daily notes and keep only a durable summary at the top, or to raise the limits and pay the prompt cost. Before compaction summarises a long conversation, a silent turn reminds the agent to save what matters, so facts that lived only in the chat survive the summary.

The model only remembers what gets saved to disk; there is no hidden state.

Search, and the engines behind it

Three tools work the files: one finds notes by meaning even when the wording differs, one reads a file or a range of lines, and one records standing intentions that trigger on events. Search is hybrid when an embedding provider is configured, vector similarity plus keyword matching, with OpenAI embeddings by default and a long list of alternatives including local models. The default engine is a built-in SQLite index; Honcho, LanceDB and a wiki-style knowledge layer are plugins.

OpenClaw memory and Hermes memory

Hermes is built around memory in a way OpenClaw is not: it curates its own notes, nudges itself to persist what it learns and searches past sessions as a first-class feature. OpenClaw’s memory is honest and inspectable, and it depends on files you can read, edit and back up. Hermes vs OpenClaw weighs the two.

On a managed host

The files live in the assistant’s own sandbox, which is why backups matter: on Diali the Backups add-on snapshots the workspace daily with one-click restore, and it is included on the Max plan. Everything above is the same OpenClaw; the difference is that the machine holding the files is not yours to lose. Hosted OpenClaw on Diali has the rest.

• Memory is Markdown in the workspace: read it, edit it, back it up.
• MEMORY.md is curated and budgeted; the daily notes are the archive.
• Dreaming consolidates in the background, and compaction flushes to disk first.

If the process that owns those files is the part you never understood, The OpenClaw Gateway, explained is the explanation.