Memory Configuration

Most memory complaints come from assuming memory is magic. OpenClaw only remembers what gets written to Markdown files in the workspace: USER.md for stable preferences, MEMORY.md for durable facts, and dated daily notes in memory/. There is no hidden state.

The defaults are far better than they used to be. Embeddings default to OpenAI, a memory flush runs before compaction, and a nightly dreaming sweep distills useful daily notes into MEMORY.md. But defaults don't know your budget or your workload.

Make memory explicit and cheap: a cheap embedding model for search, cache-TTL pruning so stale tool output stops riding along, and a memory flush pinned to a cheap model. That removes most of the "why did it forget that" moments, which are usually configuration problems blamed on the model.

Memory settings now live under the top-level memory key, with per-agent overrides in agents.entries.<id>.memory.search. Search runs vector and BM25 keyword retrieval in parallel, so exact IDs and error strings still match.

"memory": {
  "search": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "sources": ["memory", "sessions"],
    "experimental": { "sessionMemory": true }
  }
}

sources defaults to ["memory"]. Adding "sessions" only requests transcripts; experimental.sessionMemory: true is what actually indexes them. Personal installs also get rememberAcrossConversations, which recalls from the same agent's other private chats.

"agents": {
  "defaults": {
    "contextPruning": {
      "mode": "cache-ttl",
      "ttl": "1h"
    }
  }
}

cache-ttl mode explained

• Pruning is off by default; mode: "cache-ttl" turns it on
• It trims old tool results (exec output, file reads, search results), never your normal conversation text, and never the session history on disk
• ttl sets how long the prompt cache stays fresh before a new pruning round may start. The built-in default is 5 minutes; the bundled Anthropic plugin seeds 1h
• Oversized results are soft-trimmed first (head and tail kept), then hard-cleared to a placeholder if context is still heavy. The most recent assistant messages are preserved

This is the most important memory setting. When context gets too long, compaction summarizes the conversation. Before it does, a silent memory flush saves durable context into the daily note so it isn't lost in the summary.

"agents": {
  "defaults": {
    "compaction": {
      "mode": "safeguard",
      "notifyUser": true,
      "memoryFlush": {
        "enabled": true,
        "model": "ollama/qwen3:8b"
      }
    }
  }
}

How it works

1. 1Context approaches the compaction thresholdOpenClaw works out when to flush from your config and the model's context window.
2. 2A silent turn saves what mattersOn a private copy of the conversation, the agent is reminded to store durable context. You never see these housekeeping messages.
3. 3It appends to the daily noteMemory Core writes only new text to memory/YYYY-MM-DD.md. Replayed or copied paragraphs are rejected.
4. –Or it answers NO_REPLYIf nothing is worth storing, the flush ends without a write. Compaction then summarizes as usual.

safeguard mode audits summary quality and keeps recent turns verbatim. memoryFlush.model keeps the housekeeping turn on a cheap or local model; it's an exact override and doesn't inherit your fallback chain, so pick one that's reliably up. notifyUser tells you when compaction runs instead of leaving you guessing.

Here's how all three pieces fit together in openclaw.json:

{
  "memory": {
    "search": {
      "provider": "openai",
      "model": "text-embedding-3-small",
      "sources": ["memory", "sessions"],
      "experimental": { "sessionMemory": true }
    }
  },
  "agents": {
    "defaults": {
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "1h"
      },
      "compaction": {
        "mode": "safeguard",
        "notifyUser": true,
        "memoryFlush": {
          "enabled": true,
          "model": "ollama/qwen3:8b"
        }
      }
    }
  }
}

Together these settings make a memory system that's cheap, reliable and doesn't lose important context. The agent remembers what matters, forgets what doesn't, and the housekeeping runs on a fraction of what premium models would cost.

Check what actually lands in context with /context list and openclaw memory status. For more options, see the Config Reference chapter or the Mega Cheatsheet.