peon-mem

🧠 Peon — 为 AI 编码 Agent 打造的记忆大脑

本地优先、分层且能自我改进的记忆，适用于 Claude Code、Codex 和任何 MCP 客户端。

你的 AI 会忘记不同会话之间的一切，Peon 不会。它会记录你的会话，使用大模型将其整合为有类型的信念，并将相关内容注入每条提示词。它作为守护进程在你的机器上运行，不会有任何数据离开本机。

        PEON GLOBAL BRAIN            ← user-level facts & preferences, inherited everywhere
       /        |         \
  project A  project B  project C    ← rooted child brains (.peon/ in each project)

为什么选择 Peon

• 分层大脑。 一个全局父级大脑记录你是谁、你的规则和你的工具。每个项目都有一个隔离的子级大脑。每次注入都会同时包含两者。
• 两层记忆，诚实衡量。 整合后的信念（决策、偏好、事实、产物）为你提供概要。情景记忆逐字记录，可找回有损摘要遗漏的确切细节。在我自己的 LongMemEval 测试中，原始情景记忆的召回率为 61%，而仅使用信念时为 17%——这是自测结果，并非独立基准；可运行 npm run eval 重现。
• 自动捕获和注入。 Claude Code 钩子会记录消息和事件，然后将按查询排序的记忆块（带有 ⚠ MOST RELEVANT 标题）注入每条提示词。你永远不必记得保存任何内容。
• 按成本门控的整合。 只有在积累了足够的新记忆后，大模型才会将会话提炼为信念。它可以取代、合并信念，并标记冲突。不会以破坏性方式删除任何内容。
• 混合检索。 采用词法与语义 RRF 融合、MMR 多样性、强化和时间新近度。查询嵌入会缓存到磁盘，因此重复提示词不会产生任何成本。
• 神经宇宙。 localhost:3737/monitor 上的实时监视器会将每条信念渲染成一颗星星。项目是星系，搜索会让匹配项闪亮，自主整理会产生脉冲。
• 每日自审（STL）。 Peon 每天都会检查自身：记录了什么、注入了什么、哪里失败、整合做了什么。然后它会提交一份带有结论的报告。
• 评估门控开发。 提交到仓库的结果记录表（每行包含 git SHA、qrels 和大脑指纹）意味着检索变更都有实证支持，而非仅凭断言。负面结果也会保留记录。
• 本地优先且安全可靠。 使用可供你读取的纯 JSONL，仅监听回环地址并防范 DNS 重绑定的守护进程、在注入边界进行机密信息脱敏，并防范路径遍历。

实时监视器：将 1.8 万条真实信念渲染成星星。输入文字即可让匹配的信念闪亮；点击即可查看详情。

在星海中提问：输入“wulver cluster”，会让 400 多条匹配的信念闪亮，其余信念则变暗，镜头也会飞向它们。

为什么叫“Peon”？

这个名字源自印度的办公室。每间办公室都有一个 peon，他整天在办公桌之间走动：从这张桌子收取文件，记下谁需要什么，再把文件送到下一张桌子，记住所有东西放在哪里。他不是老板，也不是明星人物，但整个办公室都在默默依靠他运转。没有他，任何事情都无法推进；而且他从不会忘记任何东西放在哪里。

这就是这个框架在 AI 领域的角色。Peon 在你的会话和项目之间穿梭。它收集一张办公桌（一个会话）上发生的事情，将其归档到正确的柜子里（一个项目大脑），在你开口之前就把相关文件送到下一张桌子（注入），并将总账本保存在楼上（全局大脑）。安静的办事员。完美的记忆力。整个办公室都依靠它运转。

Peon 与现有记忆工具的区别

	Peon	mem0	Letta/MemGPT	Zep/Graphiti	扁平记忆文件（MEMORY.md）
运行方式	100% 本地守护进程	云端或自托管	服务端	云端/服务端	本地
存储	可用 cat 查看的人类可读 JSONL	向量数据库	数据库	图数据库	Markdown
记忆模型	信念 + 原文情景记忆层	提取的事实	自行编辑的区块	时序知识图谱	散文
层级结构	全局父级大脑 → 每个项目的子级大脑，每次提示词都会继承	用户/Agent/会话范围	每个 Agent 独立	每个用户独立	每个项目一个文件
采集	通过钩子自动完成（无需费心）	你编写的 SDK 调用	由 Agent 管理	SDK 调用	Agent 必须记得写入
冲突处理	取代/合并，可恢复——绝不彻底删除	大模型可能会删除	自行编辑	失效处理	覆盖
精确回忆	情景记忆层经过回归测试（在 LongMemEval 上自测，得分为 61%，仅使用信念时为 17%）	仅摘要	仅摘要	图谱事实	写入的内容
可观测性	实时 Neural Universe 监视器 + 每日自审计（STL）+ 服务遥测	控制面板	—	—	—
验证	已提交的评估台账；保留负面结果	供应商基准测试	—	供应商基准测试	—

