pi-mem
为 AI 编码代理提供纯 Markdown 的持久记忆:长期事实、每日日志、便签与语义检索。
- Star 数
- ★ 81
- 最近更新
- 18 天前
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 43/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 兼容但需适配Claude Code(部分支持)
- 费用
- 软件免费,模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 长期使用 pi 编码代理的开发者,希望代理记住项目决策与个人偏好,而不是每次重新交代。
- 不适合
- 不使用 pi 或 Claude Code 等可扩展插件与工具调用的代理用户
- 需要完全隔离、不允许代理自动写入本地记忆文件的团队
- 期望开箱即用、无需配置上下文模式与检索目录的用户
- 维护状态
- 近 30 天有提交最近提交 2026-11-02
- 源码审查
- 43/100 · 缺口较多
这个 Agent 能做什么,适合哪些场景?
pi-mem 是一个面向编码代理的持久记忆插件,把记忆以纯 Markdown 文件存放在 ~/.pi/agent/memory/ 下(可用 PI_MEMORY_DIR 覆盖)。它提供 MEMORY.md 长期记忆、SCRATCHPAD.md 待办清单、daily/YYYY-MM-DD.md 每日追加日志和 notes/*.md 自由笔记四类文件。代理通过 memory_write、memory_read、memory_search、scratchpad 等工具读写这些文件,可选的 session_ancestry 工具则沿 parentSession 链回溯会话祖先。上下文注入有 system、bootstrap、full、off 四种模式,默认 system 模式把约 3K token 的长期记忆放进可缓存的系统提示段,并在每轮追加一条检索消息。配置可来自环境变量或记忆目录下的 .pi-mem.json,安装通过 pi install git:github.com/jo-inc/pi-mem 完成。
pi-mem 在代理运行时注册一组记忆工具:memory_write 向 long_term(MEMORY.md)、daily(当日日志)或 note(notes/文件名)写入,支持 append 与 overwrite;memory_read 读取长期记忆、scratchpad、每日日志、笔记、根目录任意文件或列出全部;memory_search 对根目录、notes/ 与 daily/ 做不区分大小写的文件名与内容关键词搜索;scratchpad 管理 add/done/undo/clear_done/list 的清单状态。上下文注入按 PI_MEMORY_CONTEXT_MODE 选择模式:system 模式把 MEMORY.md 压缩到约 3K token 放在缓存的系统提示中,并每轮追加检索块、相似历史对话、已存事实(上限约 3K token,整条丢弃不截断)以及今天和昨天的日志(2,000 字符上限);full 模式每轮注入上下文文件、MEMORY.md、今日与昨日日志和 catchup 索引。启用 PI_ANCESTRY 后还会注册 session_ancestry 工具与 /ancestry 命令,只读地沿跨文件 parentSession 链回溯,并防御循环与缺失文件。会话开始时还会展示自动生成的“Last 24h”面板,扫描近期会话文件的标题、成本与子代理数量,按主题分组,每 15 分钟后台重建。
- 长期使用 pi 编码代理的开发者,希望代理记住项目决策与个人偏好,而不是每次重新交代。
- 同时维护多个分支或克隆会话的团队,想用 /ancestry 弄清当前线程从哪些会话派生而来。
- 希望用 grep 友好的纯文本文件审阅和版本化代理记忆,并在每次写入后自动 git 提交的用户。
- 在多个编码代理间切换的人,想用同一套 Markdown 记忆目录(通过 PI_MEMORY_DIR 指定)复用长期事实。
- 需要把 SOUL.md、AGENTS.md 等身份或行为文件注入上下文的用户,可通过 PI_CONTEXT_FILES 与 full 模式实现。
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 环境变量
PI_MEMORY_DIR- 配置文件
.pi-mem.json
如何安装或部署这个 Agent?
前提是已安装 pi 编码代理,并可运行其 CLI。通过 pi 的安装命令拉取仓库:
pi install git:github.com/jo-inc/pi-mem也可从 npm 获取同名包 @askjo/pi-mem。若需要自动提交记忆变更,需额外安装 Git。安装后可选择性在记忆目录写入配置文件:
{
"searchDirs": ["catchup", "projects"],
"contextFiles": ["SOUL.md", "AGENTS.md"],
"contextMode": "system",
"autocommit": true,
"ancestry": false
}如何使用这个 Agent?
记忆文件默认位于 ~/.pi/agent/memory/,可用环境变量改变行为,环境变量优先于 .pi-mem.json:
export PI_MEMORY_DIR=~/.pi/agent/memory/
export PI_MEMORY_CONTEXT_MODE=system
export PI_TIMEZONE=Asia/Shanghai
export PI_AUTOCOMMIT=1
export PI_ANCESTRY=1在会话中让代理调用工具即可:向长期记忆写入一条决策,把待办加入 scratchpad,或检索历史笔记。
memory_write(target='long_term', mode='append', content='项目统一使用 pnpm')
memory_write(target='note', filename='lessons.md', content='...')
memory_search(query='部署流程')
scratchpad(action='add', item='补写 README 示例')开启祖先追溯后,可在会话中直接使用斜杠命令查看当前线程的来源链:
/ancestry这个 Agent 有哪些优点和局限?
- 记忆以纯 Markdown 明文存放,可直接用编辑器、grep 或 git 审阅与回滚,不依赖数据库或向量服务。
- 上下文注入的 system 模式把长期记忆放在可缓存的系统提示段,只有一条小的尾部消息随轮次变化,缓存友好。
- 检索块与每日日志有明确的 token 上限,超限时整条丢弃而非截断,并给出 memory_search / memory_read 指针。
- session_ancestry 默认关闭,开启后为只读并防御循环链、缺失文件与失控长度。
- 配置既可走环境变量也可走 .pi-mem.json,且环境变量优先,便于按项目或按机器区分。
- 核心入口是 pi install 命令,主要面向 pi 编码代理生态;对 Claude Code 等其他代理只有 README 声明可用,仓库内未给出等价集成步骤。
- 记忆目录默认放在用户主目录下的 ~/.pi/agent/memory/ 单一位置,多项目隔离需要自行通过 PI_MEMORY_DIR 切换。
- memory_search 为不区分大小写的关键词匹配,并非向量语义检索,尽管简介中使用了“语义搜索”的措辞。
- “Last 24h”面板按主题分组依赖一次 LLM 调用,失败时退化为平铺列表,且每 15 分钟后台重建带来额外调用开销。
- 启用 PI_AUTOCOMMIT 后每次写入都会自动提交到 git,缺少细粒度审查流程,可能产生大量提交。
这个 Agent 与同类方案有什么区别?
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| pi-mem 当前 | 43 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 81 | 18 天前 | TypeScript | — |
| Magic Context | 54 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 2.5k | 今天 | TypeScript | — |
| Ori Mnemos | 56 · 缺口较多 | 命令行工具免费 | ★ 337 | 1 个月前 | TypeScript | Claude Code · OpenAI API · Claude API |
| MCP Memory Service | 68 · 存在缺口 | MCP 服务器免费 | ★ 2.1k | 1 天前 | Python | ChatGPT · Codex · Claude Code · Claude.ai |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
index.ts 会读取 PI_SPRITE_URL/SPRITE_TOKEN/USER_ID 并向 Sprite 服务发送对话检索与 SQL 查询(/conversation/search、/db/query),但 README 完全未提及该数据外发路径,数据流透明度不足;autocommit 默认关闭、ancestry 默认关闭属于较好的最小权限设计,但 git add -A 与 --no-verify 提交、以及向外部服务发送用户事实属于需注意的副作用;回滚仅依赖可选 git 提交,无显式撤销机制;依赖为 peerDependencies 且未锁定,依赖安全证据薄弱;来源归属仅靠 MIT 与作者字段,发布者身份未验证。
配置解析、上下文压缩、ancestry 遍历均有单元测试覆盖(含循环、缺失文件、深度上限),自洽性较好;但依赖 @earendil-works/pi-* 与 @sinclair/typebox 为 peer 依赖且版本范围宽松,可用性无法静态确认;错误处理多为静默 catch 返回 null/空(spritePost、gitCommit),失败信息对用户不可见。
README 明确面向 pi、Claude Code 及任意 LLM agent,场景(长期记忆、日志、便签、检索)清晰,能力边界(无向量检索、纯 Markdown)说明到位;但触发精度依赖模型自行调用工具与 recall 指令,缺少显式触发规则;环境适配绑定 pi 扩展 API 与特定会话目录命名(--Users- 前缀过滤),跨环境适配有限。
README 结构清晰,含布局表、工具表、配置表与安装命令;但安装仅一行 pi install,缺少 npm 安装、前置依赖与配置示例的完整说明;命名稳定(版本 1.2.0、包名固定);示例与 FAQ 较少;已知限制仅零散提及(如 3K 截断),无专门章节;LICENSE 为完整 MIT;有 publish.yml 做 tag 与版本校验,但无 CHANGELOG;维护责任仅指向 jo-inc,发布者未验证。
输出为可直接注入上下文的 Markdown 记忆与检索块,可用性较好,且有 token 预算与截断指针设计;对需要跨会话记忆的 agent 有边际价值;但每轮注入与后台 LLM 摘要(每 15 分钟)带来 token 与调用成本,成本收益证据不足。
README 的声明(3K 截断、2K 日志上限、ancestry 只读)在测试中有对应断言,可追溯性尚可;但 Sprite 数据流、dashboard LLM 摘要等关键行为在 README 中缺失,跨源佐证不足;文档与代码对数据外发的描述存在事实与推断混杂,未明确区分。
- index.ts 会向 PI_SPRITE_URL 发送对话检索与 SQL 查询,README 未披露该数据外发路径,部署前应审计并确认是否可接受。
- autocommit 使用 git add -A 与 --no-verify 提交,可能提交非预期文件并跳过钩子,建议在专用记忆仓库中启用。
- 依赖为宽松 peerDependencies,未锁定版本,安装前应核对 @earendil-works/pi-* 与 typebox 的兼容性。
- 错误处理多为静默失败,Sprite 不可用或 git 失败时用户无提示,排障困难。
- 发布者身份未经验证,安装前应自行核实来源。
常见问题
它真的做“语义搜索”吗?
记忆文件会被提交到远端吗?
system 模式会消耗多少上下文?
能在 pi 以外的代理里用吗?
开启 session_ancestry 会增加多少负担?
pi-mem 免费吗?
pi-mem 开源吗?
pi-mem 安全吗?
pi-mem 还在维护吗?
pi-mem 是谁开发的?
谢谢反馈,我们会据此改进页面。