Pi Project Memory

English | 简体中文

Pi Project Memory 是 Pi 的项目自动记忆扩展。它把每个项目的长期背景、用户偏好、关键决策和外部资源入口保存为本地 Markdown 文件，并在后续对话中自动挑选相关内容提供给模型，减少每次新会话都要重新解释项目上下文的工作。

本扩展参考 Claude Code 2.1.296 的本地文件模式自动记忆，使用 MEMORY.md 索引文件和按主题拆分的 Markdown 文件来管理项目记忆。所有记忆文件都保存在本地，你可以随时用普通文本编辑器查看、修改或删除。

日常工作方式

• 自动取回相关记忆：主模型使用会话内固定的精简 MEMORY.md 索引快照，后台 selector 根据每次提问最多挑选 5 个相关主题文件（topic）注入当前对话。索引改动通过追加过期提醒通知模型，避免反复改写提示词前缀；会话压缩、切换分支、重载配置或启动会话后重新加载快照。
• 回合后自动提取：每完成一轮对话（或空闲满 2 分钟），后台 extractor 会自动检查刚结束的对话，把值得长期保留的信息写入或更新到记忆目录。会话压缩或退出前也会自动处理尚未提取的对话。
• 定期自动整理（Dream）：当距离上次整理尝试满 24 小时，且期间至少有 5 个其他会话更新过时，后台 dream 会在空闲时自动整理记忆文件，合并重复内容、清理过时信息并精简索引。
• 支持直接读写与口头指令：你可以直接在对话中让主模型记住某条规则或忘掉某条旧记录，主模型会立即更新记忆文件；你也可以直接用外部编辑器修改记忆目录下的 .md 文件，扩展会自动感知外部改动。

关于底层钩子机制、安全协议和与 Claude Code 2.1.296 的详细对比，请参见设计与安全边界与 Claude Code 行为对齐说明。

快速开始

1. 环境要求与安装

本扩展支持 macOS、Linux 和 Android 上的 Termux，运行环境需要安装 bash、git、rg（ripgrep）和 fd。

推荐从 npm 安装：

pi install npm:pi-project-memory

Termux 用户还需完成原生依赖的手动编译。其他安装方式见下文安装与管理。

2. 启动并检查状态

进入一个已在 Pi 中受信任的项目目录并启动 Pi，然后运行：

/memory

面板支持查看项目状态、搜索和预览记忆，以及查看模型配置和用量。

如果想立即将当前对话中的信息提取为记忆，可以随时运行 /memory extract。

安装与管理

从 npm 安装

pi install npm:pi-project-memory

在 Termux 中安装

首先，安装所需工具和扩展。

pkg install nodejs-lts bash git ripgrep fd python make clang
pi install npm:pi-project-memory

接着，使用 npm 12 或更高版本时，放行安装脚本。旧版 npm 可跳过此命令。

npm --prefix ~/.pi/agent/npm install-scripts approve tree-sitter tree-sitter-bash

最后，手动编译依赖。

GYP_DEFINES="android_ndk_path=''" npm --prefix ~/.pi/agent/npm rebuild \
  tree-sitter tree-sitter-bash --ignore-scripts=false --foreground-scripts

从 GitHub 安装

pi install git:github.com/XYenon/pi-project-memory

从本地源码安装

git clone https://github.com/XYenon/pi-project-memory.git
cd pi-project-memory
pnpm install
pi install .

单次试用与日常包管理

• 单次加载试用（不写入 Pi 配置）：pi -e npm:pi-project-memory
• 查看已安装的包：pi list
• 更新已安装的扩展：pi update --extensions
• 卸载扩展：pi remove <source>（<source> 与安装时使用的来源写法一致）

命令参考

命令	用途
/memory 或 /memory status	在终端中打开记忆面板；RPC 和其他模式保留文本状态报告。
/memory list	在终端中打开 Topics，支持搜索和预览；其他模式以文本列出主题类型、路径和描述。
/memory extract	立即运行一次记忆提取，处理尚未提取的对话内容（即使配置中关闭了自动提取也可手动运行）。
/memory dream	立即运行一次记忆整理与合并。跳过间隔时间和会话数量条件，但仍要求配置中 dream.enabled 为 true。
/memory reload-config	重新加载用户级配置文件。模型、提取和整理参数立即生效；autoMemoryDirectory 目录路径变更需在下次启动会话时生效。

