OpenClaw Memory

Quick Recap: The 4 Layers

From Part 1, we learned about:

1. Bootstrap Files - Permanent identity (reloaded from disk)
2. Session Transcript - Conversation history (gets compacted)
3. Context Window - Active memory (fixed size)
4. Retrieval Index - Searchable archive (files only)

Now let's see how these layers fail.

A Real-World Example

What Happened

• She told the agent: "Don't do anything until I say so"
• Agent worked fine on test inbox for weeks
• Pointed it at real inbox with thousands of messages
• Context window filled up → compaction fired
• That instruction (given in chat, not saved to file) disappeared from the summary
• Agent went autonomous and started deleting emails

The Lesson

If Meta's Director of Alignment can lose control, so can you.

Important: Compaction is normal. The failure is relying on chat-only rules to survive long sessions.

The 3 Failure Modes

When your agent forgets, it's always one of these:

1. Failure A: Never Stored
2. Failure B: Compaction Changed Context
3. Failure C: Session Pruning

Let's break down each one.

Failure A: Never Stored

The instruction/preference/decision only existed in conversation.

It was never written to a file.

When compaction fires or new session starts → gone forever

Failure A: What Gets Lost

Examples of things that disappear:

• Instructions given in chat: "Always check X before doing Y"
• Preferences mentioned casually: "I prefer JSON over YAML"
• Decisions made mid-conversation: "Let's use approach B"
• Constraints stated once: "Don't touch the production database"
• Context from earlier: "Remember, this is for the client demo"

Failure A: Why It Happens

1. You give instruction in chat
2. Agent acknowledges and follows it
3. Session continues, context fills up
4. Compaction summarizes old messages
5. Your instruction gets compressed or dropped
6. Agent no longer "remembers" it

This is exactly what happened to Summer Yue

Failure A: Bootstrap File Limits

• 20,000 characters per file
• 150,000 characters total across all bootstrap files
• If exceeded → file gets truncated
• Truncated portion is invisible to the agent

Check with: /context list

Failure A: The Fix Preview

Write important instructions to bootstrap files:

• AGENTS.md for workflow rules
• MEMORY.md for current context
• USER.md for preferences

These files survive compaction because they're reloaded from disk.

Failure B: Compaction Changed Context

Long session hits token limit → compaction summarizes old messages

The summary can be lossy:

• Drops important details
• Loses nuance
• Misses specific constraints

Failure B: How It Happens

1. Context window approaches limit (e.g., 156K / 200K tokens)
2. OpenClaw triggers compaction
3. Model summarizes old conversation into ~5-10K tokens
4. Summary replaces detailed history
5. Agent now operates from summary, not original words

Note: Recent messages (~20K tokens) stay intact

Failure B: Example

Original conversation (detailed):

After compaction (summary):

All the specific constraints are gone

Failure B: What Survives

After compaction, the model retains:

• Recent messages (~20K tokens stay intact)
• Bootstrap files (reloaded from disk)
• Summary of old messages (lossy)

Lost:

• Exact wording of old instructions
• Specific constraints and edge cases
• Context and reasoning behind decisions
• All images shared before compaction

Failure C: Session Pruning

Session pruning trims old tool results from memory:

• File reads
• Browser snapshots
• API responses

Important: This is actually your friend!

Failure C: Why It's Good

• ✓ Reduces bloat without destroying conversation
• ✓ Only affects tool results, not messages
• ✓ User and assistant messages stay intact
• ✓ Optimizes prompt caching (saves money)
• ✓ Delays compaction (the dangerous one)

Failure C: Cache-TTL Mode

{
  "contextPruning": {
    "mode": "cache-ttl",
    "ttl": "5m"
  }
}

• Auto-enabled for Claude setups
• Trims tool results after 5 minutes
• Preserves conversation flow
• Improves cache hit rates

Failure C: The Confusion

Most people confuse pruning with compaction.

They are completely different:

• Pruning = automatic, safe, let it happen
• Compaction = dangerous, loses context

Pruning is not a failure mode - it's a feature that prevents failure.

Compaction vs Pruning

Let's make this crystal clear:

Compaction vs Pruning

Compaction: The Two Paths

There are two ways compaction can happen:

1. Good Path: Controlled compaction with memory flush
2. Bad Path: Emergency compaction from overflow

The Good Path

1. Context nearing limit (e.g., 156K / 200K tokens)
2. Memory flush fires first (automatic safety net)
3. Agent saves important context to disk
4. Compaction summarizes old history
5. Agent continues with summary + saved context

Minimal context loss

The Bad Path

1. Context overflows limit (e.g., 205K / 200K tokens)
2. API rejects the request
3. No memory flush (already past the trigger point)
4. Emergency compaction fires
5. Aggressive summarization to recover

Maximum context loss

Good Path vs Bad Path

Configuration determines which path you take

Diagnostic Tool: /context list

Shows you:

• Which bootstrap files are loaded
• File sizes (raw vs injected)
• Truncation status
• Token estimates

/context list: What to Check

• Is MEMORY.md loading? If missing, it's not in context
• Is anything TRUNCATED? Content over 20K chars gets cut
• Do injected chars = raw chars? If not, content is being cut

The 3 Failure Modes: Summary

1. Never Stored (90%): Instructions given in chat, never written to files
2. Compaction Changed Context: Lossy summarization drops details
3. Session Pruning: Not actually a failure - it's helpful (cache-TTL mode)

Key insight: Compaction is the enemy, pruning is the friend

Diagnostic Checklist

When your agent forgets something, ask:

• Was it written to a file? → If no, that's Failure A
• Did it happen after a long session? → Probably Failure B (compaction)
• Was it a tool result? → That's Failure C (pruning, expected)

First step: Run /context list to verify what's loaded