Your Agent Has Amnesia

You told your agent your name yesterday. Today it asks again. You made a decision in the morning. By afternoon, it's forgotten. Sound familiar?

This isn't a bug. This is OpenClaw working exactly as designed — and the design assumes you will configure memory properly. Most people don't, and then wonder why their agent has the long-term recall of a goldfish.

This chapter diagnoses the problem and fixes it with one prompt. The next chapter covers how to use memory day to day.

The Core Insight

Memory in OpenClaw is a suggestion, not a requirement.

The LLM — Claude, GPT, DeepSeek, whatever model you're running — makes its own decisions about memory. It decides whether something is worth saving. It decides whether to search memory before answering a question. It decides how to handle a shrinking context window.

Without explicit configuration, your agent will:

• Sometimes save things, sometimes not
• Sometimes search memory, sometimes guess from context
• Silently destroy information when the conversation gets too long

This isn't the agent being broken. It's the agent being unconfigured. The defaults prioritize speed and cost over reliability. You need to change three things.

The Three Failure Modes

Every "OpenClaw keeps forgetting things!" post in the community is one of these three problems.

Failure Mode 1: Never Saved

This is the most common failure. You tell your agent something important — a preference, a decision, a piece of context — and it just... doesn't write it down. The information exists only in the active conversation window. Close the session, and it's gone forever.

Why does this happen? The LLM treats memory writes as a tool call, and it has to decide to make that call. If the model doesn't think the information is important enough, it won't save it. Your name? Maybe. Your favorite color? Probably not. A critical project decision buried in a casual message? Coin flip.

The model is optimizing for efficiency, not completeness. It doesn't know what matters to you — it's making a best guess, and that guess is often wrong.

Failure Mode 2: Saved But Never Retrieved

This one is sneakier. You've been diligent about saving things to memory. The files are there on disk, perfectly formatted. But when you ask "what did we decide about X yesterday?" your agent improvises an answer from whatever fragments are in the current conversation instead of searching the memory files.

The agent has a memory_search tool available. But using it is — again — a decision the LLM makes on its own. If your question sounds like something it can answer from the current context, it often will, even if the answer is wrong or incomplete. It's faster and cheaper to guess than to search.

Failure Mode 3: Context Compaction Destroys Knowledge

This is the scariest failure mode. You're having a long, productive session. The context window is filling up. OpenClaw silently runs compaction — summarizing older messages to make room for new ones. Anything that was only in the conversation (not written to a file on disk) gets compressed into a lossy summary, or deleted entirely.

You don't get a warning. You don't get a chance to save. The information is just... gone.

And here's the kicker: even the contents of MEMORY.md that were loaded into context can get summarized away during a long session. The file on disk is still intact, but the agent loses awareness of its contents until the next session loads it fresh.

Fix All Three at Once

Now the good news: all three failure modes have configuration fixes, and you can apply them in a single prompt.

Open your Telegram chat with OpenClaw (or the Gateway at http://127.0.0.1:18789/) and paste this:

Update my ~/.openclaw/openclaw.json config file.

Merge the following JSON under agents.defaults, preserving
all my existing settings (channels, model config, etc.):

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 40000,
          "systemPrompt": "Session nearing compaction. Store durable memories now.",
          "prompt": "Distill this session to memory/YYYY-MM-DD.md. Focus on: decisions, state changes, lessons, blockers. If nothing important: NO_FLUSH"
        }
      },
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "6h",
        "keepLastAssistants": 3
      },
      "memorySearch": {
        "enabled": true,
        "sources": ["memory", "sessions"],
        "experimental": {
          "sessionMemory": true
        },
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3
          }
        }
      }
    }
  }
}

After updating the config, restart the gateway and confirm
the changes took effect. Show me the relevant section of
the config file so I can verify.

That's it. Your agent will update the config, restart the gateway, and show you what changed. One prompt, three fixes.

What Your Agent Just Did

That prompt applied three separate fixes. Here's what each one does and why it matters:

Fix 1: Memory Flush (Fixes "Never Saved")

"compaction": {
  "mode": "safeguard",
  "reserveTokensFloor": 20000,
  "memoryFlush": {
    "enabled": true,
    "softThresholdTokens": 40000,
    "systemPrompt": "Session nearing compaction. Store durable memories now.",
    "prompt": "Distill this session to memory/YYYY-MM-DD.md. Focus on: decisions, state changes, lessons, blockers. If nothing important: NO_FLUSH"
  }
}