Tab 切换页面，在 Topics 中直接输入搜索，Enter 预览，Escape 返回或关闭。子命令支持补全。

常见配置入口

用户级配置文件位于：

~/.pi/agent/project-memory/config.json

如果该文件不存在，扩展会使用内置默认值。你可以从仓库中的 config.example.json 复制生成初始配置：

mkdir -p ~/.pi/agent/project-memory
cp config.example.json ~/.pi/agent/project-memory/config.json

最常用的配置项如下：

• enabled：扩展总开关（默认 true）。设为 false 时完全停用扩展，不创建记忆目录，也不发起任何后台模型调用。
• autoMemoryDirectory：自定义记忆文件的保存目录（默认 null，支持绝对路径或 ~/ 开头的路径）。只能从用户级配置文件设置，项目仓库内的文件无法覆盖它。
• models.selector、models.extractor、models.dream：分别为挑选、提取和整理三个后台任务指定模型（model）、思考档位（thinkingLevel）和最大输出长度（maxTokens）。
• extraction：调整自动提取开关（enabled）、每隔多少轮提取一次（everyNTurns，默认 1）以及空闲触发秒数（idleFlushSeconds，默认 120）。
• dream：调整定期整理开关（enabled）、最短间隔小时数（minimumHours，默认 24）以及需要累积的其他会话数（minimumOtherSessions，默认 5）。

修改配置后，运行 /memory reload-config 或重启 Pi 即可。所有字段的类型、取值范围、逐字段回退规则和配置示例请查阅配置参考。

数据存储与可直接编辑的文件

默认情况下，扩展将数据保存在 ~/.pi/agent/project-memory/ 下，每个项目拥有独立的记忆目录：

~/.pi/agent/project-memory/
├── config.json
├── projects/
│   └── <project-key>/
│       └── memory/
│           ├── MEMORY.md
│           └── *.md
└── memory-roots/
    └── <memory-root-hash>/
        ├── state.json
        └── locks/

