pi-echo

pi ────))) echo — 原声过去之后，回声还在。

面向 Pi Coding Agent 的长期记忆扩展。Pi 把旧对话收成摘要；pi-echo 提醒模型哪些历史值得回看，并让模型按需找到原始证据。

它交付什么

长会话压缩（compaction）后，目标和进度通常还在摘要里，当时的命令输出、失败现场和用户原话却可能已离开模型上下文。pi-echo 保留 Pi 的摘要流程，通过三种结果补充证据：

结果	模型得到什么
Memory Cues（自动提醒）	成功压缩后值得回看的工具过程，一行说明一次事件
Search Results（搜索结果）	当前路径中的来源说明、命中位置和原文片段
Retrieved Content（找回内容）	从指定来源行开始的连续原文，未读完时可继续

搜索片段已经足够时，模型可以直接回答；缺少条件或上下文时，再找回完整内容。

🧩 来源线索与自动提醒

一条来源线索包含时间、角色、简短内容和不透明凭据 handle。凭据用于打开对应原文，模型无需解析它。

09-03 09:04 toolResult bash(npm test) → ✗ 3 failed: budget over limit [3 lines, 1 issue]
09-03 09:00 user 帮我修一下预算校验的越界问题

工具过程线索说明做了什么、得到什么，以及背后还有多少内容。超长成分保留首尾，用省略标记说明中段未展示；原文仍可找回。

自动提醒只展示工具执行过程。用户消息、模型正文和带 thinking 标记的历史思考也进入可搜索的来源目录，但不进入自动提醒。当前目标与结论继续由 Pi 上下文和摘要承接。

🌱 提醒会淡去，原文仍可查

每次成功压缩后，新工具过程线索完整进入一批提醒，旧线索按年龄变模糊或退出：

完整提醒 → 仅保留调用说明与内容规模 → 退出提醒，仍可搜索和找回

能够重新取得等价内容的线索衰减较快；记录当时执行状态的线索保留较久，失败点最慢。文件被修改后，此前的读取记录按不可重现内容处理。

模型找回仍在提醒中的事实时，该行在下一次压缩后恢复清晰并受保护一批。已经退出提醒的事实继续可查、可取，不重新进入自动提醒。

系统以模型窗口的 20% 作为压力参考：超出时加快未受保护旧行的衰减。本批新行和刚强化的行始终完整交付，即使它们自身超过参考量。因此，20% 不是提醒体积上限。具体机制见 Cue Provider 设计。

🔍 搜索与找回

模型可使用两个工具：

search_memory({ query, match, in, after })
recall_memory({ handle, from })

选择怎样搜索

参数	行为
query	同时搜索当前路径的来源线索与完整原文，包括当前提醒之外的历史
match: "literal"（默认）	忽略大小写的逐行字面子串匹配；.* 等字符也按原样匹配
match: "terms"	将查询拆成词项，按 BM25 相关性排序；适合记得几个词却不记得原句的情况
in 加非空 query	只搜索该凭据对应的完整事实，两种匹配方式均可使用
不填 query 和 in	分页列出来源线索

例如，精确定位 budget.*校验 可用 literal；只记得 budget rollback validation 这些词时可用 terms。词项搜索不是自然语言理解，也不保证每个查询词都出现。

读懂证据与续取位置

每项搜索结果都带来源说明；命中原文时，还会给出命中行、原文片段范围和所属小节范围。片段没有覆盖整个小节时，可以用 recall_memory 从小节起点补读。标题和来源说明不占原文行号。

非空查询优先显示已离开 Pi 原生上下文的历史，再显示仍保留的内容。historical、retained、unknown 表示上下文保留状态，不表示内容真伪。thinking 标记当时的推演，也不等于已核实结论。

搜索结果给出续页标记时，沿用原来的 query、match 和 in，添加 after 继续。续页保持首次查询的排序与片段边界；期间追加的新事实需要重新搜索才会进入结果。续页标记失效时，去掉 after 重新开始。

recall_memory 使用 handle 找回原文，from 是从 1 开始的来源行号。每段都带来源说明和实际范围；一行不会从中间切开，未读完时给出下一起点。工具结果连同配对调用交付，图片保持图片，思考保留来源标记。

🌿 范围与失败隔离

记忆权限来自当前 Pi 会话（session）的完整分支路径。搜索参数不能扩大范围，分支摘要（branch summary）也不会授权读取被放弃分支的原文。

正常追加与压缩保留历史可达性；捕获到历史消息修订时撤销旧快照。导航、会话替换和扩展重载（reload）会建立新运行范围，已经失效的工具结果不会交付。

线索准备、检索或找回失败时，Pi 的上下文、压缩、任务和关闭流程继续运行。工具会区分没有匹配、参数需要纠正和暂时不可用，不把计算失败当成没有历史。

安装

pi install npm:pi-echo

只在当前运行中试用：

pi -e npm:pi-echo

安装后无需配置。第一次成功压缩且模型上下文缺少当前路径历史时，普通请求会带上工具过程提醒。重新打开已压缩路径时，扩展重建基线；模型也可随时按需搜索和找回。

开发与验证

需要 Node.js 22.19.0 或更高版本。

npm ci
npm test        # 静态、模块行为与跨模块集成检查
npm run test:pi # 真实 Pi、本地确定性 provider

真实模型检查会发送实际请求。先在 Pi 中登录，检查会复用 Pi 当前配置目录中的凭证：

npm run setup:model # 报告环境状态
npm run test:model  # 真实模型验收

检查产物位于 .dev/verification/。模型记录包含原始请求、输出、耗时与 token 用量；其中费用是 Pi 根据模型目录价格计算的估算，不是实际账单。检查层次、固定模型与结果分类见 Verification。

在真实 Pi 中加载当前仓库实现：

npx pi -e ./index.ts

架构与文档

文档入口连接系统设计和各模块设计。本文说明当前用法；设计文档负责目标、契约与机制。存在未完成的交付目标时，文档入口会列出当前开发计划。

许可证

Apache-2.0，见 LICENSE。