$ cat ~/map/pi-memento.md

pi-memento

嵌套上下文事务扩展：探索可提交、压缩、合并或回退，而不改写会话历史。

extensions✓ 10月16日

./bin/memento

## 速览

实验性 pi 扩展，在 agent 自身的模型可见上下文上引入显式嵌套事务——对一段探索可以 commit、compact、squash 或 revert，而会话历史本身从不被改写。

## 要点

• $把上下文轴与执行轴解耦：子代理要获得干净的调用方上下文，必须开新循环并提前定好边界；pi-memento 在同一个 agent 循环内单独交付上下文效果——粒度任意、位置任意、事后再决定去留。
• $注册三个工具：transaction_begin（可带 purpose）、transaction_end（disposition 加可选 result 与 carryforward）和只读的 transaction_status；begin 与 end 必须各自独占一条助手消息，end 总是关闭最内层打开的事务（LIFO）。
• $四种处置：commit 原样保留正文、compact 用模型生成的摘要替换（唯一会调用模型的处置）、squash 用 agent 自己写的 result 字符串替换、revert 整段移除但必须留下非空的 carryforward 教训。
• $投影只是对规范历史的一个视图，后者始终保持追加式 JSONL——事务从不改写已发生的事，也回滚不了世界：写过的文件、跑过的命令和其他副作用一律保留。
• $压缩感知事务：切割点落在事务边界上、打开的事务完整保留在留存尾部，边界或元数据不一致时直接失败而非回退到原始历史。
• $明确的非目标：不做文件系统、shell 或进程回滚，不做 VM 与容器快照，不做数据库事务，不做分布式 agent 记忆，也不做语义搜索或自动长期记忆管理。
• $以插件形式经项目本地的锁定版 pi 运行：npm install 拉取锁定的 @earendil-works/pi-coding-agent，npm run build 编译扩展到 dist/，./bin/memento 启动这份锁定的二进制——全局安装的 pi 不受影响。

## 常见问题

## 参考链接

• README ↗
• pi 集成契约 ↗

最后更新: 2026年8月31日