This triggers a silent turn before compaction happens, giving your agent a chance to write important information to disk before the context window resets. Think of it like a fire alarm that gives your agent 30 seconds to grab the critical files before the office resets.

• mode: "safeguard" — Activates the protective compaction strategy instead of the aggressive default
• reserveTokensFloor: 20000 — Reserves a 20,000-token buffer so compaction doesn't eat into working space. Without this, your agent can run out of room to think before it even notices compaction is coming
• memoryFlush.enabled: true — The big switch. Turns on the pre-compaction save
• softThresholdTokens: 40000 — Triggers the flush at 40,000 tokens instead of waiting until the hard limit. The agent starts saving early, before the good stuff gets lost
• systemPrompt — Injected into the agent's context right before the flush turn. Sets the urgency: compaction is coming, save what matters
• prompt — The instruction your agent follows during the flush. Captures decisions, state changes, lessons, and blockers. The NO_FLUSH escape valve means it won't create empty daily logs when nothing meaningful happened

Fix 2: Context Pruning (Prevents Repeat Yourself Loop)

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

Controls how old messages are removed before compaction runs. Without it, compaction is aggressive and unpredictable — it might keep a joke from three hours ago and delete the decision you made an hour ago.

• mode: "cache-ttl" — Uses time-based pruning. Messages older than the TTL get removed first, newest stay
• ttl: "6h" — Keeps messages from the last 6 hours. Anything older is eligible for removal
• keepLastAssistants: 3 — Always preserves the 3 most recent assistant responses, no matter how old. This is the key to not repeating yourself — your agent always remembers the last few things it said

Fix 3: Hybrid Search (Fixes "Saved But Never Retrieved")

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

Combines two search approaches so your agent actually finds things:

• enabled: true — Turns on memory search globally
• sources: ["memory", "sessions"] — Searches both permanent memory files and session history
• experimental.sessionMemory: true — Indexes past conversations, not just memory files. Even things you didn't explicitly save become searchable
• hybrid.enabled: true — Combined search instead of vector-only
• vectorWeight: 0.7 — 70% weight on semantic meaning. "What did I build?" matches "set up a monitoring workflow"
• textWeight: 0.3 — 30% weight on exact keywords. Catches baseline.sha256, Argus, error codes — specific strings that vectors miss

Optional: Advanced Search Tweaks

Once you've used hybrid search for a week or two, you can ask your agent to add two refinements. Paste this when you're ready:

Update my memorySearch config in openclaw.json.

Add these two settings inside the hybrid block, keeping
everything else the same:

"mmr": {
  "enabled": true,
  "lambda": 0.7
},
"temporalDecay": {
  "enabled": true,
  "halfLifeDays": 30
}

Show me the updated hybrid block when done.

MMR (Maximal Marginal Relevance) removes near-duplicate results. If three memory files all say roughly the same thing, you get the best one instead of all three. lambda: 0.7 favors relevance — lower values give more variety.

Temporal Decay boosts recent notes so yesterday's update outranks a six-month-old entry. halfLifeDays: 30 means a note loses half its ranking boost after 30 days. Older notes aren't deleted — they just rank lower when newer content also matches.

The full hybrid block looks like this after the upgrade:

"memorySearch": {
  "query": {
    "hybrid": {
      "enabled": true,
      "vectorWeight": 0.7,
      "textWeight": 0.3,
      "mmr": {
        "enabled": true,
        "lambda": 0.7
      },
      "temporalDecay": {
        "enabled": true,
        "halfLifeDays": 30
      }
    }
  }
}

Don't add these on day one. You'll know you need MMR when duplicate results get annoying, and temporal decay when old notes keep burying new ones.

Credits

This chapter draws from the OpenClaw community's excellent research on memory:

• Kevin Simback (@KSimback) — Deep-dive on the three failure modes and configuration fixes
• Nick Spisak (@NickSpisak_) — Fire alarm analogy and reserveTokensFloor insights
• Tobi (CEO of Shopify) — Creator of QMD, the open-source search engine we'll cover in Chapter 9

Thanks to these contributors for documenting what works and sharing it with the community.

What's Next

You just fixed the biggest problem most OpenClaw users don't even know they have. Your agent now saves important information before compaction destroys it, prunes context intelligently instead of randomly, and searches memory using both meaning and keywords.

But configuring memory is only half the story. In the next chapter, you'll learn how to actually use it — where memory files live, how sessions and memory work together, how to write daily logs, how to search effectively, and the habits that turn a configured system into a genuine second brain.