Memory overview: How OpenClaw persists information across sessions

OpenClaw persists information by writing plain Markdown files inside your agent's workspace, which defaults to ~/.openclaw/workspace. The model retains only what is written to disk; no hidden state exists.

How it works

Three memory files are available to your agent:

MEMORY.md, handles long-term memory. Stores durable facts, preferences, and decisions. Loaded at session startup.
memory/YYYY-MM-DD.md (or memory/YYYY-MM-DD-<slug>.md), contains daily notes. Holds running context and observations. Today's and yesterday's dated notes are loaded 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), stores Dream Diary and dreaming sweep summaries intended for human review, including grounded historical backfill entries.

Tip

To make your agent remember something, simply tell it: "Remember that I prefer TypeScript." The note is written to the correct file.

What goes where

MEMORY.md serves as the compact, curated layer: it contains durable facts, preferences, standing decisions, and short summaries that need to be accessible at session start. This is not a raw transcript, daily log, or exhaustive archive.

memory/YYYY-MM-DD.md files form the working layer: they hold detailed daily notes, observations, session summaries, and raw context that may remain useful later. These files 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 perform this periodically; you do not need to manually edit MEMORY.md for every detail.

If MEMORY.md exceeds the bootstrap file budget, OpenClaw keeps the file on disk intact but truncates the copy injected into context. Consider this a signal to move detailed material into memory/*.md, keep only a durable summary in MEMORY.md, or increase the bootstrap limits if you want to allocate more prompt budget. Use /context list, /context detail, or openclaw doctor to view raw versus injected sizes and truncation status.

Import from coding assistants

The Control UI can import existing local memory from Codex and Claude Code. Navigate to Settings → Import Memory, select the destination agent, review the detected files, and confirm the import. OpenClaw copies only Markdown memory:

Codex: the consolidated MEMORY.md and memory_summary.md files located under ~/.codex/memories (or CODEX_HOME/memories). Raw rollout and transcript files are not imported.
Claude Code: Markdown files from each project auto-memory directory under ~/.claude/projects/*/memory, plus a user-configured autoMemoryDirectory when present. Project instructions, sessions, settings, and credentials are excluded from this memory-only action.

Imported files remain separate under memory/imports/codex/ and memory/imports/claude-code/ in the selected agent workspace. They are indexed for memory_search and accessible through memory_get; they are not merged into the agent's bootstrap MEMORY.md. The source files remain unchanged.

The preview highlights destination conflicts. Enable Replace existing imports to overwrite those files; applying creates a verified pre-import backup and preserves item-level copies of overwritten files in the migration report.

Action-sensitive memories

Most memories are standard 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:

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 clarifies:

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.

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 scheduled tasks for exact reminders, timed checks, and recurring work. Memory can still summarize the durable context around that work.

Retired 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."

The inferred commitments experiment is retired. OpenClaw no longer extracts or delivers those follow-ups. Use scheduled tasks for future actions; the legacy openclaw commitments command remains available to inspect or dismiss existing stored rows.

Memory tools

Two tools are available to the agent for working with memory:

memory_search, locates relevant notes through 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 search

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.

Info

OpenClaw uses OpenAI embeddings by default. Set memory.search.provider explicitly to use Gemini, Voyage, Mistral, Bedrock, DeepInfra, local GGUF, Ollama, LM Studio, GitHub Copilot, or a generic OpenAI-compatible endpoint.

See Memory search for how search works, tuning options, and provider setup.

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, LanceDB-backed memory with OpenAI-compatible embeddings, auto-recall, auto-capture, and local Ollama embedding support. Plugin install.

Knowledge wiki layer

To make durable memory act like a curated knowledge base rather than a collection of scattered notes, use the included memory-wiki plugin. This tool organizes durable knowledge into a wiki vault featuring a predictable page layout, structured claims and supporting evidence, detection of contradictions and freshness, auto-generated dashboards, compiled summaries, and wiki-native utilities (wiki_status, wiki_search, wiki_get, wiki_apply, wiki_lint).

memory-wiki does not replace the active memory plugin; that plugin continues to handle recall, promotion, and dreaming functions. Instead, memory-wiki introduces a knowledge layer rich in provenance alongside it.

Memory Wiki, Converts durable memory into a wiki vault with provenance tracking, claims, dashboards, bridge mode, and workflows compatible with Obsidian.

Automatic memory flush

Before compaction produces a summary of your conversation, OpenClaw runs a silent cycle that prompts the agent to write important context into memory files. This behavior is enabled by default; to disable it, set agents.defaults.compaction.memoryFlush.enabled: false.

To run that maintenance cycle on a local model, apply a precise override that affects only the memory flush turn (it does not inherit the fallback model chain from the active session):

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "model": "ollama/qwen3:8b"
        }
      }
    }
  }
}

Tip

The memory flush prevents information loss during compaction. If your agent holds important facts in the conversation that have not yet been saved to a file, those facts are automatically written before the summary is generated.

Dreaming

Dreaming provides an optional background consolidation pass for memory. It gathers short-term recall signals, evaluates candidates, and promotes only those that meet the criteria into long-term memory (MEMORY.md):

Opt-in: turned off by default.
Scheduled: when activated, memory-core automatically manages a single recurring cron job for a full dreaming sweep.
Thresholded: promotions must satisfy gates for score, recall frequency, and query diversity.
Reviewable: phase summaries and diary entries are written to DREAMS.md for human inspection.

For details on phase behavior, scoring signals, and the Dream Diary, refer to Dreaming.

Grounded backfill and live promotion

The dreaming system provides two related review channels:

Live dreaming operates from the short-term dreaming store located at memory/.dreams/ and is the mechanism the normal deep phase uses to determine what graduates into MEMORY.md.
Grounded backfill reads historical memory/YYYY-MM-DD.md notes as individual day files and writes structured review output into DREAMS.md.

Grounded backfill is useful for replaying older notes and examining what the system considers durable, without requiring manual edits to MEMORY.md.

openclaw memory rem-backfill --path ./memory --stage-short-term

The --stage-short-term flag places grounded durable candidates into the same short-term dreaming store that the normal deep phase already uses; it does not directly promote them. Therefore:

DREAMS.md remains the surface for human review.
The short-term store stays the machine-facing ranking surface.
MEMORY.md is still written exclusively through deep promotion.

To undo a replay without affecting 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