AI 编码 Agent 总记不住项目上下文？用 PMB 装个本地记忆层一步到位
你有没有遇到过这个场景：Claude Code 刚刚帮你重构了一个模块，你关掉终端再开一个新会话，它对你的项目结构、你之前的决策偏好、甚至你刚教它的那几条规则全都忘得一干二净。
你不得不每隔几个小时就重新喂一遍上下文：「我们用的是 pnpm 不是 npm」「测试在 __tests__ 目录下」「API base URL 是 staging 的」。
这不是你教得不够多——是 AI 编码 Agent 天生没有长期记忆。每一次新会话都是一张白纸。
痛点对比：AI Agent 的记忆困境
| 场景 | 传统方案 | PMB 方案 |
|---|---|---|
| 项目结构记忆 | 手动写 CLAUDE.md / CURSORRULES | Agent 自动维护实体图+项目索引 |
| 决策偏好持久化 | 用 Notion 或 Markdown 手工记录 | record_keyed_fact() 即时存档，带时间旅行 |
| 跨 Agent 共享 | Cursor 的记忆 Codex 读不到 | 同一 SQLite 文件，所有 MCP Agent 共享 |
| PDF 文档参考 | 每次重传文件或复制粘贴 | pmb index pdf paper.pdf 自动分块+嵌入 |
| 会话恢复 | 从零解释当前进展 | prepare() 返回最近活动+未完成目标 |
| 延迟 | 手动搜索文件——秒级 | 6-16 ms 单次 MCP 调用 |
| API 依赖 | OpenAI Memory API（按 Token 收费） | 零 API Key，全本地 |
快速上手：两条命令搞定
安装只需要一个 PyPI 包：
pip install pmb-ai
然后执行初次配置：
pmb setup
这个命令会自动检测你本地已安装的 AI 编码 Agent（Claude Code、Cursor、Codex CLI、Windsurf、Zed 等都支持），为它们配好 MCP 配置。重启 Agent 后，它就有了记忆。
如果你想用多个 Agent 共享同一份记忆：
pmb connect claude --workspace personal pmb connect cursor --workspace personal
Claude Code 和 Cursor 现在读写的是同一个 SQLite 数据库文件——你在 Claude 里教的规则，Cursor 那边直接就能用。
核心功能拆解
1. Agent 用 prepare() 获取完整的项目上下文
PMB 最核心的 MCP 工具是 prepare()。当 Agent 收到一个新任务时，它调用这个工具获取以下信息：
prepare("修复上周二的 LoadGuard 定价 Bug")
返回的数据结构（70ms p50 以内包含）：
- project_context：与 LoadGuard 相关的 12 个事件、4 条规则（含「NEGOTIATE/SKIP 阈值不低于 25%」）、3 个决策、2 个未完成目标
- lessons：与「定价」直接匹配的程序性规则，每条带
surface_id供 Agent 确认 - recent_activity：过去 24 小时的决策/编辑/完成记录
- open_goals：当前正在推进的目标
- active_arcs：项目正在进行中的叙事线
Agent 收到这些信息后，直接定位到 src/engine/verdict-policy.ts 第 142 行，不需要再问「这个项目的目录结构是什么样的」。
2. 记忆写入——Agent 在干活的同时自动积累
Agent 在工作的过程中会自动记录以下三类信息（可在 pmb config 中开关）：
决策：当 Agent 在多个方案之间做了选择（「我们用 A 方案而非 B 方案因为性能更好」），log_decisions 自动存档。
规则：当你告诉 Agent「永远不要在 TypeScript 中使用 any」或「修复 LoadGuard 时不要把折扣降到底」，log_lessons 自动保留为可检索的程序性规则。
完成记录：目标完成后，prepare() 会把前后对比写入记忆，以后查询类似问题时会作为参考返回。
如果你想手动记录一个事实：
record_keyed_fact("user", "city", "Warsaw")
record_keyed_fact("pricing_rule", "min_discount", "25%")
PMB 使用 bge-m3 多语言嵌入模型，英语查询「where do I live」也能找到 user.city = Warsaw。
3. 文档摄入——用自然语言搜索 PDF
PMB 可以索引 PDF 文件和源代码目录：
pmb index pdf paper.pdf pmb index project . pmb index pdf ~/docs --recurse
索引后，Agent 的 recall(query) 工具能通过 BM25 + 向量搜索 + 实体图 + 交叉编码器重排（可选）的多路融合来找到相关内容。写入是异步的——MCP 工具在亚毫秒内返回，嵌入和 LanceDB 插入在后台线程完成。
4. 内置的去重和时间旅行
PMB 的四层去重机制保证记忆不会膨胀：
- 精确文本匹配
- 余弦相似度 ≥ 0.92 → 自动合并
- 余弦 0.80-0.92 → 边界判定（LLM 延迟验证）
- 手动审查（Dashboard UI 内操作）
旧值永远不被删除——通过 keyed_fact_as_of(t) 可以查询任何时间点的历史状态。
5. 检索策略可调
PMB 有 105 个可调参数，但大多数情况下默认值就够用了。几个关键选项：
| 配置项 | 默认值 | 作用 |
|---|---|---|
recall.bm25_weight | 0.7 | BM25 与向量搜索的混合比例 |
recall.ppr_enabled | true | 多跳实体图扩散搜索 |
recall.rerank | false | 是否启用交叉编码器重排 |
embedding.model | paraphrase-multilingual-MiniLM-L12-v2 | 嵌入模型 |
graph.extractor | regex | 实体提取方式（可选 SpaCy/LLM） |
最适合 AI 编码 Agent 的场景是 ppr_enabled=true + top_k=5 + bm25_weight=0.7——语义搜索能找到「LoadGuard 定价」这种跨术语关联，BM25 能精确匹配函数名和变量名。
横向对比：PMB vs 其他 Agent 记忆方案
| 特性 | PMB | MetaBrain | OpenAI Memory API | 手动 CLAUDE.md |
|---|---|---|---|---|
| 部署方式 | MCP Server（本地 stdio） | 独立服务 | 云端 API | 纯文本文件 |
| 检索方式 | BM25+向量+图+重排 | 向量搜索 | OpenAI 内部 | grep |
| 代码库索引 | pmb index project 原生支持 | 需额外配置 | 不支持 | 手动维护 |
| PDF 支持 | 原生分块+嵌入 | 不支持 | 不支持 | 不支持 |
| 时间旅行 | ✅ 内置 | ❌ | ❌ | ❌ |
| 跨 Agent 共享 | 同一 SQLite 文件 | 需配置共享 | 同一账号 | 手动复制 |
| API Key | ❌ 不需要 | ✅ 可能需要 | ✅ OpenAI Key | ❌ 不需要 |
| 响应时间 | 6-16 ms（prepare），35 ms（recall） | 取决于服务 | 网络延迟 | 秒级 |
| 许可 | Apache 2.0 | 待确认 | 按 Token 计费 | — |
| GitHub Stars | 78 | — | — | — |
注意事项
- 版本：目前 v0.3.0，仍在快速迭代中，建议关注 GitHub 更新
- 数据位置：SQLite 文件默认在
~/.pmb/下，想备份或迁移直接cp这个目录即可 - 磁盘占用：取决于索引的内容量，一个中型项目 + 若干 PDF 通常在几十到几百 MB
- HTTP 共享模式：如果需要跨机器或团队共享记忆，可以用可选的 HTTP 模式（Bearer Token 认证），但 99% 的单机使用不需要
- Agent 协作：PMB 不要求 Agent 配合——它通过
hooks install在 Agent 协议层注入记忆读写，Agent 本身不需要任何修改 - 多语言支持：默认嵌入器
bge-m3原生支持 50+ 语言，中文查询也能匹配到英文存储的事实
总结
PMB 解决了一个 AI 编码 Agent 生态中最实际也被最多人默默忍受的问题——会话级遗忘。29 个 MCP 工具、6-16ms 响应、零 API Key，让它成为目前给 Claude Code / Cursor / Codex 装上持久记忆的最轻量方案。
如果你每天都在处理「Agent 又忘记了我的规则」的挫败感，值得花两分钟试一下：
pip install pmb-ai && pmb setup
然后重启你的 Agent——它会记得你。