简而言之：mem0 和 Zep 是供你构建产品使用的记忆平台。Peon 则是供你已在使用的编码 Agent 使用的记忆工具。它能在大约五分钟内接入 Claude Code 或 Codex，而且你可以观察它的思考过程，并审计它声称的每一个数字。

你的 Agent 共用一个大脑

如果你使用多个编码 Agent——比如 Claude Code 和 Codex——它们通常各自待在独立的环境中。你和其中一个 Agent 一起解决的问题，切换到另一个 Agent 时就不复存在了。

让它们指向同一个项目，Peon 就能消除这道隔阂。两个 Agent 都会定位到同一个 .peon/ 大脑（Peon 会规范化项目路径，因此钩子、直接 MCP 调用和 Codex 最终都会使用同一个存储）。这样，记忆就能在它们之间流动：

• Codex 弄清楚构建流水线如何运行，并将其记录下来。下次你在该仓库中打开 Claude Code 时，这些内容已经注入上下文。
• Claude Code 遇到一个棘手问题并将其记录下来。Codex 调用 get_context 或 search_memory 时，就能立即看到。
• 全局大脑位于二者之上，因此你的偏好和规则会跟随你进入每个项目中的每个 Agent。

它们不会实时聊天，而是共用一本双方都能读写的笔记本，因此，一个 Agent 做出的决定会出现在另一个 Agent 那里，无需你再次解释。同一个项目，同一份记忆，不论有多少个 Agent。

快速开始

要求：Node 20+、macOS 或 Linux。建议使用 OpenRouter API 密钥（用于整合和语义嵌入）；没有密钥时，Peon 仍可仅通过词法方式工作。

一行命令：

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、Cline、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 会撤销这些操作（绝不会触碰记忆数据）。

或者手动安装：

git clone https://github.com/VineetV2/peon-mem && cd peon-mem
npm install && npm run build
node bin/peon-mem.mjs install --dry-run   # inspect, then run without --dry-run

在仓库根目录创建 .env：

OPENROUTER_API_KEY=sk-or-...
PEON_PROCESSING_MODEL=google/gemini-2.5-flash-lite   # cheap + good enough (measured)
PEON_EMBEDDING_MODEL=openai/text-embedding-3-small

启动守护进程（安装程序会打印 launchd/systemd 配置说明，也可以直接运行）：

node dist/daemon-cli.js              # serves 127.0.0.1:3737

然后接入你的 Agent（安装程序会根据你的路径打印填好的配置）：

• 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. **整合。**达到大小阈值后，大模型会将会话增量转换为 .peon/brain/memories.jsonl 中的类型化信念记录（重要性/置信度评分、实体、来源指针），并与现有信念协调：替换、合并、标记冲突。内容可恢复，绝不会删除。
3. **检索 + 注入。**每次收到提示词时，都会对信念进行排序（RRF 词法 + 语义、MMR、强化），并与情景记忆的逐字匹配结果及继承的全局信念一同注入。
4. **自我整理。**后台记忆库任务会强化已回忆的信念、压缩过时的集群，并解决重复项。每项操作都会记录日志且可撤销。
5. **自我审计（STL）。**每日任务会报告记录了什么、注入了什么、出了什么问题，以及整合是否正常运行，并提供服务延迟遥测数据和健康状况结论。

完整安装（复制粘贴）

1. 守护进程（始终运行，macOS launchd）

node scripts/install-peon.mjs           # prints everything below filled in for YOUR paths

或手动配置 — ~/Library/LaunchAgents/com.peon.daemon.plist：

<?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>

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 支持尚处于早期阶段 — issue #1 会跟踪真实机器上的报告。）

2. Claude Code — 钩子（自动捕获 + 注入）

合并到 ~/.claude/settings.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 服务（搜索/检查工具）

claude mcp add peon -- node /ABSOLUTE/PATH/TO/peon/dist/index.js

4. Codex / 任意 MCP 客户端

~/.codex/config.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. 验证

curl "http://127.0.0.1:3737/context?projectPath=$PWD&query=test"   # JSON context
open http://127.0.0.1:3737/monitor                                  # the Neural Universe

在任意项目中启动 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

卸载

