pi-mem

为 AI 编码代理提供纯 Markdown 的持久记忆:长期事实、每日日志、便签与语义检索。

源仓库
jo-inc/pi-mem
Star 数
★ 81
最近更新
18 天前
License
MIT
主语言
TypeScript

30 秒速览

运行形态
命令行工具Agent 插件 / 技能
可在哪里用
兼容但需适配Claude Code(部分支持)
费用
软件免费,模型调用费用自付
上手难度
低 · 几分钟可跑通
开始前需要
pi 编码代理Node.js(npm 包 @askjo/pi-mem)Git(可选,用于 PI_AUTOCOMMIT)Shell / 命令行网络访问本地文件系统
典型场景
长期使用 pi 编码代理的开发者,希望代理记住项目决策与个人偏好,而不是每次重新交代。
不适合
  • 不使用 pi 或 Claude Code 等可扩展插件与工具调用的代理用户
  • 需要完全隔离、不允许代理自动写入本地记忆文件的团队
  • 期望开箱即用、无需配置上下文模式与检索目录的用户
维护状态
近 30 天有提交最近提交 2026-11-02

这个 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 分钟后台重建。

  1. 长期使用 pi 编码代理的开发者,希望代理记住项目决策与个人偏好,而不是每次重新交代。
  2. 同时维护多个分支或克隆会话的团队,想用 /ancestry 弄清当前线程从哪些会话派生而来。
  3. 希望用 grep 友好的纯文本文件审阅和版本化代理记忆,并在每次写入后自动 git 提交的用户。
  4. 在多个编码代理间切换的人,想用同一套 Markdown 记忆目录(通过 PI_MEMORY_DIR 指定)复用长期事实。
  5. 需要把 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?

FollowAgents 源码审查 · FARS-2.1
缺口较多
43/ 100 五分制 2.2 / 5
信任安全 10/29
可靠稳定 6/14
适用触发 9/18
规范维护 8/18
有效结果 7/13
证据核验 3/8
查看各维度的扣分理由
信任安全10 / 29 · 1.7/5

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 与作者字段,发布者身份未验证。

可靠稳定6 / 14 · 2.1/5

配置解析、上下文压缩、ancestry 遍历均有单元测试覆盖(含循环、缺失文件、深度上限),自洽性较好;但依赖 @earendil-works/pi-* 与 @sinclair/typebox 为 peer 依赖且版本范围宽松,可用性无法静态确认;错误处理多为静默 catch 返回 null/空(spritePost、gitCommit),失败信息对用户不可见。

适用触发9 / 18 · 2.5/5

README 明确面向 pi、Claude Code 及任意 LLM agent,场景(长期记忆、日志、便签、检索)清晰,能力边界(无向量检索、纯 Markdown)说明到位;但触发精度依赖模型自行调用工具与 recall 指令,缺少显式触发规则;环境适配绑定 pi 扩展 API 与特定会话目录命名(--Users- 前缀过滤),跨环境适配有限。

规范维护8 / 18 · 2.2/5

README 结构清晰,含布局表、工具表、配置表与安装命令;但安装仅一行 pi install,缺少 npm 安装、前置依赖与配置示例的完整说明;命名稳定(版本 1.2.0、包名固定);示例与 FAQ 较少;已知限制仅零散提及(如 3K 截断),无专门章节;LICENSE 为完整 MIT;有 publish.yml 做 tag 与版本校验,但无 CHANGELOG;维护责任仅指向 jo-inc,发布者未验证。

有效结果7 / 13 · 2.7/5

输出为可直接注入上下文的 Markdown 记忆与检索块,可用性较好,且有 token 预算与截断指针设计;对需要跨会话记忆的 agent 有边际价值;但每轮注入与后台 LLM 摘要(每 15 分钟)带来 token 与调用成本,成本收益证据不足。

证据核验3 / 8 · 1.9/5

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 失败时用户无提示,排障困难。
  • 发布者身份未经验证,安装前应自行核实来源。
证据充分度:低 评估于 2026年11月11日 审查版本 4dd3d369854d
查看完整评分方法 →
你是这个项目的维护者?把 FARS 徽章加到 README

徽章显示当前的评审分数和结论,点击回到本页。重新评审后约一小时内更新。

FARS

[![FARS 评测](https://followagents.com/badge/pi-mem.svg?lang=zh)](https://followagents.com/zh/agents/pi-mem)
<a href="https://followagents.com/zh/agents/pi-mem"><img src="https://followagents.com/badge/pi-mem.svg?lang=zh" alt="FARS 评测"></a>

常见问题

它真的做“语义搜索”吗?
文档中 memory_search 被描述为对根目录、notes/ 和 daily/ 的文件名与内容做不区分大小写的关键词搜索;简介里的“semantic search”并无向量或嵌入模型的实现说明。
记忆文件会被提交到远端吗?
只有当 PI_AUTOCOMMIT 设为 1 或 true 时,pi-mem 才会在每次写入后自动 git 提交;否则文件停留在本地目录,不会自动推送。
system 模式会消耗多少上下文?
长期记忆段约 3K token,超出部分按行边界截断并给出 memory_read 指针;每轮的尾部检索块上限也接近 3K token,超限时整条丢弃;每日日志保留最近内容,上限 2,000 字符。
能在 pi 以外的代理里用吗?
README 称可与 pi、Claude Code 及任何 LLM 代理配合,但安装步骤只给出 pi install 命令,其他代理需要自行接入工具调用与上下文注入逻辑。
开启 session_ancestry 会增加多少负担?
该功能默认关闭,只有设置 PI_ANCESTRY=1 或 .pi-mem.json 中 ancestry 为 true 时才注册工具与 /ancestry 命令,操作均为只读。
pi-mem 免费吗?
软件本身免费,但 pi-mem 要调用 AI 模型,模型的调用费用由你向模型服务商支付(也可以接本地模型)。
pi-mem 开源吗?
开源。源码在 GitHub(jo-inc/pi-mem),许可证是 MIT。
pi-mem 安全吗?
FollowAgents 的 FARS 评审(2026年11月11日)给 pi-mem 的“信任与安全”打了 10/29 分。评审检查的 8 项安全措施没有完全缺失的。
pi-mem 还在维护吗?
在维护。GitHub 上最近一次提交是 2026-11-02,在最近 30 天内。
pi-mem 是谁开发的?
pi-mem 由 GitHub 账号 jo-inc 发布。FollowAgents 没有核实这个账号背后是哪个人或公司。
这页内容对你有帮助吗?
在 GitHub 查看 ↗ 安装 ↓

对比同类 Agent

用同一套 FARS 评审,横向比较这个 Agent 所属的短名单。

相关核心概念