OpenClaw Memory Management Guide

Why your OpenClaw agent forgets things, the configuration changes that fix most issues, and the advanced tools that make memory production-grade. Based on the guide by Kevin Simback.

Why OpenClaw Memory Breaks

OpenClaw treats memory as a suggestion, not a requirement. The agent decides what to save, when to search, and what to recall. Without explicit configuration, it forgets by default.

There are three common failure modes, and each requires a different solution.

Failure 1: Memory Is Never Saved

When you tell your agent something important — your name, your preferences, a critical project decision — OpenClaw doesn't automatically write it to disk. The LLM makes a real-time judgment call on whether it's worth storing. Important context can slip through constantly because the model deemed it not worth saving.

This is like having an employee who decides on their own which meeting notes to keep and which to throw away.

Failure 2: Memory Is Saved But Never Retrieved

Even when facts make it to disk, recall isn't guaranteed. OpenClaw provides a memory_search tool, but the agent has to decide to use it. In practice, when you ask about something stored in memory, the model frequently answers from its current context window instead of searching. From your perspective it "forgot" — but in reality, it never looked.

This is like an employee who saved a document to Google Drive, but when you ask for it, they answer from memory instead of checking the actual document.

Failure 3: Context Compaction Destroys Knowledge

This is the killer. To avoid hitting token limits, OpenClaw compacts context — older messages get summarized or removed. Any information that only existed in the active conversation and wasn't yet saved to disk is destroyed. This applies even to MEMORY.md content, which loads at session start but can get summarized away during a long session.

Imagine having an employee with a stack of papers on their desk. When the stack gets too tall, they throw out the oldest papers to make room — without saving the important ones.

Basic Fixes: What Everyone Should Configure

Before reaching for plugins or external databases, there's a lot you can fix with configuration alone. Most cases of "my agent forgets everything" come from running the default config without any optimizations.

1. Enable Memory Flush (Critical)

Memory flush triggers a silent turn before compaction that prompts the agent to write durable memories to disk. This is the single most impactful change you can make.

Customize the prompt to tell it exactly what to capture — decisions, state changes, lessons, blockers. Raise softThresholdTokens to 40000 to trigger flushes earlier, before the good stuff gets compacted.

{
  "compaction": {
    "memoryFlush": {
      "enabled": true,
      "softThresholdTokens": 40000,
      "prompt": "Distill this session to memory/YYYY-MM-DD.md. Focus on decisions, state changes, lessons, blockers. If nothing: NO_FLUSH",
      "systemPrompt": "Extract only what is worth remembering. No fluff."
    }
  }
}

2. Configure Context Pruning

Context pruning controls how old messages are removed before full compaction. Use TTL mode to keep messages from the last 6 hours and always preserve the 3 most recent assistant responses. This eliminates the annoying situation where you have to repeat recent messages following a context flush.

{
  "contextPruning": {
    "mode": "cache-ttl",
    "ttl": "6h",
    "keepLastAssistants": 3
  }
}

3. Enable Hybrid Search

Memory search combines vector similarity (conceptual matching) with BM25 keyword search (exact tokens). You want both enabled. BM25 catches exact matches (error codes, project names) that vector search misses.

{
  "memorySearch": {
    "enabled": true,
    "sources": ["memory", "sessions"],
    "query": {
      "hybrid": {
        "enabled": true,
        "vectorWeight": 0.7,
        "textWeight": 0.3
      }
    }
  }
}

4. Index Past Sessions

Enable session transcript indexing to recall conversations from weeks ago. This chunks and indexes past conversations alongside your memory files, so questions like "What did we decide about the content template last Tuesday?" become answerable.

{
  "memorySearch": {
    "sources": ["memory", "sessions"]
  },
  "experimental": {
    "sessionMemory": true
  }
}

Advanced Memory Solutions

For agents running more demanding workloads — multi-day projects, multi-agent team coordination, or complex knowledge management — the built-in system can hit limitations. Here's where to go next.

QMD: Superior Retrieval Backend

QMD, developed by Tobi (CEO of Shopify), is an opt-in replacement for the built-in SQLite indexer. It runs as a local sidecar that combines BM25 + vectors + reranking. Retrieval quality is noticeably better.

The killer feature: you can index external document collections. Your Obsidian vault, project documentation, Notion exports — all become searchable via memory_search.

Mem0: Compaction-Proof External Memory

Mem0 stores memories outside the context window entirely, so compaction literally cannot destroy them. Two processes run every turn:

Auto-Capture detects information and stores it without depending on the LLM's judgment
Auto-Recall searches and injects relevant memories before the agent responds

This solves Failure Modes 1 and 3 completely — memory is captured automatically and survives any compaction. Mem0 installs as an OpenClaw plug-in.

Cognee: Knowledge Graphs

When you need to query relationships between people, places, and things, vector search isn't enough. Cognee ingests OpenClaw's memory files to construct a graph of entities and relationships — for example, "Alice owns the auth module" creates nodes for Alice with an "owns" edge to auth.

Best suited for enterprise settings or multi-agent teams requiring deep understanding of structured knowledge. May be overkill for basic setups.

Obsidian Integration

Obsidian works as an external brain for agent memory. Two integration approaches:

Symlink your memory folder — your agent's daily notes appear in Obsidian across all devices for easy review and annotation
Index your vault via QMD — everything in Obsidian becomes searchable by your agents. One knowledge base, multiple access patterns. This is the most robust approach.

Multi-Agent Memory Architecture

For teams running specialized agents across multiple OpenClaw instances, memory should be structured in layers — just like a human team's documentation.

Private memory per agent — each agent has its own workspace with MEMORY.md and daily notes. Private context stays private.
Shared reference files — a symlinked _shared/ directory containing user profile, agent roster, and team conventions. Every agent sees the same ground truth.
QMD with shared paths — each agent's QMD config includes the shared directory, so they can all search the same reference docs while maintaining private memory.
Coordination — a "Chief of Staff" agent reads core files at session start and maintains consistency. Specialists focus on their domains.

The Bottom Line

OpenClaw treats memory as suggestions — you have to configure it to be reliable. The basic configuration changes (memory flush, context pruning, hybrid search, session indexing) fix most problems. For production-grade memory, layer in QMD, Mem0, or Cognee depending on your needs.

Start with memory flush. It's the single highest-impact change. Then layer on the rest as needed.

Need help configuring memory for your OpenClaw setup?

ClawEasy handles memory configuration as part of every deployment. We'll set up memory flush, hybrid search, and session indexing — tuned for your specific workflow.

Get Started

This guide is based on Kevin Simback's comprehensive memory management article. Follow him for more OpenClaw guides and tips.