pi-session-history

English | 中文

无需离开 Agent，即可搜索、查看并恢复历史 Pi 编程会话。

安装后可以直接对 Pi 说：

搜索我之前关于“数据库迁移”的会话，然后打开最相关的结果。

Agent 会调用只读的 pi_history Tool，搜索 Pi 本地 JSONL 会话存储，并按范围读取规范化后的转录。交互用户也可以运行 /history，预览、交给 Agent 分析或恢复某个会话。

为什么需要它

Pi 的本地会话文件保存了技术决策、失败尝试、工具输出和实现上下文。内置会话选择器适合恢复一个已知会话，但 Agent 本身不能把历史会话作为可检索材料。pi-session-history 用一个有界、只读的 Tool 补上这条路径。

提供的能力

• 跨项目词法搜索，或只筛选当前工作目录。
• 通过 @letta-ai/trajectory 规范化消息、推理、工具调用和工具结果。
• 按规范化记录分页读取转录。
• 默认排除当前活动会话，避免搜索命中自身。
• /history 交互选择器，支持预览、交给 Agent 和恢复会话。
• 不建立索引、不收集遥测，也不通过网络传输会话内容。

环境要求

• Pi 0.80.10 或兼容的更高版本。CI 中的宿主包固定为 0.80.10。
• Node.js 22 或更高版本。Pi 0.80.10 打包的运行时依赖无法在 Node.js 20 上可靠加载。

安装

npm

pi install npm:pi-session-history

Git

pi install git:github.com/yoyooyooo/pi-session-history

本地源码

git clone https://github.com/yoyooyooo/pi-session-history.git
cd pi-session-history
npm install
pi install .

安装后重启 Pi，或运行 /reload。

快速开始

1. 安装并重载插件。

2. 对 Pi 说：

   查找我之前关于缓存失效的 Pi 会话，并总结里面的关键决策。

3. Agent 应先用 action: "search" 调用 pi_history，再使用返回的精确路径调用 action: "read"。

4. 成功的搜索结果包含会话标题、路径、工作目录、更新时间、命中摘录和分页信息。

直接交互使用：

/history
/history 缓存失效

不修改 Pi 设置的临时加载验证：

pi --no-extensions -e . --list-models

Agent Tool

本包注册一个 Tool：

pi_history

它支持三个 action。

Search

{
  "action": "search",
  "query": "database migration",
  "limit": 10
}

搜索不区分大小写，采用词法匹配。空白分隔的查询词使用 AND 语义：每个查询词都必须出现在同一会话中，但可以分别出现在不同记录里。

List

{
  "action": "list",
  "limit": 10,
  "scope": "cwd"
}

scope 可以是：

• all：检查本地 Pi 存储中的所有项目，这是默认值。
• cwd：只保留记录工作目录与当前 Pi 工作目录相同的会话。

Read

应优先使用 search 或 list 返回的精确路径：

{
  "action": "read",
  "session": "/home/me/.pi/agent/sessions/.../session.jsonl",
  "offset": 0,
  "recordLimit": 80,
  "maxCharacters": 30000
}

当 details.hasMore 为 true 时，从 details.nextOffset 继续。当 details.recordTruncated 为 true 时，应先增大 maxCharacters 并重试当前 offset，再向后翻页。

精确路径只有在规范化解析后仍位于 Pi 会话目录中才会被接受。也可以传会话 ID，但它必须能在所选 scanLimit 范围内唯一定位。

参数

| 参数 | 适用 action | 默认值 | 上限 | 说明 | | ---------------- | ---------------- | ------: | ------: | ------------------------------------ | | query | search | — | — | 必填的词法查询。 | | session | read | — | — | 必填的会话 ID 或精确结果路径。 | | scope | 全部 | all | — | all 或 cwd。 | | limit | list、search | 10 | 50 | 最大返回结果数。 | | scanLimit | 全部 | 1000 | 5000 | 最多检查多少个最新会话文件。 | | includeCurrent | 全部 | false | — | 是否包含当前活动会话。 | | offset | read | 0 | — | 规范化记录偏移量。 | | recordLimit | read | 80 | 200 | 单次响应考虑的记录数。 | | maxCharacters | read | 30000 | 50000 | 应用全局 Tool 输出限制前的字符预算。 |

所有 Tool 响应还会受到 50 KiB UTF-8 和 2,000 行的全局限制，以先达到者为准。

交互命令

/history
/history database migration

命令会打开会话选择器，并提供三个动作：

1. 预览规范化转录。
2. 把会话路径插入编辑器，请 Agent 分析。
3. 恢复所选 Pi 会话。

该命令依赖 Pi 交互 UI。pi_history Tool 才是 Agent 的自主检索接口。

存储与性能

插件按以下顺序查找会话：

1. 已设置的 $PI_CODING_AGENT_DIR。
2. 默认的 ~/.pi/agent。

会话文件应位于 <agent-dir>/sessions/<project>/*.jsonl。

其他行为：

• list 收集到请求数量的合格会话后停止。
• search 会扫描所选 scanLimit 的完整范围，以保证排序有意义。
• 完整 JSONL 行会被组合成约 1 MiB 的规范化批次；单个超大 JSONL 行可能超过这个批次目标。
• 格式错误或不可读的会话会被跳过并计数。
• 只要仍含有可用记录，部分写入或被中断的会话也可以读取。
• 本包不维护持久索引，因此搜索成本随所选语料规模增长。

隐私与安全

Pi 扩展使用用户自身权限执行。安装第三方扩展前应审查源码。

pi-session-history 是只读插件：

• 不修改或删除会话文件。
• 不发起网络请求。
• 会返回本地会话路径，因为后续读取需要稳定标识。
• 精确路径会在规范化路径和符号链接解析后限制在 Pi 会话目录内。
• 搜索结果和转录内容会在进入 Agent 上下文前执行输出限制。

会话内容可能包含源码、工具输出、文件路径、其他工具曾打印的凭据或其他敏感数据。应把 Tool 结果和日志视为敏感材料。

私下报告漏洞的方法见 SECURITY.md。

限制

• 搜索是词法匹配，不是语义搜索或向量检索。
• 会话分支共用一个追加式 JSONL 文件。规范化读取保留文件记录顺序，不会只选择活动分支。
• @letta-ai/trajectory 会在规范化阶段限制超大的工具参数和工具结果。
• 本包通过 trajectory 兼容的 OpenClaw adapter 读取 Pi 当前的 SessionManager JSONL 结构。

更新与卸载

pi update npm:pi-session-history
pi remove npm:pi-session-history

Git 安装可以运行 pi update --extensions，或安装新的固定 ref。

开发

npm install
npm run format:check
npm run lint
npm run typecheck
npm test
npm run check

npm run check 会执行格式检查、lint、类型检查、测试和 npm 打包预检。

贡献要求见 CONTRIBUTING.md。首次发布后，后续版本通过版本 tag 和 .github/workflows/publish.yml 中的 npm Trusted Publishing 发布。

许可证

MIT