Source: https://x.com/velvet_shark/status/2030042476418134148
Full article: https://velvetshark.com/openclaw-memory-masterclass
Author: Radek Sienkiewicz (@velvet_shark) — OpenClaw maintainer
Date reviewed: March 6, 2026
An OpenClaw maintainer with 2+ months of daily use explains the root cause of the "agent forgets instructions and goes rogue" problem: context compaction. The article covers all four memory layers, three distinct failure modes, and the three-layer defense system that prevents instruction loss. High signal — this is from someone inside the codebase, not a tutorial blogger.
Summer Yue, Meta's Director of Alignment, told her agent "don't do anything until I say so." It worked fine for weeks on a test inbox. When pointed at her real inbox (thousands of messages), the context window filled, compaction fired, and that instruction — given in chat, never saved to a file — vanished from the summary. The agent deleted her real emails while ignoring stop commands.
Her quote: "Rookie mistake tbh. Turns out alignment researchers aren't immune to misalignment."
The agent later wrote its own fix to MEMORY.md: "show the plan, get explicit approval, then execute. No autonomous bulk operations." Good rule. Too late.
| Layer | What it is | Durability |
|---|
|-------|-----------|-----------|
| Bootstrap files (SOUL.md, AGENTS.md, USER.md, MEMORY.md, TOOLS.md) | Loaded from disk at session start | **Permanent — survives everything** |
|---|---|---|
| Session transcript (JSONL on disk) | Conversation history rebuilt each turn | Semi-permanent — compacted when context fills |
| LLM context window | What the model actually "sees" right now | Temporary — fixed 200K token bucket |
| Retrieval index (memory_search) | Searchable index over memory files | Permanent — rebuilt from files |
Key insight: Bootstrap files survive compaction because they're re-read from disk at every turn, not from conversation history.
Failure A — "It was never stored."
Most common. Instruction only existed in conversation. Never written to file. Gone on compaction or new session. This is the Summer Yue failure.
Failure B — "Compaction changed what's in context."
Context hit the token limit. Compaction summarized old messages — lossy summary dropped your specific constraints and nuance.
Failure C — "Session pruning trimmed tool results."
Tool outputs (file reads, web results) were trimmed per-request. Temporary — on-disk transcript is untouched. Model just can't see the old result for this request.
Quick diagnostic:
#### Layer 1: Pre-Compaction Memory Flush Config
Add this to OpenClaw config (~/.openclaw/clawdbot.json or equivalent):
{
"agents": {
"defaults": {
"compaction": {
"reserveTokensFloor": 40000,
"memoryFlush": {
"enabled": true,
"softThresholdTokens": 4000,
"systemPrompt": "Session nearing compaction. Store durable memories now.",
"prompt": "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
}
}
}
}
}
Why 40000? Default is 20K — too tight. With 200K context: 200K - 40K reserve - 4K soft threshold = flush triggers at 156K tokens. Gives the flush room to actually fire before overflow.
Why NO_REPLY? Suppresses the flush turn from being delivered to the user. It's silent.
#### Layer 2: Manual Memory Discipline
#### Layer 3: File Architecture
Bootstrap files (injected every session):
Memory directory (on-demand via search):
Sub-agent caveat: Sub-agents only get AGENTS.md + TOOLS.md. NOT SOUL.md, USER.md, MEMORY.md. Personality and Trevor's personal context are invisible to sub-agents unless explicitly passed.
## Memory Protocol
- Before answering questions about past work: search memory first
- Before starting any new task: check memory/[today's date] for active context
- When you learn something important: write it to the appropriate file immediately
- When corrected on a mistake: add the correction as a rule to MEMORY.md
- When a session is ending or context is large: summarize to memory/YYYY-MM-DD.md
## Retrieval Protocol
Before doing non-trivial work:
1. memory_search for the project/topic/user preference
2. memory_get the referenced file chunk if needed
3. Then proceed with the task
Run this in OpenClaw to see what's actually loaded. Watch for:
Limits to tune if needed:
Compaction bugs fixed in late Feb 2026. Must be on v2026.2.23 or later.
openclaw --version