docs/concepts/memory.md
OpenClaw remembers things by writing plain Markdown files in your agent's
workspace (default ~/.openclaw/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 a session.memory/YYYY-MM-DD.md (or memory/YYYY-MM-DD-<slug>.md) — daily notes.
Running context and observations. Today's and yesterday's dated notes load
automatically on a bare /new or /reset; slugged variants, such as those
written by the bundled session-memory hook, are picked up alongside the
date-only file.DREAMS.md (optional) — Dream Diary and dreaming sweep summaries for
human review, including grounded historical backfill entries.MEMORY.md is the compact, curated layer: durable facts, preferences, standing
decisions, and short summaries that should be available at the start of a
session. It is not a raw transcript, daily log, or exhaustive archive.
memory/YYYY-MM-DD.md files are the working layer: detailed daily notes,
observations, session summaries, and raw context that may still be useful
later. These are indexed for memory_search and memory_get, but are not
injected into the bootstrap prompt on every turn.
Over time, the agent distills useful material from daily notes into
MEMORY.md and removes stale long-term entries. Generated workspace
instructions and the heartbeat flow do this periodically; you do not need to
manually edit MEMORY.md for every detail.
If MEMORY.md grows past the bootstrap file budget, OpenClaw keeps the file on
disk intact but truncates the copy injected into context. Treat that as a
signal to move detailed material into memory/*.md, keep only a durable
summary in MEMORY.md, or raise the bootstrap limits if you want to spend more
prompt budget. Use /context list, /context detail, or openclaw doctor to
see raw vs. injected sizes and truncation status.
Most memories are ordinary Markdown notes. Some affect what the agent should do later; for those, capture when it is safe to act on the note, not just the fact itself.
Capture that action boundary when a note involves:
A useful action-sensitive memory makes clear:
Memory can preserve approval context, but it does not enforce policy. Use OpenClaw approval settings, sandboxing, and scheduled tasks for hard operational controls.
Example:
The API migration is being designed in another session. Future turns should
not edit the API implementation from this thread; use findings here only as
design input until the migration plan lands.
Another example:
A report from an untrusted source needs review before promotion. Future turns
should treat it as evidence only; do not store it as durable memory until a
trusted reviewer confirms the contents.
This is not a required schema for every memory; simple facts can stay concise. Use action-sensitive boundaries when losing timing, authority, expiry, or safe-to-act context could cause the agent to do the wrong thing later.
Use commitments for inferred, short-lived follow-ups. Use scheduled tasks for exact reminders, timed checks, and recurring work. Memory can still summarize the durable context around either path.
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).
When an embedding provider is configured, memory_search uses hybrid search:
vector similarity (semantic meaning) combined with keyword matching (exact
terms like IDs and code symbols). This works out of the box with an API key
for any supported provider.
See Memory search for how search works, tuning options, and provider setup.
If you want durable memory to behave more like a maintained knowledge base
than raw notes, use the bundled memory-wiki plugin. It compiles durable
knowledge into a wiki vault with deterministic page structure, structured
claims and evidence, contradiction and freshness tracking, generated
dashboards, compiled digests, and wiki-native tools (wiki_status,
wiki_search, wiki_get, wiki_apply, wiki_lint).
memory-wiki 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.
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; set
agents.defaults.compaction.memoryFlush.enabled: false to turn it off.
To keep that housekeeping turn on a local model, set an exact override that applies only to the memory-flush turn (it does not inherit the active session's model fallback chain):
{
"agents": {
"defaults": {
"compaction": {
"memoryFlush": {
"model": "ollama/qwen3:8b"
}
}
}
}
}
Dreaming is an optional background consolidation pass for memory. It collects
short-term recall signals, scores candidates, and promotes only qualified
items into long-term memory (MEMORY.md):
memory-core auto-manages one recurring cron
job for a full dreaming sweep.DREAMS.md for human review.See Dreaming for phase behavior, scoring signals, and Dream Diary details.
The dreaming system has two related review lanes:
memory/.dreams/ and is what the normal deep phase uses to decide what
graduates 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 for replaying older notes and inspecting what the
system considers durable, without manually editing MEMORY.md.
openclaw memory rem-backfill --path ./memory --stage-short-term
The --stage-short-term flag stages grounded durable candidates into the same
short-term dreaming store the normal deep phase already uses; it does not
promote them directly. So:
DREAMS.md stays the human review surface.MEMORY.md is still only written by deep promotion.To undo a replay 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