# OpenClaw Memory System The memory system is [[OpenClaw]]'s answer to "the agent should remember things across conversations." It stores memory as plain Markdown files in the agent's workspace, keeps a curated long-term file, and provides agentic tools so the model itself can search, recall, and persist. The headline design choice: **memory is not a vector database, it's a folder of Markdown.** Vector search is layered on top, but the source of truth is human-readable files the operator can inspect, edit, version-control, and back up. ## Two Tiers - **Daily memory**: `memory/YYYY-MM-DD.md` - Append-only daily log - Today's and yesterday's entries auto-loaded on a bare `/new` or `/reset`; otherwise indexed for `memory_search` / `memory_get` rather than injected on every turn - Captures running thread of recent activity - **Long-term memory**: `MEMORY.md` - Curated, durable knowledge about the user, project, conventions - Loaded only in **main / private** sessions ; not in group/sandboxed contexts to limit leakage Both files live inside the agent's workspace (the default workspace is `~/.openclaw/workspace`; each routed agent gets its own), so each isolated agent has its own memory ; consistent with the [[OpenClaw Multi-Agent Routing|multi-agent routing]] model. Current docs list two more optional files next to these: - **`USER.md`** ; a compact user model: stable preferences and profile facts written as directives, loaded at session start with its own small budget - **`DREAMS.md`** ; the Dream Diary: summaries of the background "dreaming" sweep that distills useful material from daily notes into `MEMORY.md` ## Agentic Tools The agent has direct tool access: - `memory_search` ; semantic recall across indexed snippets - `memory_get` ; targeted file read by path This means the model itself decides when to look something up; memory is not pre-stuffed into every prompt. ## Auto-Persist on Compaction Before context compaction, OpenClaw runs a **silent agentic turn** that prompts the model to identify and persist durable memories. The user never sees this turn ; it just happens, on the way to the compaction step. The result is that important facts surface from long sessions into MEMORY.md without manual curation. ## Vector Search Layer The retrieval engine is hybrid: - **BM25** lexical scoring (classic term matching) - **Vector** embeddings (semantic similarity) - **MMR** (Maximal Marginal Relevance) re-ranking for diversity - **Temporal decay** so older snippets fade unless reinforced Embedding providers are pluggable: OpenAI, Gemini, Voyage, Mistral, [[Ollama]], local GGUF. Pick whatever matches the privacy/cost posture you want; local GGUF keeps everything inside the host. ## Pluggable Memory Engines The default is the **builtin engine**: a per-agent SQLite index with keyword, vector and hybrid search (MMR on by default, optional sqlite-vec acceleration). Alternatives in the docs: - **Honcho memory** ; third-party, AI-native cross-session memory - **LanceDB** ; plugin with OpenAI-compatible embeddings and auto-recall - ~~**QMD memory engine** ; specialized storage format~~ ; removed in OpenClaw 2.0 (see below) Memory engines are plugins ; install via `openclaw plugins install`, then set the active engine in config. ## What Changed in OpenClaw 2.0 [[2026-10-03 OpenClaw 2.0 - easier setup, shared sessions, same security defaults|OpenClaw 2.0]] (v2026.8.1, August 30, 2026) reworked memory: - **Recall across conversations**: an eligible personal Claw can recall relevant context from the same agent's other private conversations, including what mattered right before a reset. Recall stays inside that agent's private conversations and respects isolation and access policies - **Built-in memory owns search and recall**; the QMD backend is retired. If you used QMD, `openclaw doctor --fix` removes the old settings, carries over supported extra paths and session indexing, and rebuilds the index from the canonical Markdown. QMD-only reranking, query expansion and cross-agent transcript search are gone - **Visible workflows** to search indexed sources, inspect how memory works, import supported history, and remove derived memory. Forgetting derived memory doesn't erase the original conversation - **Import from coding assistants**: the Control UI (Settings, Import Memory) copies Markdown memory from Codex, [[Claude Code]] (project auto-memory) and [[Hermes Agent]] - Sessions and transcripts also moved from files to [[SQLite]] in 2.0; the Markdown memory files remain the source of truth ## Why Plain Files Win Compared to a vector-DB-only approach: - **Inspectable**: open in any editor, diff in `git` - **Migratable**: copy a folder, you've moved memory - **Backup-trivial**: it's `tar` + your normal backup pipeline - **Recoverable**: vector index can be rebuilt from the source files The vector layer accelerates retrieval; it never owns the truth. ## References - Memory overview: https://docs.openclaw.ai/concepts/memory - Builtin memory engine: https://docs.openclaw.ai/concepts/memory-builtin - OpenClaw 2.0 memory changes: https://docs.openclaw.ai/releases/2026.8.1/memory ## Related - [[OpenClaw]] - [[2026-10-03 OpenClaw 2.0 - easier setup, shared sessions, same security defaults]] - [[OpenClaw Multi-Agent Routing]] - [[OpenClaw Sub-Agents]] - [[Claude Code Memory]]