OpenClaw Context Memory Optimizer v3.1

Source-verified · ClawHub-safe · Transparent path declarations

Compaction logic verified against claw-code open-source port (compact.rs).
v2.0 turn-count trigger has been corrected to token-count trigger.
All file paths and persistent changes are declared in the frontmatter above.

Core Principles

1. Memory as Pointers 记忆是指针

MEMORY.md stores locations, not content. Keeps the always-loaded index under 800 tokens regardless of project size.

2. Skeptical Memory 怀疑型记忆

Agent treats its own memory as a hint, not ground truth. Always cross-verify against source files before any write or bash action. Prevents stale-memory bugs in long sessions.

3. Token-Driven Compaction Token 驱动压缩

Trigger is token volume, not turn count. Formula: total_chars ÷ 4. Source: compact.rs → estimate_session_tokens().

4. Immediate Post-Compact Restore 压缩后立即恢复

Key files are re-injected right after compaction so the agent never "forgets what it was doing." Source: Claude Code post-compact file restore.

5. Circuit Breaker 熔断保护

Stop retrying after 3 consecutive compaction failures. Prevents the real-world incident where one session wasted 250k API calls/day. Source: Claude Code BigQuery incident note in source comments.

Step 1: Workspace Setup 工作区结构

CODEBLOCK0

MEMORY.md template — each line ≤ 150 chars, full file ≤ 800 tokens:

CODEBLOCK1

Privacy note 隐私提示: Add memories/ to .gitignore if your
.openclaw/ directory is synced to Git.

Step 2: Verification-First Instructions 验证优先指令

Add the following to the static section of your agent's system prompt.
Label it clearly so you know what it does:

CODEBLOCK2

Step 3: Token-Driven Compaction 压缩分层

Token estimation formula (from compact.rs estimate_session_tokens):
CODEBLOCK3

L1 — Tool Output Soft Trim 工具输出软截断

Runs automatically after every tool call. No user action needed.

- bash / read / search output > 2,000 chars:

keep last 500 chars + one-line conclusion

- File reads > 3,000 chars:

extract key paragraphs, append [trimmed — full content at {path}]

- Keep the 8 most recent tool records; summarize earlier ones to one line each

L2 — Session Compaction 会话压缩

Trigger: estimated tokens > 150,000

Run these steps in order. Do not skip or reorder.

CODEBLOCK4

L3 — Key File Restore 关键文件恢复

Runs immediately after every L2 compaction.

Read in this order:

1. MEMORY.md — reload the pointer index
INLINECODE10 — most important: current task snapshot
Up to 5 files from Step ② — limit each to 1,000 tokens

After reading, resume the task. Do not tell the user "I have restored X files."

L4 — Circuit Breaker 熔断器

CODEBLOCK5

L5 — Emergency Trim 紧急裁剪

Trigger: context_length_exceeded error

CODEBLOCK6

Step 4: Multi-Agent Coordination 多 Agent 协作

AGENTS.md template

CODEBLOCK7

Prompt Cache Protection 缓存保护

Structure your agent's system prompt in two sections, in this order:

CODEBLOCK8

Do not insert timestamps, summaries, or task descriptions into the middle
of the static section. Doing so invalidates the prefix cache and re-bills
the full static section on every turn.

Step 5: Speculative Pre-warming 推测预热（optional）

Add to your agent's system prompt (static section, after the memory rules):

CODEBLOCK9

Deployment Checklist 部署验证清单

- [ ] MEMORY.md exists and is ≤ 800 tokens
[ ] memories/ contains: project.md, decisions.md, errors.md, context.md
[ ] Step 2 snippet is in the static section of the agent system prompt
[ ] Dynamic content is after INLINECODE13
[ ] Manually trigger one L2 compaction to verify the continuation message format
[ ] Multi-agent handoffs use the XML format from AGENTS.md
[ ] memories/ is in .gitignore (if workspace is Git-synced)

References

- references/compression-examples.md — before/after compaction examples,

key file extraction walkthrough, project fingerprint format

- references/prompt-cache.md — prompt cache segmentation strategy,

common mistakes, cost estimation

OpenClaw Context Memory Optimizer v3.1

来源已验证 · ClawHub安全 · 透明路径声明

压缩逻辑已对照 claw-code 开源端口 (compact.rs) 验证。
v2.0 的回合数触发已修正为 Token 数触发。
所有文件路径和持久化更改均已在上方 frontmatter 中声明。

核心原则

1. 记忆是指针

MEMORY.md 存储的是位置，而非内容。无论项目规模多大，始终将常驻加载的索引保持在 800 Token 以内。

2. 怀疑型记忆

智能体将自身记忆视为线索，而非事实依据。在执行任何写入或 bash 操作前，务必与源文件交叉验证。防止长会话中出现记忆过时错误。

3. Token 驱动压缩

触发条件是 Token 量，而非回合数。公式：总字符数 ÷ 4。来源：compact.rs → estimatesessiontokens()。

4. 压缩后立即恢复

压缩后立即重新注入关键文件，确保智能体不会忘记正在做什么。来源：Claude Code 压缩后文件恢复机制。

5. 熔断保护

连续 3 次压缩失败后停止重试。防止真实案例中单个会话每天浪费 25 万次 API 调用。来源：Claude Code BigQuery 事件记录（源注释中）。

步骤 1：工作区结构