• 同一仓库与 Worktree 共享记忆：Git 仓库按主检出目录区分项目，使用 git worktree 创建的关联工作树会自动共享同一份项目记忆。
• 可直接查看和编辑：memory/ 目录下的 MEMORY.md 是简短索引，其他 .md 文件保存具体的主题记忆。你可以随时用编辑器查看、修改、新增或删除这些 .md 文件。
• 切勿手动修改内部状态文件：除 config.json 和 memory/*.md 外，其余如 .project-root、state.json 和 locks/ 均为扩展内部协调文件，请勿手动编辑。

完整的目录树、自定义目录影响、状态文件用途和文件生命周期说明请参见配置参考中的存储路径与目录结构说明。

模型费用、隐私与安全摘要

• 模型选择与费用：三个后台任务的模型默认均为 "inherit"（跟随当前 Pi 主会话模型），也可单独指定为 "provider/model-id"。当显式指定的模型不存在或未配置凭据时，对应任务会发出 warning 通知并跳过，不会私自切换到其他模型。后台调用会按所选 provider 的标准正常计费，但不会写入主会话的聊天账单记录；你可以通过 /memory status 查看当前进程累计的后台 token 与费用（重启 Pi 后清零）。
• 提示词缓存：后台请求启用 Pi 的短期缓存。Selector 保持完整目录前缀，在选择后过滤已读文件；同模型的 extractor / dream 在有父请求快照时保留其系统消息、工具声明与完整历史，仅追加任务指令。实际命中和费用取决于 provider、缓存有效期与最小长度，不能保证每次命中。
• 项目信任保护：扩展只在 Pi 已信任的项目中运行。对未受信任的项目，扩展不会创建目录、读取文件或调用模型。
• 发送给模型的数据：
  • selector 只接收你的当前提问和已有记忆文件的摘要列表（文件名、类型、修改时间和一行描述），不会上传全部记忆正文。
  • extractor 默认可接收完整父请求历史以复用缓存，但提取目标仍是游标之后的未处理消息；跨模型、缺少可复用快照等情况下仅发送未处理消息。显式设置 extraction.recentMessages 为整数时禁用完整父前缀复用，遵守该消息上限。
  • dream 在整理时会读取记忆目录、当前项目文件以及该项目的历史会话记录（JSONL），用来核对事实和提炼长期信息。
  • 以上数据会发送给你所配置的模型 provider，请根据项目敏感程度选择合适的 provider 和模型。
• 后台写入限制：后台任务只能创建、修改或删除当前项目记忆目录下的 .md 文件，不能修改你的项目源码、AGENTS.md 或历史会话文件。详细安全边界请阅读设计与安全边界。

使用限制与注意事项

• 中英文空格触发门槛：为了对齐 Claude Code 2.1.296 的触发规则，自动取回和自动提取都按空白字符判断输入长度：
  • 自动取回（Selector）：提问文本去掉首尾空白后，中间必须包含至少一个空格、换行或制表符。单个英文单词或整句不含空格的纯中文输入不会触发自动取回。
  • 自动提取（Extractor）：未提取的用户消息中，必须至少有一段文本按空白字符拆分后达到 3 个词（即至少包含两处空格或换行）。完全不含空格的纯中文短句不会触发自动提取（手动运行 /memory extract 同样受此三词条件限制）。如果你习惯输入不带空格的中文，可以直接在对话中让主模型保存记忆，或在句子中加入空格。
• 记忆文件大小与预算限制：MEMORY.md 索引最多加载前 200 行（约 25,000 个字符）；单个主题文件在自动取回时最多读取前 200 行或 4,096 字节，因此建议每个主题文件只记录一项独立事实并保持简短。单个会话分支累计自动取回达到 61,440 个字符后，会在该分支停止自动取回（会话压缩或开启新会话后会重置）。
• 主模型已完整读取的文件不重复取回：如果主模型已经在当前对话中完整读取过某个记忆文件，扩展不会再重复自动取回它；修改时间满 48 小时的旧记忆在读取或取回时会自动提示模型先核对当前代码。
• 不支持的功能：本扩展仅实现本地项目文件记忆，不提供 BM25 本地搜索，文件读取沿用 Pi 原生行为，不额外提供 PDF 或 Jupyter Notebook 解析，也不包含任何 Claude 云端账户记忆、团队共享存储（CLAUDE_MEMORY_STORES）、claude.ai Project memory 或 memory_search 等服务端功能。

常见问题排查

提示项目未受信任（Project is not trusted）

请先在 Pi 中信任当前项目目录，然后重启会话。未受信任的项目不会启用记忆功能。

提示配置的模型不可用或缺少凭据

请检查 ~/.pi/agent/project-memory/config.json 中的 model 是否为 "inherit" 或正确的 "provider/model-id" 格式，并确认已在 Pi 中为该 provider 配置好 API 凭据。

对话后没有自动生成记忆文件

1. 运行 /memory status，检查 Auto-memory 和 Extraction 是否都显示为 enabled。
2. 检查你的输入是否包含足够的空格（按空白拆分至少 3 个词），并且主模型没有在本轮对话中直接调用文件工具写过记忆文件（若主模型已直接写过记忆，后台会自动跳过重复提取）。
3. 运行 /memory extract 手动触发提取，并查看 Pi 是否有模型错误或文件权限方面的 warning 通知。

修改配置文件后没有生效

保存配置后请运行 /memory reload-config 或重启 Pi。注意：如果修改了 autoMemoryDirectory，必须启动新的 Pi 会话才会切换到新目录，且扩展不会自动搬移旧目录中的文件。

文档导航

• 配置参考与存储结构：配置文件位置、逐字段回退规则、全部字段详解、配置示例以及完整的本地存储目录结构与文件生命周期。
• 设计与安全边界：威胁模型、生命周期与钩子流程、后台工具权限控制、读取基线与跨进程并发锁设计。
• Claude Code 行为对齐说明：与 Claude Code 2.1.296 的对齐范围、静态逆向依据、提示词基线规则与宿主适配取舍。
• 开发说明：本地开发环境、检查与测试命令、源码模块职责及长期维护约束。

许可证

本项目基于 GNU Affero General Public License v3.0 or later 许可发布。

Copyright (C) 2026 XYenon