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:

• text

  Copy

  MEMORY.md
  — long-term memory. Durable facts, preferences, and decisions. Loaded at the start of every DM session.
• text

  Copy

  memory/YYYY-MM-DD.md
  — daily notes. Running context and observations. Today and yesterday's notes are loaded automatically.
• text

  Copy

  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

).

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

."

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:

• text

  Copy

  memory_search
  — finds relevant notes using semantic search, even when the wording differs from the original.
• text

  Copy

  memory_get
  — reads a specific memory file or line range.

Both tools are provided by the active memory plugin (default:

).

Memory Wiki companion plugin

If you want durable memory to behave more like a maintained knowledge base than just raw notes, use the bundled

plugin.

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
  text

  Copy

  wiki_search
  ,
  text

  Copy

  wiki_get
  ,
  text

  Copy

  wiki_apply
  , and
  text

  Copy

  wiki_lint

It does not replace the active memory plugin. The active memory plugin still owns recall, promotion, and dreaming.

adds a provenance-rich knowledge layer beside it.

See Memory Wiki.

Memory search

When an embedding provider is configured,

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

Knowledge wiki layer

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:

json
Copy
{
  "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 (

).

It is designed to keep long-term memory high signal:

• Opt-in: disabled by default.
• Scheduled: when enabled,
  text

  Copy

  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
  text

  Copy

  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
  text

  Copy

  memory/.dreams/
  and is what the normal deep phase uses when deciding what can graduate into
  text

  Copy

  MEMORY.md
  .
• Grounded backfill reads historical
  text

  Copy

  memory/YYYY-MM-DD.md
  notes as standalone day files and writes structured review output into
  text

  Copy

  DREAMS.md
  .

Grounded backfill is useful when you want to replay older notes and inspect what the system thinks is durable without manually editing

.

When you use:

bash
Copy
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:

• text

  Copy

  DREAMS.md
  stays the human review surface.
• the short-term store stays the machine-facing ranking surface.
• text

  Copy

  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:

bash
Copy
openclaw memory rem-backfill --rollback
openclaw memory rem-backfill --rollback-short-term

CLI

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

Further reading

• Builtin memory engine: default SQLite backend.
• QMD memory engine: advanced local-first sidecar.
• Honcho memory: AI-native cross-session memory.
• Memory LanceDB: LanceDB-backed plugin with OpenAI-compatible embeddings.
• Memory Wiki: compiled knowledge vault and wiki-native tools.
• Memory search: search pipeline, providers, and tuning.
• Dreaming: background promotion from short-term recall to long-term memory.
• Memory configuration reference: all config knobs.
• Compaction: how compaction interacts with memory.

Related

• Active memory
• Memory search
• Builtin memory engine
• Honcho memory
• Memory LanceDB
• Commitments