OpenClaw Memory Subsystem
OpenClaw Memory Subsystem
Philosophy
Memory is plain Markdown on disk — no hidden state, fully auditable. The agent reads and writes normal files.
Storage layout
| File | Role | When loaded |
|---|---|---|
MEMORY.md |
Long-term facts and preferences | Every session |
memory/YYYY-MM-DD.md |
Daily notes | Today + yesterday, automatically |
DREAMS.md |
Dream diary / consolidation summaries | Optional |
Agent-facing tools
Two tools exposed to the agent:
memory_search— hybrid semantic + keyword search across all notesmemory_get— direct read of a specific file or line range
Search engine
The default Builtin engine is SQLite + FTS5 with no extra dependencies. It runs two retrieval paths in parallel and merges the results:
| Path | Good for |
|---|---|
| Vector (embeddings) | Paraphrase, synonyms, conceptual queries |
| BM25 keyword | Exact strings, IDs, error codes, config keys |
Embedding providers are auto-detected from environment API keys (OpenAI → Gemini → Voyage → Mistral); local options (Ollama, GGUF ~0.6 GB) require explicit config. No provider = keyword-only fallback. Chunks are ~400 tokens with 80-token overlap.
Two optional quality layers sit on top:
- Temporal decay — a note from last month scores at ~50% weight, keeping recent notes prominent
- MMR (Maximal Marginal Relevance) — top results cover different topics; prevents redundant near-duplicates
Three pluggable backends
| Backend | Description |
|---|---|
| Builtin (default) | SQLite; zero deps; hybrid search |
| QMD | Local sidecar; adds reranking + query expansion |
| Honcho | AI-native; cross-session user modeling |
Lifecycle integration
- Context Assembly (phase 3): memory search fires automatically every turn; results are injected into the system prompt before the model call. The agent can also call
memory_search/memory_getexplicitly mid-turn. - Automatic Memory Flush: before Compaction, the framework reminds the agent to save important context to disk — preventing information loss across context collapses.
- Dreaming: background consolidation that promotes short-term signals to
MEMORY.mdbased on a scoring threshold and recall frequency. - Grounded Backfill: replays historical notes to audit what would qualify as durable memory, without promoting anything yet.
Advanced
| Feature | Description |
|---|---|
| Multimodal indexing | Images and audio indexed via Gemini Embedding 2 |
| Session memory search | Optional transcript indexing for cross-session conversation recall |
| Memory Wiki Plugin | Compiles notes into a structured vault with typed claims, contradiction tracking, and dashboards |
Diagnostics
openclaw memory status # index health + provider
openclaw memory index --force # full rebuild
See also
- Memory System — canonical concept page
- Builtin Memory Engine — SQLite implementation details
- Memory Search — dual retrieval, temporal decay, MMR
- Context Assembly — how memory feeds into the prompt
- Compaction — triggers the Automatic Memory Flush