~/.openclaw/workspace-{agent}/
├── MEMORY.md # 始终加载。仅含指针。保持 ≤ 800 Token。
├── memories/
│ ├── project.md # 技术栈 + 项目指纹 + 模块清单
│ ├── decisions.md # 决策日志——记录为什么，而非是什么
│ ├── errors.md # 权限拒绝/错误路径记录（仅追加）
│ └── context.md # 当前任务快照——每次 L2 前覆盖
└── AGENTS.md # 多智能体角色与协调规则

MEMORY.md 模板——每行 ≤ 150 字符，完整文件 ≤ 800 Token：

markdown

记忆索引

每条记录是指向文件的指针，而非文件内容的副本。

更新于：{时间戳} | Token 估算：{会话字符数 ÷ 4}

当前项目

- 名称：{名称} | 详情 → memories/project.md

活跃任务

- {任务描述 ≤ 50 字符} | 状态：进行中 | 详情 → memories/context.md

关键约束

- {约束 ≤ 30 字符}

步骤 2：验证优先指令

将以下内容添加到智能体系统提示的静态部分。清晰标注其用途：

记忆完整性规则

来源：context-memory-optimizer 技能，步骤 2

目的：防止记忆过时错误和重复的权限错误

1. MEMORY.md 是线索，非事实依据。

在执行任何写入或 bash 操作前，读取相关源文件进行验证。不要仅凭记忆摘要行事。

2. 在操作前检查 memories/errors.md。

不要重试之前导致 PermissionDenied 的操作。不要重复使用之前返回 FileNotFound 的路径。

3. 当记忆与源文件矛盾时：

→ 信任源文件 → 更新相关 MEMORY.md 指针条目 → 在 memories/errors.md 中追加一行描述不一致之处

步骤 3：Token 驱动压缩

Token 估算公式（来自 compact.rs 的 estimatesessiontokens）：

每条消息：
文本块 → 字符数 ÷ 4 + 1
工具使用 → (名称长度 + 输入长度) ÷ 4 + 1
工具结果 → (名称长度 + 输出长度) ÷ 4 + 1
总计 → 所有消息之和

L1 — 工具输出软截断

每次工具调用后自动运行。无需用户操作。

- bash / read / search 输出 > 2,000 字符：

保留最后 500 字符 + 单行结论

- 文件读取 > 3,000 字符：

提取关键段落，追加 [已截断——完整内容位于 {路径}]

- 保留最近 8 条工具记录；将较早的记录汇总为每行一条

L2 — 会话压缩

触发条件：估算 Token > 150,000

按顺序执行以下步骤。不得跳过或重排。

步骤 ① — 扫描待办工作关键词
在最近消息中搜索包含以下关键词的句子（不区分大小写）：
todo / next / pending / follow up / remaining
收集匹配的句子以纳入摘要。
来源：compact.rs → inferpendingwork()

步骤 ② — 提取关键文件路径
扫描所有消息内容，查找满足以下条件的 Token：
- 包含正斜杠 /
- 以以下扩展名结尾：.md .json .py .ts .js .rs .yaml .toml
去重。最多保留 8 个路径。
来源：compact.rs → collectkeyfiles()

步骤 ③ — 生成摘要
格式：

- 已完成：{已完成工作的项目符号列表}
- 待办： {步骤 ① 的输出}
- 关键文件：{步骤 ② 的输出}
- 当前任务：{最近非空消息的前 200 字符}

插入前移除所有块。
来源：compact.rs → formatcompactsummary()

步骤 ④ — 注入延续消息
使用以下精确文本。不得改写。
──────────────────────────────────────────────────────────────
以下是本会话前半部分的摘要。
请直接从对话中断处继续。
不要确认此摘要。不要回顾。不要提问。
立即恢复任务。

摘要：
{步骤 ③ 的输出}
──────────────────────────────────────────────────────────────
来源：compact.rs → getcompactcontinuationmessage(suppressfollow_up=true)

步骤 ⑤ — 丢弃旧消息
保留：延续消息（步骤 ④）+ 最近 4 条消息。
丢弃其余所有内容。
来源：compact.rs → preserverecentmessages 默认值 = 4

步骤 ⑥ — 立即运行 L3（见下文）

L3 — 关键文件恢复

每次 L2 压缩后立即运行。

按以下顺序读取：

1. MEMORY.md — 重新加载指针索引
memories/context.md — 最重要：当前任务快照
步骤 ② 中的最多 5 个文件 — 每个限制为 1,000 Token

读取后，恢复任务。不要告诉用户我已恢复 X 个文件。

L4 — 熔断器

如果 L2 压缩连续失败 3 次：
→ 停止重试 L2
→ 仅回退到 L1 软截断
→ 将失败原因追加到 memories/errors.md
→ 等待操作员手动清除并重启

原因：某个真实会话曾连续失败 L2 压缩 3,272 次，
在添加熔断器前每天浪费 25 万次 API 调用。
来源：Claude Code 内部 BigQuery 事件记录。

L5 — 紧急裁剪

触发条件：contextlengthexceeded 错误

1. 将最后一条助手消息的结论写入 memories/context.md

（这是紧急裁剪期间唯一执行的写入操作）

2. 丢弃最旧的 2 轮对话
重复直到错误清除

context-memory-optimizer上下文记忆优化

context-memory-optimizer

OpenClaw Context Memory Optimizer v3.1

Core Principles

Step 1: Workspace Setup 工作区结构

Step 2: Verification-First Instructions 验证优先指令