概念

Memory 系統解決一個核心問題：LLM 的 context window 有限。

對話越長，context 越大，最終會超出限制。OpenClaw 用兩種機制處理：

Compaction：把舊對話「壓縮」成摘要
Memory Flush：在壓縮前提醒 agent 存檔

Context Window 限制

模型	Context Window
Claude Opus 4.5	200K tokens
Claude Sonnet 4.5	200K tokens
GPT-5.2	128K tokens

當 session 歷史接近這個限制，OpenClaw 會觸發 compaction。

Compaction 流程

Session 歷史快滿了
        ↓
觸發 Memory Flush（可選）
        ↓
Agent 把重要資訊寫入檔案
        ↓
Compaction 開始
        ↓
舊訊息被「摘要」成一段文字
        ↓
新的 context = 摘要 + 最近訊息

核心代碼

1. Auto-Compaction 觸發

async function checkCompaction(session, model) {
  const contextWindow = model.contextWindow;  // e.g., 200000
  const reserve = config.compaction.reserveTokens;  // e.g., 10000
  
  const currentTokens = countTokens(session.history);
  
  if (currentTokens > contextWindow - reserve) {
    // 需要 compaction
    await runCompaction(session);
  }
}

2. Memory Flush（壓縮前通知）

// 在 compaction 之前，給 agent 一次機會存檔
async function memoryFlush(session) {
  const flushPrompt = `
Pre-compaction memory flush. Store durable memories now 
(use memory/YYYY-MM-DD.md; create memory/ if needed). 
If nothing to store, reply with NO_REPLY.
`;
  
  // 執行一個 silent turn
  await runAgentTurn(session, flushPrompt, {
    silent: true,  // 不發送給用戶
    allowTools: ['read', 'write', 'edit']
  });
}

為什麼需要 memory flush？

Compaction 會「遺忘」細節
給 agent 機會把重要資訊寫入永久檔案
例如：今天的決策、重要事件、待辦事項

3. Compaction 執行

async function runCompaction(session) {
  const history = session.history;
  
  // 1. 找出要壓縮的部分（保留最近 N 則）
  const keepRecent = 20;
  const toCompress = history.slice(0, -keepRecent);
  const toKeep = history.slice(-keepRecent);
  
  // 2. 用 LLM 產生摘要
  const summary = await llm.summarize(toCompress, {
    maxTokens: 2000,
    prompt: "Summarize the key decisions, facts, and context from this conversation."
  });
  
  // 3. 替換歷史
  session.history = [
    { role: 'system', content: `Previous conversation summary:\n${summary}` },
    ...toKeep
  ];
  
  // 4. 持久化到 JSONL
  await saveSession(session);
}

4. 設定

// openclaw.json
{
  "agents": {
    "defaults": {
      "compaction": {
        "enabled": true,
        "mode": "safeguard",      // 或 "aggressive"
        "reserveTokens": 10000,
        "memoryFlush": true       // 啟用 memory flush
      }
    }
  }
}

Compaction 模式：

safeguard：保守，保留更多歷史
aggressive：積極壓縮，節省 context

Session Pruning vs Compaction

特性	Compaction	Session Pruning
對象	整個對話歷史	只有 tool results
永久性	寫入 JSONL	僅 in-memory
時機	context 快滿	每次 LLM 呼叫前

// Session pruning：清理舊的工具結果
function pruneToolResults(history) {
  return history.map(msg => {
    if (msg.role === 'tool' && msg.age > 5) {
      // 舊的工具結果只保留摘要
      return { ...msg, content: '[pruned]' };
    }
    return msg;
  });
}

💡 關鍵洞察

Compaction 是有損的
- 摘要會丟失細節
- 所以 memory flush 很重要
- 重要資訊要寫入檔案
Memory Flush 是「最後機會」
- 在 compaction 前觸發
- Agent 可以存檔
- 回覆 NO_REPLY 表示沒東西存
檔案比 context 更持久
- memory/YYYY-MM-DD.md = 日誌
- MEMORY.md = 長期記憶
- TOOLS.md = 工具筆記
- 這些不會被 compaction
手動 compaction
- 用 /compact 命令
- 可以加指示：/compact Focus on decisions

🔗 核心檔案

Compaction 文檔：/opt/homebrew/lib/node_modules/openclaw/docs/concepts/compaction.md
Memory 文檔：/opt/homebrew/lib/node_modules/openclaw/docs/concepts/memory.md
Session 儲存：~/.openclaw/agents/<agentId>/sessions/

明天： Config 系統（openclaw.json, agents, bindings）

Day 7: Memory 系統（compaction, memory-flush）