让 Pi agent 主动把已经消化完的过程移出当前上下文，需要时再完整找回——长任务不再越聊越钝。
你让 agent 做一个长任务——比如修一个难缠的 bug，或者做一次跨十几个文件的重构。做着做着你会发现它变钝了：回答变慢、开始忘事、偶尔重复已经做过的操作。
原因很简单：对话历史越堆越长。里面大部分是"过程"——读过的日志、走过的弯路、早就修完的报错。这些东西任务早就消化完了，但每次回复模型都要重新看一遍全部历史。历史越长，注意力越稀，费用越高。
Pi 自带 compaction 兜底：接近窗口上限时，把旧历史在模型的当前上下文里换成一段摘要。原始记录仍在会话文件里，你可以手动用 /tree 回看。但整理的时机和边界由 host 决定，而且 agent 自己没有工具去搜索旧历史、取回被压掉的细节——摘要漏了什么，它就真的忘了。
pi-context 把这套能力直接交给 agent：它像人整理办公桌一样，自己判断哪段过程已经消化完，把它收进抽屉，桌面上只留一张简短的交接单；之后随时可以搜索抽屉里的东西，需要哪个细节就回去取。
一句话：Pi 原生 compaction 是 host 驱动的单向摘要；pi-context 是 agent 自主、可回溯的收纳。
pi install git:github.com/KorenKrita/pi-context或者在仓库目录里本地安装：
pi install .也可以不安装、临时加载试用：
pi -e /path/to/pi-context/src/index.ts兼容性： 当前版本针对 Pi（
@earendil-works/pi-coding-agent）0.84.0开发并完成集成验证，要求 Node.js>=22.19.0。其它 Pi 版本未经验证；升级 Pi 后如遇报错，请先核对版本。本 fork 只发布在 GitHub。npm 上未带 scope 的
pi-context是上游项目，不要用npm install装这个 fork。
不需要你做任何事。agent 拿到三个新工具，会在合适的时机自己用：
| 工具 | 干什么 |
|---|---|
acm_checkpoint |
存档。给当前对话位置起个名字，之后随时能回来。 |
acm_timeline |
地图。查看对话主干和所有存档点，搜索整棵历史树——包括已经收起来的部分。 |
acm_travel |
移动。回到树里的另一个位置：既用于折叠（回到早处、把之后的过程换成交接单），也用于取回（回到收起来的原文分支）。原文永不删除。 |
比如你让 agent 排查一次性能回退：
- 开始翻日志前，它先给当前位置存个档，叫
perf-baseline。 - 排查完，它已经能明确说出"数据库已排除、重试循环是嫌疑、下一步读哪个文件"——于是折叠回
perf-baseline，把几十条搜索和日志输出换成这份结论，轻装继续。 - 之后如果需要某个被折掉的配置值，它先搜时间线；要完整前情时，凭自动留下的"回程票"travel 回原文分支。
全程你的文件和 Git 状态一动不动，变的只是之后发给模型的对话上下文。
你还能观察到：普通工具结果末尾多了一行小字，形如 [ctx 43% window · 86K/200K · …]——这是上下文压力仪表，只报数字，不催促。设 ACM_GAUGE_DISABLED=1 可以关掉。你也可以直接下指令："存个档"、"看看时间线"、"回到刚才那个点"。
每次折叠，agent 都要写一份交接单（handoff），写给"折叠之后的自己"：目标是什么、现在到哪了、下一步干什么——必要时还有证据在哪、改过哪些文件、放弃过哪些方向。合格标准只有一条：一个完全不知道前情的新 agent，只看这张单子就能无缝接着干。 写不出这样的单子，说明这段过程还没消化完，就不该折。
同时，每次折叠都自动留一张"回程票"：折叠前的位置被记名存档，写进交接单里。想找回任何被折掉的细节，一次 travel 就回去了。
- 折叠和回溯只改对话上下文，不会回滚文件、进程、Git 提交或任何外部系统。存档点是对话位置的书签，不是文件备份。
- 折叠永远可逆：原始历史完整留在会话树里。
- 不取消、不替换 Pi 原生 compaction——真正超长的任务照样有原生机制兜底。
- 每次操作都返回可核对的事实回执；不确定的结果如实标注，不伪装成功。
- 扩展默认会往本地
~/.pi/agent/state/acm-boundary-ledger.jsonl追加匿名运行计数（时间、压力百分比、消息与存档点数量），用于观察折叠是否发生。不含任何对话正文，文件上限 8 MiB，不上传。设ACM_LEDGER_DISABLED=1可完全关闭。
npm ci --ignore-scripts
bun run verify:acm # 生成物一致性 + 全部测试 + 类型检查 + 真实 Pi host fixture架构、host 兼容性契约、文案规则见 AGENTS.md。
- pi-context — 原项目，作者 ttttmr
- 让 AI 主动管理自己的上下文 — 设计思路
MIT License