launchctl unload ~/Library/LaunchAgents/com.peon.daemon.plist
# remove the hook entries + MCP server from your agent config
# your memory stays in <project>/.peon/ and ~/Library/Application\ Support/Peon/ — plain files, delete when ready

故障排除 / 常见问题

• 没有注入内容？ 运行 curl http://127.0.0.1:3737/health；检查钩子是否已注册 （在 claude 中运行任意提示词，然后查看监控器“系统”页面中的请求）。
• 大型提示词出现 431 错误？ 已处理。钩子会将检索查询限制为 2k 个字符。
• 没有 OpenRouter 密钥？ 所有功能仍可运行；检索仅使用词汇和情景记忆 （语义排序和整合需要模型）。PEON_EMBEDDING_MODE=ollama 也可使用。
• 费用？ 整合设有门槛（默认：每新增约 6k 个字符触发一次，使用 flash-lite 时每天约几美分）。查询嵌入会缓存到磁盘，因此重复查询免费。
• 多台机器？ 大脑是仓库中的纯文件。若想让记忆随项目迁移，可提交 .peon/ （请先删去敏感信息：原始层包含会话文本）。
• 我的数据会发送到别处吗？ 只会向你配置的模型提供商发送整合和嵌入请求。没有遥测，也没有云端存储。守护进程会拒绝非环回地址的调用者。

配置（环境变量）

变量	默认值	用途
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_CONSOLIDATION_CONCURRENCY	1 本地，2 托管	所有项目中允许同时进行的整合数
PEON_LLM_TIMEOUT_MS	600000	单次整合请求的截止时间
PEON_QUERY_EMBED_TIMEOUT_MS	2000	按词汇排序前，提示词等待查询嵌入的时长
PEON_EMBED_TIMEOUT_MS	90000	单次嵌入请求的截止时间（在新连接上重试一次）
PEON_DISABLED	—	用于 A/B 测试的硬性关闭开关

项目大脑

• 大脑以人类可读的 JSONL 和 Markdown 文件形式存放在 <project>/.peon/ 中。是否提交或忽略由你决定（随附的 .gitignore 会忽略该目录）。
• .peon/root 用于标记大脑边界。新大脑会在根目录下创建，因此父目录永远无法吞并项目的记忆。
• 全局大脑位于 ~/Library/Application Support/Peon/global/（macOS）。

完全不使用 AI 时使用 Peon

有些人想要一个从不调用模型的记忆系统：不需要 API 密钥、本地 LLM 或嵌入。Peon 支持这种方式。在安装向导中选择 skip，或者在 <memory-home>/.env 中设置两个环境变量：

PEON_AI_MODE=off
PEON_EMBEDDING_MODE=off

不使用模型时，处理流程如下。Hooks 仍会将你执行的所有操作记录为 <project>/.peon/raw/ 中的纯 JSONL。每当事件到达时，基于规则的提取会将其归入易读的脑文件：以“we decided”或“always use”开头的行会写入 decisions.md，偏好会写入 preferences.md，文件路径会写入 artifacts.md。没有模型读取这些内容；这里使用的是模式匹配，你可以打开文件，查看它准确捕获了什么。在下一次会话开始时，Hook 会向守护进程请求上下文，守护进程根据关键词匹配、时间新近度和重要性为这些记录排序，并将最相关的记录注入提示词。唯一会完全消失的步骤是整合，也就是每晚运行的 LLM 流程，它会将原始历史压缩为去重后的信念。没有这一步，你的记忆就是一本索引完善、而非提炼过的日志。搜索仍能找到内容；但不会对其进行摘要。

仍然可用的功能（全部由确定性代码实现，不涉及任何模型）：

• 捕获。 Hooks 会将每条提示词、工具调用和会话事件记录为 <project>/.peon/raw/ 中的纯 JSONL。
• 实时脑文件。 事件到达时，基于规则的提取会将决策、偏好、未决问题和产物实时写入易读的 .md 文件。
• 注入。 会话开始时的上下文来自这些实时文件，聚焦查询并设有预算，与以往一样。
• 搜索。 词法检索（对关键词排名、时间新近度、重要性和类型先验进行 RRF 排序）。无需嵌入。这与语义栈的降级路径相同，因此会不断得到运用。
• 情景回忆。 对原话内容的查找本来就采用词法检索，因此不受影响。
• 监控界面、令牌跟踪、跨项目搜索、备份。 全部无需模型。

你将失去：整合功能（原始事件永远不会被提炼为去重后的信念，因此记忆会像只追加的日志一样不断增长）、语义搜索（改述后的查询需要包含相同关键词）、自动实体提取，以及过时影子降级（该功能会比较嵌入）。

