name: openclaw-memory-resilience description: "Configure OpenClaw agent memory to survive compaction and session restarts. Use when: (1) setting up a new OpenClaw agent or workspace, (2) agents are forgetting instructions or context between sessions, (3) configuring the pre-compaction memory flush, (4) setting up the file archival pattern for memory/archive/, (5) diagnosing why an agent forgot something, or (6) tuning compaction headroom and context pruning. Covers Layer 1 (gateway compaction config) and Layer 3 (file architecture) of the three-layer memory defense."

OpenClaw Memory Resilience

Covers the two highest-impact layers of memory durability for OpenClaw agents.

The Four Memory Layers (quick reference)

Core rule: If it's not written to a file, it doesn't exist after compaction.

Three Failure Modes

• Failure A — Instruction only existed in conversation, never written to a file. Most common.
• Failure B — Compaction summarized it away. Lossy. Nuance lost.
• Failure C — Session pruning trimmed old tool results. Temporary, lossless.

Diagnostic: Forgot a preference? → Failure A. Forgot what a tool returned? → Failure C. Forgot the whole thread? → Failure B.

Layer 1: Gateway Compaction Config

Apply via gateway config.patch. This is a global default — applies to all agents:

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "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."
        }
      },
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "1h"
      }
    }
  }
}

See references/config-explained.md for why each value is set the way it is.

Layer 3: File Architecture

See references/file-architecture.md for the full pattern — bootstrap files, daily notes, archival, and QMD indexing.

Context Footer Standard

Add to every agent's SOUL.md. This gives you real-time visibility into context fill and compaction count — the single fastest way to know when to act before you hit the bad compaction path.

## Context Management (Auto-Applied)
**Every response:** fetch live status via `session_status`, append footer: `🧠 [used]/[total] ([%]) | 🧹 [compactions]`
- Auto-clear: **85% context** OR **6 compactions**
- Warn: **70% context** OR **4 compactions**
- Before clearing: file critical info to memory, then reset

See references/context-footer.md for why this matters and how to tune the thresholds.

Diagnosing Problems

Run /context list in any OpenClaw session to see:

• Which bootstrap files loaded and at what size
• Whether any files are TRUNCATED (over per-file limit)
• Total injected chars vs raw chars

If a file shows TRUNCATED: reduce it or raise bootstrapMaxChars in config. If a file is missing entirely: check the workspace path in agent config.