OpenClaw Memory System: Setup, Configuration, and Best Practices

OpenClaw's GitHub repository has logged dozens of compaction-related bug reports in 2026 alone, from silent context resets to flush settings being ignored at runtime. The root cause is architectural: compaction permanently rewrites conversation history into lossy summaries, and any instruction or fact that exists only in the chat transcript gets compressed or dropped entirely.

The memory system exists to solve this. Instead of relying on the conversation window, OpenClaw stores knowledge in plain Markdown files that reload at every session start, survive compaction, and remain searchable even when they're not actively injected into the prompt.

The system splits into three tiers, each serving a different purpose:

1. Long-term memory stores durable facts, preferences, and standing decisions. It loads into every session automatically.
2. Daily notes capture detailed session observations. They're indexed for search but not injected into every prompt turn, keeping the bootstrap budget manageable.
3. Dream diary records consolidation summaries from the optional dreaming process, which promotes qualified items from daily notes into long-term storage.

If information isn't written to one of these tiers, it doesn't survive compaction. That's the single most important principle of OpenClaw memory.

OpenClaw stores memory as plain Markdown files in the agent workspace. No database to configure, no schema to define. You create the files and the system reads them.

MEMORY.md: The Durable Layer

This file loads at every session start. Keep it compact and curated: standing decisions, user preferences, project rules, and short summaries that the agent needs on every turn.

Good MEMORY.md entries state facts, not instructions. "User prefers TypeScript over JavaScript" works. "Remember to always use TypeScript" does not, because the model treats it as a one-time instruction rather than a persistent preference.

If MEMORY.md grows past the bootstrap token budget, the file stays intact on disk but gets truncated in model context. Run /context list to check whether truncation is happening and how much of the file the model actually sees.

Daily Notes: The Working Layer

Files under memory/ with a date-stamped filename (memory/2026-06-14.md or memory/2026-06-14-project-setup.md) capture session-specific detail. These notes are indexed for search through memory_search but aren't loaded into the prompt by default.

This separation matters. MEMORY.md carries the small set of facts every session needs. Daily notes carry the large set of observations any session might need, available on demand through search without consuming bootstrap tokens.

DREAMS.md: Automated Consolidation

The optional dreaming process collects short-term signals from daily notes, scores candidates against recall frequency and query diversity gates, and promotes only qualified items into MEMORY.md. Summaries of what was promoted (and what was skipped) get written to DREAMS.md for human review.

Dreaming is disabled by default. When enabled, OpenClaw manages a recurring cron job that runs the consolidation pass automatically. The diary entries in DREAMS.md give you visibility into what the system chose to remember and why.

The memory_search tool finds relevant notes using hybrid search that combines vector similarity (semantic meaning) with keyword matching (exact terms, IDs, code symbols). This means a search for "authentication setup" will find notes that mention "login configuration" or "OAuth flow" even when the exact words differ.

The default embedding provider is OpenAI. Override it by setting agents.defaults.memorySearch.provider in your configuration to use any supported provider:

• OpenAI (default): cloud-hosted, highest quality for English text
• Gemini: Google's embedding model, strong multilingual support
• Voyage: optimized for code and technical content
• Mistral: European-hosted option with good multilingual performance
• Ollama: fully local, no data leaves your machine
• Bedrock: AWS-hosted, useful for teams already on AWS infrastructure

For air-gapped or privacy-sensitive setups, Ollama is the clear choice. The local embedding model downloads automatically on first use. For teams that want semantic search without sending workspace content to any external API, this is the path. Teams that also need a persistent, shared storage layer for their memory files can pair any embedding provider with a workspace like Fast.io's free agent tier, which auto-indexes uploaded files for its own semantic search through Intelligence Mode.

The companion tool memory_get reads specific files or line ranges when you already know what you're looking for. Use memory_search for discovery, memory_get for retrieval.

CLI Access

You can search and manage the index from the command line without starting a conversation:

openclaw memory status
openclaw memory search "deployment configuration"
openclaw memory index --force

The status command shows the current index state and provider. The --force flag on index rebuilds the entire index from scratch, useful after switching embedding providers or recovering from a corrupted index.

Give Your OpenClaw Agent Persistent File Storage

