Context 不是聊天记录

理解消息投影、自动 compaction、保留尾部与分支摘要如何共同塑造模型看到的世界。

Session 保存历史，Context 选择现在

三次选择

模型请求之前，信息至少经过三次选择：

1. 分支选择：session tree 的 active leaf 决定哪条历史路径有效。
2. 压缩选择：compaction 用 summary 代表较老历史，并保留近期消息。
3. 模型选择：transformContext() 可裁剪/注入，convertToLlm() 过滤 UI-only 自定义消息。

自动 Compaction

触发条件可简化为：

contextTokens > contextWindow - reserveTokens

默认 reserveTokens 为 16,384，keepRecentTokens 为 20,000。流程从最新消息向前选择保留尾部，在有效边界切分旧消息，生成结构化摘要，再追加 CompactionEntry。

摘要格式并非自由散文，而是 Goal、Constraints、Progress、Decisions、Next Steps、Critical Context 等工程交接结构。工具结果在送去摘要前截断到 2,000 字符，避免大段 shell/read 输出吞噬预算。

Branch Summary 不等于 Compaction

二者都记录文件操作并可由 extension hook 替换，但语义不同：一个处理“太长”，一个处理“走过但离开”。

Context Engineering 的真正目标

不是把尽可能多的信息塞给模型，而是让当前决策需要的事实，稳定地出现在有限窗口内。常见策略包括：

• 把不变约束放进 AGENTS.md / system prompt。
• 把可恢复事实放进 session entries。
• 把长历史压缩成结构化 checkpoint。
• 把 UI-only 状态过滤在 provider 边界之外。
• 把大工具输出存为文件，只在 context 中保留定位与结论。

Trade-off

更多历史提高连续性，也提高成本与注意力噪声；更激进压缩降低成本，也可能丢失隐含决策。Pi 提供默认策略与 extension hooks，但不能替项目判断“什么最重要”。