docs/concepts/memory.md
OpenClaw remembers things by writing plain Markdown files in your agent's workspace. The model only "remembers" what gets saved to disk — there is no hidden state.
Your agent has three memory-related files:
MEMORY.md — long-term memory. Durable facts, preferences, and
decisions. Loaded at the start of every DM session.memory/YYYY-MM-DD.md — daily notes. Running context and observations.
Today and yesterday's notes are loaded automatically.DREAMS.md (optional) — Dream Diary and dreaming sweep
summaries for human review, including grounded historical backfill entries.These files live in the agent workspace (default ~/.openclaw/workspace).
MEMORY.md is the compact, curated layer. Use it for durable facts,
preferences, standing decisions, and short summaries that should be available at
the start of a main private session. It is not meant to be a raw transcript,
daily log, or exhaustive archive.
memory/YYYY-MM-DD.md files are the working layer. Use them for detailed daily
notes, observations, session summaries, and raw context that may still be useful
later. These files are indexed for memory_search and memory_get, but they are
not injected into the normal bootstrap prompt on every turn.
Over time, the agent is expected to distill useful material from daily notes
into MEMORY.md and remove stale long-term entries. The generated workspace
instructions and heartbeat flow can do that periodically; you do not need to
manually edit MEMORY.md for every remembered detail.
If MEMORY.md grows past the bootstrap file budget, OpenClaw keeps the file on
disk intact but truncates the copy injected into the model context. Treat that as
a signal to move detailed material back into memory/*.md, keep only the
durable summary in MEMORY.md, or raise the bootstrap limits if you explicitly
want to spend more prompt budget. Use /context list, /context detail, or
openclaw doctor to see raw vs injected sizes and truncation status.
Some future follow-ups are not durable facts. If you mention an interview
tomorrow, the useful memory may be "check in after the interview," not "store
this forever in MEMORY.md."
Commitments are opt-in, short-lived follow-up memories for that case. OpenClaw infers them in a hidden background pass, scopes them to the same agent and channel, and delivers due check-ins through heartbeat. Explicit reminders still use scheduled tasks.
The agent has two tools for working with memory:
memory_search — finds relevant notes using semantic search, even when
the wording differs from the original.memory_get — reads a specific memory file or line range.Both tools are provided by the active memory plugin (default: memory-core).
If you want durable memory to behave more like a maintained knowledge base than
just raw notes, use the bundled memory-wiki plugin.
memory-wiki compiles durable knowledge into a wiki vault with:
wiki_search, wiki_get, wiki_apply, and wiki_lintIt does not replace the active memory plugin. The active memory plugin still
owns recall, promotion, and dreaming. memory-wiki adds a provenance-rich
knowledge layer beside it.
See Memory Wiki.
When an embedding provider is configured, memory_search uses hybrid
search — combining vector similarity (semantic meaning) with keyword matching
(exact terms like IDs and code symbols). This works out of the box once you have
an API key for any supported provider.
For details on how search works, tuning options, and provider setup, see Memory Search.
Before compaction summarizes your conversation, OpenClaw runs a silent turn that reminds the agent to save important context to memory files. This is on by default — you do not need to configure anything.
To keep that housekeeping turn on a local model, set an exact memory-flush model override:
{
"agents": {
"defaults": {
"compaction": {
"memoryFlush": {
"model": "ollama/qwen3:8b"
}
}
}
}
}
The override applies only to the memory-flush turn and does not inherit the active session fallback chain.
<Tip> The memory flush prevents context loss during compaction. If your agent has important facts in the conversation that are not yet written to a file, they will be saved automatically before the summary happens. </Tip>Dreaming is an optional background consolidation pass for memory. It collects
short-term signals, scores candidates, and promotes only qualified items into
long-term memory (MEMORY.md).
It is designed to keep long-term memory high signal:
memory-core auto-manages one recurring cron job
for a full dreaming sweep.DREAMS.md
for human review.For phase behavior, scoring signals, and Dream Diary details, see Dreaming.
The dreaming system now has two closely related review lanes:
memory/.dreams/ and is what the normal deep phase uses when deciding what
can graduate into MEMORY.md.memory/YYYY-MM-DD.md notes as
standalone day files and writes structured review output into DREAMS.md.Grounded backfill is useful when you want to replay older notes and inspect what
the system thinks is durable without manually editing MEMORY.md.
When you use:
openclaw memory rem-backfill --path ./memory --stage-short-term
the grounded durable candidates are not promoted directly. They are staged into the same short-term dreaming store the normal deep phase already uses. That means:
DREAMS.md stays the human review surface.MEMORY.md is still only written by deep promotion.If you decide the replay was not useful, you can remove the staged artifacts without touching ordinary diary entries or normal recall state:
openclaw memory rem-backfill --rollback
openclaw memory rem-backfill --rollback-short-term
openclaw memory status # Check index status and provider
openclaw memory search "query" # Search from the command line
openclaw memory index --force # Rebuild the index