Skill.md
Compact Memory 实现指南
Agent 在长会话中面临一个根本性问题：对话历史随轮次无限增长，但模型的 context window 有固定上限。一旦超限，要么截断历史（丢失关键上下文），要么会话崩溃。这个 skill 给出了一套完整的工程实现方案：在 context 接近上限时，自动派生一个 compactor sub-agent 执行压缩，将压缩结果注入下轮的 system prompt，跨会话持久化。
适用于使用 Anthropic API（Python/TypeScript SDK）或 Claude Agent SDK 开发 Agent 的工程师。
7 步实现框架
| 步骤 | 内容 |
|---|---|
| Step 1 | 确认架构：SDK、agent 模式、session 模型 |
| Step 2 | 触发时机：token 阈值 / turn 计数 / 阶段边界三种策略 |
| Step 3 | Fork compactor：独立 API 调用，用 Haiku 模型，主 agent 同步等待 |
| Step 4 | compact 输出 schema：task、current_state、key_decisions、eliminated_approaches、next_steps |
| Step 5 | 记忆恢复：system prompt 注入（推荐）或 first-message 注入 |
| Step 6 | 完整 agent 循环：含触发、压缩、持久化、恢复的完整代码 |
| Step 7 | 链式 compact：多次会话的 compact 合并更新，避免堆积 |
为什么 Fork 而不是自我压缩
主 agent 在长时间运行后焦点容易漂移——它沉浸在当前任务的细节里，很难站出来做全局总结。独立的 compactor 从零开始读全量历史，产出更准确的摘要。同时，compaction 是总结任务，用 Haiku 足够，节省下来的额度用于主 agent 的执行工作。
支持的使用场景
- 构建需要跨会话保持状态的研究型 / 执行型 Agent
- Agent 会话长度不可预测，需要自动管理 context，不能手动介入
- 中间决策、放弃的方案、工具调用结果不能在压缩中丢失
- 需要 compact 在多次会话后仍然准确（链式更新模式）
常见陷阱对照表
| 陷阱 | 解决方法 |
|---|---|
| compact 丢失后续步骤需要的工具结果 | 把关键结果摘要写入 relevant_tool_results |
| 新会话忽略 compact | 注入 system prompt，不要放在 messages 里 |
| compactor 用了昂贵模型 | 用 Haiku 做压缩，Opus 做主工作 |
| compact 跨会话无限增大 | 用链式 compact 合并更新，不要堆叠 |
| compact JSON 解析失败崩溃 | 加重试机制 + 降级 compact 兜底 |
局限说明
这个 skill 提供的是实现框架和代码模板，不是一个可以直接运行的库。compact 输出质量依赖 compactor 的提示词设计——如果 compactor system prompt 指令不清晰，生成的摘要可能遗漏关键上下文。建议在开发阶段手动验证前几次 compact 的输出质量，再投入生产。