Memory Overview: How OpenClaw Persists Information

OpenClaw persists information by writing plain Markdown files into your agent's workspace, which defaults to ~/.openclaw/workspace. Anything the model retains must be stored on disk; no hidden state exists.

How it works

Four memory-related files belong to your agent:

USER.md (optional), stable preferences, communication style, relationships, and active-project context written as directives. Loaded at the start of a session with a separate small budget.
MEMORY.md, long-term memory. Durable non-profile facts 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.

Tip

To have your agent retain something, simply request: "Remember that I prefer TypeScript." It then writes the note to the appropriate file.

What goes where

The compact user-model layer is USER.md. Record stable preferences and profile facts as imperative directives carrying observed-date and active/superseded metadata. When a preference shifts, mark the old one superseded in place rather than adding a conflicting active directive. Refer to User model.

For durable non-profile facts, standing decisions, and brief summaries that need to be present when a session starts, MEMORY.md serves as the compact, curated layer. It is neither a raw transcript, a daily log, nor a comprehensive archive.

The working layer consists of memory/YYYY-MM-DD.md files: detailed daily notes, observations, session summaries, and raw context that could still prove useful. These get indexed for memory_search and memory_get, yet they are not inserted into the bootstrap prompt on every turn.

Over time, the default dreaming sweep distills useful material from daily notes into MEMORY.md. The generated workspace instructions still prompt the agent to record durable facts during work, while dreaming manages background consolidation. The default heartbeat prompt does not perform any memory maintenance itself.

Should MEMORY.md exceed the bootstrap file budget, OpenClaw leaves the file on disk untouched but truncates the copy injected into context. Treat that as a cue to shift detailed material into memory/*.md, keep only a durable summary in MEMORY.md, or increase the bootstrap limits if you prefer to allocate more prompt budget. Use /context list, /context detail, or openclaw doctor to inspect raw versus injected sizes and truncation status.

Import from coding assistants

Existing local memory from Codex, Claude Code, and Hermes can be imported through the Control UI. Open Settings → Import Memory, pick the destination agent, examine the detected files, and confirm the import. For the existing default agent, an alternative is Settings → Ask OpenClaw with the phrase import memory; this narrower chat wizard requires completed onboarding, copies only newly detected memory, and reports per-source failures or possible partial copies. Only Markdown memory gets copied by OpenClaw:

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 it exists. Project instructions, sessions, settings, and credentials fall outside this memory-only action.
Hermes: MEMORY.md and USER.md from the detected Hermes home. Config, credentials, and skills fall outside this memory-only action.

Imported files remain separate under memory/imports/codex/ and memory/imports/claude-code/, or memory/imports/hermes/ in the selected agent workspace. They are indexed for memory_search and reachable via memory_get; they are not merged into the agent's bootstrap MEMORY.md. The source files stay untouched.

The preview flags destination conflicts. Turning on Replace existing imports overwrites those files; applying creates a verified pre-import backup and keeps item-level copies of overwritten files in the migration report.

Action-sensitive memories

Most memories are ordinary Markdown notes. Some shape what the agent should do later; for those, record 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.

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.

Memory tools

Three tools let the agent work 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.
intent, creates, lists, or explicitly cancels event-conditioned standing intents. Time-based reminders continue to use scheduled tasks.

Both tools are provided by the active memory plugin (default: memory-core).

Memory search

With an embedding provider configured, memory_search employs hybrid search: vector similarity (semantic meaning) combined with keyword matching (exact terms like IDs and code symbols). This functions immediately with an API key for any supported provider.

Info

OpenAI embeddings are the default for OpenClaw. 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.

For details on how search operates, tuning options, and provider setup, see Memory search.

Memory engines

Builtin (default), SQLite-based. Works out of the box with keyword search, vector similarity, and hybrid search. No extra dependencies.
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

If your goal is for durable memory to act as a curated knowledge base rather than a collection of raw notes, the included memory-wiki plugin is the way to go. It assembles durable knowledge into a wiki vault featuring predictable page layouts, organized claims with supporting evidence, checks for contradictions and freshness, auto-generated dashboards, compiled digests, and wiki-native utilities (wiki_status, wiki_search, wiki_get, wiki_apply, wiki_lint).

The memory-wiki plugin does not take over the role of the active memory plugin; that plugin continues to manage recall, promotion, and dreaming. Instead, memory-wiki introduces a knowledge layer rich in provenance alongside it. The compiled wiki is accessible in the Control UI via Memory → Dreams → Diary → Memory Wiki (details).

Memory Wiki, Turns durable memory into a wiki vault with provenance, claims, dashboards, bridge mode, and Obsidian-friendly workflows.

Automatic memory flush

Prior to compaction condensing your conversation, OpenClaw triggers a quiet turn that prompts the agent to store important context in memory files. This behavior is enabled by default; set agents.defaults.compaction.memoryFlush.enabled: false to disable it.

To keep that housekeeping turn active on a local model, configure an exact override that applies solely to the memory-flush turn (it does not carry over the active session's model fallback chain):

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

Tip

The memory flush safeguards against context loss during compaction. If your agent holds critical facts in the conversation that have not yet been persisted to a file, they are saved automatically before the summary runs.

Dreaming

Dreaming serves as the default background pathway for memory consolidation. It gathers short-term recall signals, evaluates candidates, and promotes only qualified owner or agent-derived items into long-term memory (MEMORY.md):

Default on: turn it off with plugins.entries.memory-core.config.dreaming.enabled: false.
Scheduled: when active, memory-core automatically manages a single recurring cron job for a complete dreaming sweep.
Thresholded: promotions must satisfy gates for score, recall-frequency, and query-diversity.
Consolidated: after the deterministic gate, a bounded subagent rewrite merges duplicates and replaces stale entries. If a rewrite is invalid or unavailable, an append-only fallback is used.
Taint gated: candidates from untrusted or system-derived sources are never included in the consolidation prompt or the durable promotion path.
Reviewable: phase summaries and diary entries, including rewrite counts and highlights, are written to DREAMS.md for human inspection.

This background pattern aligns with the rationale behind sleep-time compute (arXiv:2504.13171). Provenance-aware reflection also draws on the durable memory insights from the Generative Agents research.

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

Grounded backfill and live promotion

The dreaming system offers two related review lanes:

Live dreaming operates on the short-term dreaming store under memory/.dreams/ and is what the normal deep phase uses to determine what advances 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 handy for replaying older notes and seeing what the system deems durable, without needing to manually edit 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 that the normal deep phase already uses; it does not promote them directly. Consequently:

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

To reverse 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