peon-mem

# 🧠 Peon — 您的 AI 编程代理的记忆大脑 [](https://www.npmjs.com/package/peon-mem) [](LICENSE) [](test/) **本地优先、层次化、自我改进的记忆，适用于 Claude Code、Codex 和任何 MCP 客户端。** 您的 AI 在每次会话之间都会忘记一切。Peon 不会。它记录您的会话，使用 LLM 将它们合并为有类型的*信念*，并将相关的信念注入每个提示中。它在您的机器上作为守护进程运行，没有任何数据离开它。 ``` Peon 全局大脑 ← 用户级事实和偏好，继承于所有地方 / | \ 项目 A 项目 B 项目 C ← 根子大脑（.peon/ 在每个项目中） ``` ## 为什么选择 Peon - **层次化大脑。** 一个全局父大脑存储您的身份、规则和工具。每个项目都有一个隔离的子大脑。每次注入都携带两者。 - **两层记忆，诚实测量。** 合并的*信念*（决策、偏好、事实、产物）为您提供概要。一个*情节*逐字逐句层恢复损失性摘要省略的精确细节。在 LongMemEval 上，原始情节回忆得分为 61%，而仅信念得分为 17%。 - **自动捕获和注入。** Claude Code 钩子记录消息和事件，然后注入一个查询排名的记忆块（带有 `⚠ MOST RELEVANT` 头部）到每个提示中。您无需记住保存任何内容。 - **成本门控合并。** LLM 仅在积累足够新的记忆时才会将会话提炼为信念。它可以取代、合并和标记冲突。不会有破坏性的删除。 - **混合检索。** 词汇和语义 RRF 融合、MMR 多样性、强化和时效性。查询嵌入缓存到磁盘，因此重复提示无需成本。 - **神经宇宙。** `localhost:3737/monitor` 上的实时监视器将每个信念呈现为一个星星。项目是星系，搜索使匹配的星星闪烁，自主管理脉动。 - **每日自我审计（STL）。** Peon 每天检查自己：记录了什么，注入了什么，失败了什么，合并了什么。然后它提交一份报告和裁决。 - **评估门控开发。** 一个已提交的结果账本（git SHA、qrels 和每个行的大脑指纹）意味着检索更改是经过验证的，而不是断言的。负面结果仍然被记录。 - **本地优先和锁定。** 普通 JSONL 您可以阅读，一个仅限回环的守护进程，具有 DNS 重新绑定保护、注入边界的秘密删除和路径遍历防护。  *实时监视器：18k 真实信念呈现为星星。输入以使匹配的信念闪烁；点击一个以检查它。*  *询问领域：输入“wulver cluster”使 400+ 个匹配信念闪烁，而其余信念变暗，相机飞向它们。* ## 为什么叫“Peon”？ 这个名字来自印度办公室。每个办公室都有一个**peon**，即从一个桌子走到另一个桌子的人员：收集一个文件，记录谁需要什么，带到下一个桌子，记住一切存放的位置。他不是老板或明星，但整个办公室都依赖他。没有他，任何事情都不会移动，他永远不会忘记东西的位置。 这就是这个框架与 AI 的关系。Peon 在您的会话和项目之间走动。它收集在一个桌面（会话）发生的事情，将其归档在正确的柜子（项目大脑）中，将相关文件带到下一个桌面（注入）之前，并保持总账（全局大脑）更新。安静的职员。完美的记忆。办公室运转靠他。 ## Peon 与现有记忆工具的区别 | | **Peon** | mem0 | Letta/MemGPT | Zep/Graphiti | 普通记忆文件（MEMORY.md） | |---|---|---|---|---|---| | 运行 | **100% 本地守护进程** | 云或自托管 | 服务器 | 云/服务器 | 本地 | | 存储 | 可读的 JSONL | 向量数据库 | 数据库 | 图数据库 | Markdown | | 记忆模型 | **信念 + 原始情节层** | 提取的事实 | 自我编辑块 | 时间知识图 | 散文 | | 层次结构 | **全局父大脑 → 按项目子大脑，在每个提示中继承** | 用户/代理/会话范围 | 按代理 | 按用户 | 按项目文件 | | 捕获 | **通过钩子自动**（零努力） | 您编写的 SDK 调用 | 代理管理 | SDK 调用 | 代理必须记住写入 | | 冲突处理 | 取代/合并，**可恢复 - 绝不硬删除** | LLM 可能删除 | 自我编辑 | 使无效 | 覆盖 | | 精确回忆 | 情节层回归测试（61% vs 17% 仅信念，LongMemEval） | 仅概要 | 仅概要 | 图形事实 | 您写的内容 | | 可观察性 | **实时神经宇宙监视器 + 每日自我审计（STL）+ 提供遥测** | 仪表板 | - | - | - | | 验证 | **已提交的评估账本；保留负面结果** | 供应商基准 | - | 供应商基准 | - | 简而言之：mem0 和 Zep 是用于您构建的产品的记忆平台。Peon 是您已使用的编码代理的记忆。它大约在五分钟内与 Claude Code 或 Codex 集成，并且您可以观察它思考和审计它声称的每个数字。 ## 快速入门 要求：Node 20+，macOS 或 Linux。一个 [OpenRouter](https://openrouter.ai) API 密钥是推荐的（合并 + 语义嵌入）；如果没有，Peon 仍然仅限词汇工作。 一行： ```bash npm install -g peon-mem && peon-mem install ``` （如果没有 Node？`curl -fsSL https://raw.githubusercontent.com/VineetV2/peon-mem/main/install.sh | bash`） 引导式设置会询问四个问题： 1. **您的全局大脑存储位置**（默认：`~/Library/Application Support/Peon`） 2. **哪个 LLM**：OpenRouter（一个密钥，任意模型）· OpenAI · Anthropic · **Ollama（100% 本地和免费）** · 或跳过 3. 将守护进程安装为自动启动服务（macOS 上为 launchd，Linux 上为 systemd 用户单元） 4. **检测您的 AI 应用** 并将 MCP 服务器（以及 Claude Code 的钩子）连接到您选择的应用程序。自动配置：Claude Code、Claude Desktop、Codex、Gemini CLI、Cursor、Windsurf、VS Code（Copilot MCP）、Zed、LM Studio。检测并附带说明：ChatGPT Desktop、Perplexity Desktop。每个受影响的配置都会生成一个 `.peon-backup`。 这会构建软件包、启动守护进程作为服务、连接您的 Claude Code 钩子 + MCP 服务器（以及备份您的设置），并编写一个配置文件模板。然后，将您的密钥添加到 `~/Library/Application Support/Peon/.env` 并打开监视器。`peon-mem install --dry-run` 显示每个操作；`peon-mem uninstall` 逆向操作（内存数据永远不会被触及）。 或手动： ```bash git clone https://github.com/VineetV2/peon-mem && cd peon-mem npm install && npm run build node bin/peon-mem.mjs install --dry-run # 检查，然后运行不带 --dry-run ``` 在存储库根目录创建 `.env`: ```bash OPENROUTER_API_KEY=sk-or-... PEON_PROCESSING_MODEL=google/gemini-2.5-flash-lite # 便宜且足够好（已测量） PEON_EMBEDDING_MODEL=openai/text-embedding-3-small ``` 启动守护进程（安装程序会打印一个 launchd/systemd 配方，或者直接运行）： ```bash node dist/daemon-cli.js # 提供 127.0.0.1:3737 ``` 然后连接您的代理（安装程序会打印这些，填写您的路径）： - **Claude Code**：将钩子添加到 `~/.claude/settings.json`（SessionStart / UserPromptSubmit / SessionEnd → `scripts/claude-peon-hook.mjs`）和 MCP 服务器（`dist/index.js`）。 - **Codex / 任意 MCP 客户端**：将 `dist/index.js` 注册为 stdio MCP 服务器；16 个工具（`start_session`, `get_context`, `search_memory`, `record_message`, `process_memory`, …）。 打开 `http://127.0.0.1:3737/monitor` 并观察您的大脑增长。 ## 它是如何工作的 1. **记录。** 钩子将消息、事件和工具调用流式传输到 `<project>/.peon/raw/`（追加）。 2. **合并。** 在大小门控之后，LLM 将会话增量转换为 `.peon/brain/memories.jsonl` 中的有类型信念记录（重要性/置信度分数、实体、源指针），与现有信念进行调和：取代、合并、冲突标记。可恢复，绝不删除。 3. **检索 + 注入。** 在每个提示中，信念被排名（RRF 词汇+语义、MMR、多样性、强化）和注入，与逐字匹配的情节和继承的全局信念一起。 4. **自我管理。** 后台大脑通过强化召回的信念、压缩过时的集群和解决重复项来进行自我管理。每个操作都会记录并且可撤销。 5. **自我审计（STL）。** 每日作业报告记录了什么、注入了什么、失败了什么以及合并是否正常运行，并带有服务延迟遥测和健康裁决。 ## 完整安装（复制粘贴） ### 1. 守护进程（始终在线，macOS launchd） ```bash node scripts/install-peon.mjs # 打印所有内容，填写您的路径 ``` 或手动 — `~/Library/LaunchAgents/com.peon.daemon.plist`: ```xml <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"><dict> <key>Label</key><string>com.peon.daemon</string> <key>ProgramArguments</key><array> <string>/opt/homebrew/bin/node</string> <string>/ABSOLUTE/PATH/TO/peon/dist/daemon-cli.js</string> </array> <key>RunAtLoad</key><true/> <key>KeepAlive</key><true/> </dict></plist> ``` ```bash launchctl load ~/Library/LaunchAgents/com.peon.daemon.plist curl http://127.0.0.1:3737/health # → {"ok":true} ``` Linux：安装程序会写入 `~/.config/systemd/user/peon-mem.service` 并启用它。手动等效：`systemctl --user enable --now peon-mem.service`，以及 `loginctl enable-linger $USER` 以使其在注销后继续运行。（Linux 支持较新 - [问题 #1](https://github.com/VineetV2/peon-mem/issues/1) 跟踪实际机器报告。） ### 2. Claude Code — 钩子（自动捕获 + 注入） 将以下内容合并到 `~/.claude/settings.json`（替换路径）： ```json { "hooks": { "SessionStart": [{ "hooks": [{ "type": "command", "command": "node /ABSOLUTE/PATH/TO/peon/scripts/claude-peon-hook.mjs" }] }], "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "node /ABSOLUTE/PATH/TO/peon/scripts/claude-peon-hook.mjs" }] }], "SessionEnd": [{ "hooks": [{ "type": "command", "command": "node /ABSOLUTE/PATH/TO/peon/scripts/claude-peon-hook.mjs" }] }] } } ``` ### 3. Claude Code — MCP 服务器（搜索/检查工具） ```bash claude mcp add peon -- node /ABSOLUTE/PATH/TO/peon/dist/index.js ``` ### 4. Codex / 任意 MCP 客户端 `~/.codex/config.toml`: ```toml [mcp_servers.peon] command = "node" args = ["/ABSOLUTE/PATH/TO/peon/dist/index.js"] [mcp_servers.peon.env] PEON_DAEMON_URL = "http://127.0.0.1:3737" ``` Codex 没有钩子，因此请在 `~/.codex/AGENTS.md` 中添加使用规则，告诉它调用 `start_session` + `get_context` 在会话开始时，并调用 `record_message` 以获取持久性事实（[文档/](docs/) 中的示例块）。 ### 5. 验证 ```bash curl "http://127.0.0.1:3737/context?projectPath=$PWD&query=test" # JSON 上下文 open http://127.0.0.1:3737/monitor # 神经宇宙 ``` 启动一个 Claude Code 会话，在任何项目中说出一个决策型陈述，然后结束会话。在一分钟内，监视器显示该信念。下一个会话会注入它。 ### 公开的 MCP 工具 `start_session` · `record_message` · `record_event` · `end_session` · `get_context` · `search_memory` · `inspect_brain` · `build_injection` · `query_projects`（跨项目搜索） · `quality_report` · `remember_global` · `search_global_memory` · `import_global_memory` · `evaluate_project` · `process_memory` · `maybe_process_memory` ### 卸载 ```bash launchctl unload ~/Library/LaunchAgents/com.peon.daemon.plist # 删除钩子条目 + MCP 服务器从您的代理配置中 # 您的内存存储在 <project>/.peon/ 和 ~/Library/Application Support/Peon/ - 普通文件，删除时请等待 ``` ## 故障排除/常见问题 - **没有注入？** `curl http://127.0.0.1:3737/health`；检查钩子是否已注册（在 `claude` 中运行任意提示，然后查看监视器的系统页面以获取请求）。 - **对大提示的 431 错误？** 已处理。钩子将检索查询限制在 2k 字符。 - **没有 OpenRouter 密钥？** 仍然可以运行；检索仅限词汇 + 情节（语义排名和合并需要模型）。`PEON_EMBEDDING_MODE=ollama` 也有效。 - **成本？** 合并是门控（默认：每 ~6k 个新字符触发，大约每天几美分，使用 flash-lite）。查询嵌入缓存到磁盘，因此重复免费。 - **多个机器？** 大脑是您存储库中的普通文件。提交 `.peon/` 如果您希望内存移动（首先删除：原始层包含会话文本）。 - **您的数据发送到哪里？** 仅合并/嵌入调用您的配置的模型提供商。无遥测，无云存储。守护进程拒绝非回环调用者。 ## 配置（env） | 变量 | 默认值 | 用途 | |---|---|---| | `OPENROUTER_API_KEY` | - | 合并 + 嵌入 | | `PEON_PROCESSING_MODEL` | `google/gemini-2.5-flash-lite` | 合并模型 | | `PEON_EMBEDDING_MODE` | auto | `api` / `ollama` / `local` / `off` | | `PEON_EMBEDDING_MODEL` | - | 例如 `openai/text-embedding-3-small` 或 Ollama 模型 | | `PEON_OLLAMA_URL` | `http://127.0.0.1:11434` | 本地嵌入服务器 | | `PEON_AI_MODE` | `gated` | `off` 禁用所有 LLM 调用 | | `PEON_FLUSH_MIN_CHARS` | `6000` | 合并成本门控 | | `PEON_MEMORY_DIR` | `.peon` | 项目大脑目录名称 | | `PEON_DAEMON_URL` | `http://127.0.0.1:3737` | 守护进程地址 | | `PEON_CONSOLIDATION_MAX_DELTA_CHARS` | `60000` | 抗截断-卡顿分段 | | `PEON_DISABLED` | - | 硬关闭开关，用于 A/B 测试 | ## 项目大脑 - 一个大脑存放在 `<project>/.peon/` 中，是可读的 JSONL 和 Markdown。提交它或忽略它；您可以自行决定（`.gitignore` 默认忽略它）。 - `.peon/root` 标记大脑边界。新大脑诞生于此根目录，因此父目录永远不会吞没项目的内存。 - 全局大脑存放在 `~/Library/Application Support/Peon/global/`（macOS）。 ## 在没有 AI 的情况下使用 Peon 有些人希望一个不调用模型的内存系统：没有 API 密钥，没有本地 LLM，没有嵌入。Peon 支持这一点。在安装向导中选择 **跳过**，或在 `<memory-home>/.env` 中设置两个环境变量： ``` PEON_AI_MODE=off PEON_EMBEDDING_MODE=off ``` 没有模型时的处理流程如下。钩子仍然将您执行的所有操作捕获到 `<project>/.peon/raw/` 中的普通 JSONL 中。当每个事件到达时，基于规则的提取将其文件化到可读的大脑文件中：以“我们决定”或“始终使用”开头的行进入 `decisions.md`，偏好进入 `preferences.md`，文件路径进入 `artifacts.md`。没有模型读取它；这是模式匹配，您可以打开文件查看它捕获的内容。在您的下一个会话开始时，钩子询问守护进程获取上下文，守护进程对记录进行关键字匹配、时效性和重要性排序，并将最佳记录注入您的提示中。唯一完全消失的步骤是合并，即夜间 LLM 传递压缩原始历史记录为重复项的信念。没有它，您的内存是一个索引良好的日志，而不是蒸馏的日志。搜索仍然可以找到事物；它们不会被总结。 没有模型时仍然有效（所有这些都是确定性的代码，没有模型）： - **捕获。** 钩子将每个提示、工具调用和会话事件记录到 `<project>/.peon/raw/` 中的纯 JSONL 中。 - **实时大脑文件。** 决策、偏好、开放问题和产物通过基于规则的提取实时写入可读的 `.md` 文件。 - **注入。** 会话开始时的上下文来自这些实时文件，按查询焦点和预算进行排序，与以前一样。 - **搜索。** 词汇检索（RRF 关键字排名，时效性，重要性，类型先验）。不需要嵌入。 - **情节回忆。** 原样逐字查找是按设计词汇的，因此不受影响。 - **监视器 UI，令牌跟踪，跨项目搜索，备份。** 全部无模型。 您会放弃什么：合并（原始事件永远不会蒸馏成重复的信念，因此内存增长为追加日志），语义搜索（同义查询需要共享关键字），自动实体提取和过时阴影解除（它比较嵌入）。 两个逃生孔，如果您希望在没有外部 AI 的情况下进行管理： 1. `process_memory` 接受预构建的 `aiResult`。您已经运行的编码代理（Claude Code，Codex）可以在会话内自行蒸馏结构化结果，并将其传递给 Peon。内存保持管理，您自己从未花费令牌。 2. 所有内容都是磁盘上的纯 JSONL/Markdown。您可以手动编辑信念或通过监视器的内存端点进行编辑，Peon 在每次更改前都会备份。 ## 实测：内存真的能节省令牌吗？ 使用真实的 `claude -p` 会话进行 A/B 测试：每个会话一个问题，同一个仓库，同一个模型。 开启（ON）意味着 Peon 钩子处于活跃状态（在会话开始时注入内存）。关闭（OFF）意味着设置了 `PEON_DISABLED=1`，因此代理回退到读取文件。在 20 个问题中，跨过程、过去结果、决策和当前状态事实；15 个干净的 ON/OFF 对由于工具问题而幸存。令牌计数来自 Claude Code 的会话记录。 | 成对，n=15/臂 | 开启（Peon） | 关闭 | 增量 | | --- | --- | --- | --- | | 平均令牌（输入+输出） | **511** | 878 | **−42%** | | 中位数令牌 | **225** | 1,048 | **−79%** | | 缓存读取令牌 | 81.6k | 110.5k | 1.35 倍减少 | | 更便宜的臂 | **ON 12/15** | | | 答案质量，以仓库真实结果为准：8 次平局，1 次 Peon 明显获胜，5 次基线获胜，1 次两者都弱。Peon 获胜是最有趣的。一个只在对话中提到的规则（教授的引用政策，从电子邮件中），基线得到 *"没有找到这样的规则"*；Peon 准确地背诵了它。对话中的知识没有文件可供 grep。 诚实的注意事项：测试仓库有异常好的文档（一个维护的研究日志），这使得基线很强，而且大多数仓库都不是这样。n=15 很小。问题被挑选出来以确保有已知的答案，而不是从实际使用中抽样。测试还暴露了 Peon 本身的两个真实错误：一个过时的被取代的信念优先于新的真相，以及在合并超时时令牌行丢失。两者都已修复（检索时进行过时影子降级；合并前记录使用情况）。 ## 诚实部分 Peon 的开发通过评估关卡，并保留其负面结果。构建了一个关联实体图，测量了（-2.9% Recall@10），并默认关闭。合并设计上是有损的；这就是为什么存在短暂层并进行回归测试。评估工具和提交的账本（`npm run eval`）允许您自己验证检索更改。 ## 安全 - 守护进程仅绑定 `127.0.0.1` 并拒绝非回环 `Host`/`Origin` 头（DNS 重新绑定防御）。 - 机密（API 密钥、令牌、JWT）会在注入边界处被删除。 - 路径遍历受到保护。写入使用每个项目锁和原子 tmp+rename，并自动备份任何破坏性操作前。没有任何硬删除。 ## 许可证 MIT © Vineet Vora ## 贡献 — 我很乐意得到您的帮助 Peon 由一个人构建和维护，我很乐意帮助它变得更好。问题、PR、想法、对架构的批评或只是告诉我它在您的机器上哪里崩溃：所有这些都是有用的。 目前最需要帮助的地方： - **Windows 和 Linux 支持。** 守护进程安装今天是 macOS launchd。systemd 和任务调度器等效项需要真正的用户来测试它们。 - **更多代理集成。** 向导涵盖了 11 个应用程序，但钩子级捕获（像 Claude Code 集成一样）适用于 Codex、Cursor 等，将使内存更加丰富。 - **检索质量。** 评估工具（`npm run eval`）使实验变得便宜：更好的合并提示、更智能的过时处理、本地嵌入模型值得默认使用。 - **基准。** 在您的仓库上运行令牌 A/B 并分享数字，特别是在 Peon 失败的地方。负面结果在这里是一流的。 - **文档和 onboarding。** 如果 README 或向导让您感到困惑，那么这种困惑就是一个错误报告。 在 [github.com/VineetV2/peon-mem/issues](https://github.com/VineetV2/peon-mem/issues) 上打开一个问题或直接发送 PR。 房屋规则：每个检索/质量变更都带有测试和评估账本运行（`npm run eval`）；负面结果被记录，而不是删除；任何内容都不允许硬删除用户内存。`npm test` 必须保持绿色。