如果你想在不使用外部 AI 的情况下整理记忆，可以通过以下两种方式实现：

1. process_memory 接受预先构建的 aiResult。你已经在使用的编码 Agent（Claude Code、Codex）可以在会话中自行提炼内容，并将结构化结果交给 Peon。这样记忆仍能得到整理，而 Peon 本身不会消耗任何令牌。
2. 磁盘上的所有内容都是纯 JSONL/Markdown。你可以手动或通过监控界面的记忆端点编辑信念；Peon 会在每次修改前进行备份。

实测：记忆真的能节省令牌吗？

使用真实的 claude -p 会话进行 A/B 测试：每个会话只问一个问题，使用相同的代码库和模型。 ON 表示 Peon 钩子已启用（会话开始时注入记忆）。OFF 表示 PEON_DISABLED=1， 因此 Agent 会改为读取文件。在流程、过往结果、决策和当前状态事实等方面提出 20 个问题； 排除工具问题后，保留了 15 组有效的 ON/OFF 配对。令牌数量来自 Claude Code 自己的会话记录。

配对测试，每组 n=15	ON（Peon）	OFF	差值
平均令牌数（输入+输出）	511	878	−42%
令牌数中位数	225	1,048	−79%
缓存读取令牌数	81.6k	110.5k	少 1.35 倍
成本较低的一方	ON 胜出 12/15 次

根据代码库中的真实信息评估回答质量：8 组打平，1 组 Peon 明显胜出，5 组基线胜出， 另有 1 组双方表现都不佳。Peon 胜出的那组最值得关注。一条只在对话中提过的规则（一位教授在电子邮件中提出的引用政策），让基线回答 “未找到此类规则”；而 Peon 则准确复述了它。对话中形成的知识，没有文件可供搜索。

坦诚说明局限：测试代码库的文档质量异常高（有持续维护的研究日志），因此基线表现很强，而大多数代码库并非如此。样本量只有 15，较小。问题经过挑选，答案已知，并非从真实使用中抽样。测试还发现了 Peon 自身的两个实际缺陷：已过时且被取代的信念在检索时优先于新事实；合并操作超出钩子超时后，令牌记录会丢失。两者现已修复（检索时降低过时信息的优先级；在合并前记录用量）。

坦诚说明

Peon 的开发由评估结果把关，并会保留负面结果。我们构建并测量了一个关联实体图（Recall@10 降低 2.9%），随后将其默认关闭。合并过程本就有损，这正是设置情景记忆层并对其进行回归测试的原因。评估工具和已提交的评估记录（npm run eval）可让你在自己的记忆库上验证检索变更。

安全性

• 守护进程仅绑定到 127.0.0.1，并拒绝非回环地址的 Host/Origin 标头 （防止 DNS 重绑定攻击）。
• 在注入边界处对机密信息（API 密钥、令牌、JWT）进行脱敏。
• 防范路径遍历。写入操作使用每个项目独立的锁和临时文件加重命名的原子操作，并会在任何可能造成破坏的操作前自动备份。不会彻底删除任何内容。

许可证

MIT © Vineet Vora

参与贡献 — 欢迎你来帮忙

Peon 由我一人开发和维护，我欢迎大家帮助改进它。提交 Issue、PR、想法、对架构的批评，或者告诉我它在你的机器上哪里出了问题： 这些反馈都很有用。

目前最需要帮助的方面：

• 支持 Windows 和 Linux。 目前守护进程通过 macOS launchd 安装。systemd 和任务计划程序的对应方案需要真实用户来测试。
• 集成更多 Agent。 向导支持 11 款应用，但如果能像 Claude Code 集成那样，通过钩子捕获 Codex、Cursor 和其他应用的数据，就能让各处的记忆更丰富。
• 提升检索质量。 评估工具（npm run eval）让实验成本很低：改进合并提示词、更智能地处理信息过时问题，以及值得设为默认选项的本地嵌入模型。
• 基准测试。 在你的代码库上运行令牌 A/B 测试并分享数据，尤其是 Peon 表现不佳的情况。负面结果在这里同样重要。
• 文档和入门体验。 如果 README 或向导让你感到困惑，这就是一个缺陷报告。

请在 github.com/VineetV2/peon-mem/issues 提交 Issue，或直接发送 PR。

项目规约：每项检索或质量变更都必须附带测试和评估记录运行结果 （npm run eval）；负面结果必须记录，不得删除；不得彻底删除用户记忆。npm test 必须保持通过。

---