Memory overview

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.

How it works

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 (or memory/YYYY-MM-DD-<slug>.md) — daily notes. Running context and observations. Today and yesterday’s notes are loaded automatically, and slugged variants such as those written by the bundled session-memory hook on /new or /reset are now picked up alongside the date-only file.
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).

What goes where

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.

Action-sensitive memories

Most memories can be written as ordinary Markdown notes. But some memories 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:

approval or permission requirements,
temporary constraints,
handoffs to another session, thread, or person,
expiry conditions,
safe-to-act timing,
source or owner authority,
instructions to avoid a tempting action.

A useful action-sensitive memory makes clear:

what changes future behavior,
when or under what condition it applies,
when it expires, or what unlocks action,
what the agent should avoid doing,
who is the source or owner, if that affects trust or authority.

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.

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.

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.

Inferred commitments

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.

Memory tools

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).

Memory Wiki companion plugin

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:

deterministic page structure
structured claims and evidence
contradiction and freshness tracking
generated dashboards
compiled digests for agent/runtime consumers
wiki-native tools like wiki_search, wiki_get, wiki_apply, and wiki_lint

It 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.

Memory search

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.

Memory backends

Builtin (default)

SQLite-based. Works out of the box with keyword search, vector similarity, and hybrid search. No extra dependencies.

QMD

Local-first sidecar with reranking, query expansion, and the ability to index directories outside the workspace.

Honcho

AI-native cross-session memory with user modeling, semantic search, and multi-agent awareness. Plugin install.

LanceDB

Bundled LanceDB-backed memory with OpenAI-compatible embeddings, auto-recall, auto-capture, and local Ollama embedding support.

Knowledge wiki layer

Memory Wiki

Compiles durable memory into a provenance-rich wiki vault with claims, dashboards, bridge mode, and Obsidian-friendly workflows.

Automatic memory flush

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.

Dreaming

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:

Opt-in: disabled by default.
Scheduled: when enabled, memory-core auto-manages one recurring cron job for a full dreaming sweep.
Thresholded: promotions must pass score, recall frequency, and query diversity gates.
Reviewable: phase summaries and diary entries are written to DREAMS.md for human review.

For phase behavior, scoring signals, and Dream Diary details, see Dreaming.

Grounded backfill and live promotion

The dreaming system now has two closely related review lanes:

Live dreaming works from the short-term dreaming store under memory/.dreams/ and is what the normal deep phase uses when deciding what can graduate into MEMORY.md.
Grounded backfill reads historical 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.
the short-term store stays the machine-facing ranking 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

CLI

openclaw memory status          # Check index status and provider
openclaw memory search "query"  # Search from the command line
openclaw memory index --force   # Rebuild the index