50 GB free workspace with MCP-ready access and auto-indexed semantic search. No credit card, no expiration.

Sign Up Free

OpenClaw ships with a built-in SQLite backend and supports three plugin alternatives. Each trades off simplicity against capability.

Built-in (SQLite) is the default. It handles keyword search, vector similarity, and hybrid queries with no extra dependencies. For most single-agent setups, this is sufficient and the right starting point.

QMD is a local-first sidecar that adds query expansion, reranking, and the ability to index files outside the workspace (Obsidian vaults, project documentation, reference repos). If you already have a knowledge base you want the agent to search alongside its own notes, QMD bridges that gap without moving files.

Honcho targets multi-agent and multi-user scenarios. It provides cross-session awareness and user modeling, so agents serving different users can maintain isolated memory contexts while sharing common knowledge. This requires a plugin install and external service.

LanceDB stores memory in a LanceDB-backed vector database with automatic recall before each model turn and automatic capture after each response. It supports local Ollama embeddings for fully offline operation. The community-maintained LanceDB Pro variant adds BM25 hybrid retrieval, cross-encoder reranking, and multi-scope isolation for teams running multiple agents.

For a single developer working with one agent, start with the built-in SQLite backend and move to LanceDB or QMD only when you hit a concrete limitation (index size, offline requirements, or cross-project search).

Before conversation compaction, OpenClaw runs a silent turn that reminds the agent to save important context to memory files. This automatic flush is enabled by default, but the default settings often trigger too late.

The reserveTokensFloor setting controls how much headroom the flush gets. The default of 20,000 tokens is frequently insufficient for sessions with large tool outputs or code blocks. Setting it to 40,000 gives the flush turn enough room to write meaningful notes before compaction compresses the conversation.

The flush turn uses the session's primary model by default. For cost control, you can override this with a smaller local model that handles the note-writing pass without consuming API credits:

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

This override applies only to the memory-flush turn. The main conversation continues using whatever model you configured for the session.

Three other settings reduce unnecessary compaction triggers:

• softThresholdTokens: 4000 fine-tunes when the flush fires relative to the context limit
• Cache-TTL pruning mode with a 5-minute TTL trims stale tool outputs per-request without triggering full compaction
• maxContextTokens set to 80% of your model's actual limit prevents the edge case where token counting discrepancies cause premature compaction

The distinction between compaction and pruning matters here. Compaction permanently rewrites the conversation into a lossy summary. Pruning temporarily trims tool outputs from a single request without changing the saved transcript. Aggressive pruning settings reduce how often compaction fires, which reduces how often memory flush needs to save the day.

Dreaming automates the promotion of daily notes into long-term memory. Without it, MEMORY.md only gets what you (or the agent) manually writes there. With dreaming enabled, the system reviews daily notes on a schedule and promotes entries that pass three gates: a minimum relevance score, sufficient recall frequency (how often the information was referenced), and query diversity (whether the information matters across different contexts, not just one repeated query).

Entries that pass all three gates get added to MEMORY.md. Everything reviewed, promoted or not, gets logged in DREAMS.md so you can audit the system's decisions.

Grounded Backfill

For existing workspaces with weeks or months of daily notes that predate dreaming, the backfill command processes historical files:

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

This reads historical memory/YYYY-MM-DD.md files and stages them for the next dreaming pass. If the results are wrong, roll back with:

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

Commitments vs. Memory

OpenClaw distinguishes between memory (durable facts) and commitments (short-lived follow-ups). Commitments are inferred in a background pass, scoped to the same agent and channel, and delivered through heartbeat check-ins. They're not stored in MEMORY.md because they expire. Use scheduled tasks for explicit reminders with deadlines; use memory for facts that stay true indefinitely.

Where Persistent File Storage Fits

As memory files accumulate, the question of where they live becomes practical. Local disk works for solo development, but teams running multiple agents or sharing context across projects need durable, accessible storage. Fast.io workspaces provide 50 GB of free persistent storage where agents read and write files through the MCP server, with Intelligence Mode auto-indexing those files for semantic search. Agents working in the same workspace share the indexed knowledge layer without additional configuration. Local alternatives like S3 or Google Drive work too, but require separate indexing infrastructure to make stored files searchable by meaning rather than just filename.