oleksiijko/pmb

Local-first persistent memory for AI coding agents (Claude Code, Cursor, Codex) over MCP. Decisions, lessons and facts live in one SQLite file on your disk. Offline, multilingual.

PMB – AI 编程代理的本地优先记忆

这是什么 – PMB（发音为“p-m-b”）是一个 Python 包，为编写代码的 LLM 代理（Claude Code、Cursor、Codex、Gemini 等）提供一个持久、可搜索且完全存在于您机器上的记忆。记忆存储在 SQLite 数据库中（事实来源），并在 LanceDB 中带有可选的向量索引，通过 Model-Context-Protocol (MCP) 暴露给代理。

为何重要 – 如今许多 AI 辅助编程工具在进程重启后就会忘记一切，迫使您重复决策、教训和项目上下文。PMB 会自动捕获这些事实，进行索引，并在模型生成响应之前将相关片段注入回代理，全程无需任何云端调用或 API 密钥。

主要功能（如 README 中所述）

功能	您会得到什么
本地优先存储	所有事件、事实和嵌入都被写入 `~/.pmb/<workspace>/` 中的 SQLite 文件。读取不需要网络流量；写入在毫秒以下。
混合回忆	查询由 BM25 词汇搜索、密集向量相似度和基于图的扩散（Reciprocal-Rank-Fusion）融合来回答。典型的暖路径延迟：~35 毫秒 (p50) 和 ~110 毫秒 (p95)。
MCP 原生集成	一个微小的 MCP 服务器作为代理的子进程运行。标准的 `prepare(message)` 调用返回结构化的负载（`project_context`、`lessons`、`recent_activity`、`open_goals`、`active_arcs`）。
自动摄取	`pmb index project .` 扫描您的代码库，提取符号、导入和文件意图。`pmb index pdf …` 提取并分块 PDF。`pmb track …` 记录提交意图和模块用途。
环境（自动写入）记忆	钩子观察代理的工具使用（编辑、测试、提交），并在代理忘记调用 `record_*` 工具时写入轻量级的日志条目。
仪表板 UI	本地 Web UI（`pmb dashboard`）将记忆可视化为实体图、时间轴、教训影响、重复项和性能统计。
多语言嵌入	使用 `paraphrase-multilingual-MiniLM-L12-v2`（涵盖 50 多种语言），因此俄语、法语等查询可以检索英语事实。
零配置，零成本	无云账户、无 API 密钥、无订阅。所有数据都保留在您的磁盘上；您可以导出为 Markdown/JSON。
隐私与导出	机密信息在写入时会被遮蔽；整个工作区可以被复制、同步到 Dropbox 或进行版本控制。
可扩展配置	105 个可调旋钮；默认暴露 25 个（`pmb config list`）。高级标志隐藏在 `--pro` 之后。

工作方式（高层流程）

设置 – pip install pmb-ai && pmb setup 检测目标代理并安装 MCP 钩子。
摄取 – 文件、PDF、git 提交和明确的 record_* 调用被写入 SQLite；嵌入被排队并异步插入 LanceDB。
回忆 – 当代理发送 prepare(message) 时，PMB 运行混合搜索（BM25 + 向量 + 图扩散）并返回最相关的实体、教训、近期动作等。
环境写入 – 在每次使用工具后，钩子会记录动作；“stop”钩子会评分教训的后续执行，并可以合成缺失的 record_* 条目。
仪表板 – UI 显示实体和弧线的实时图表、事件时间轴以及诊断（哪些教训实际改变了结果、每个工具的延迟、重复检测）。

快速开始（来自 README）

pip install pmb-ai          # install the package
pmb setup                    # wire the chosen agent (Claude Code, Cursor, …)
pmb warmup                   # preload the ~450 MB embedder
# restart the agent – memory is now active
pmb stats                    # see counts of stored items
pmb recall "auth decision"   # ad-hoc terminal search
pmb dashboard                # open the local UI at http://127.0.0.1:8765

所有命令也可以通过 pmb-ai 别名 (npm) 或作为 Python 模块使用。

典型用例

长期运行的代码库 – 在多次会话中保留决策、架构规则和错误修复理由，无需重新解释。
跨代理连续性 – 从 Claude Code 切换到 Cursor；相同的 SQLite 工作区为两者提供记忆。
研究密集型项目 – 索引 PDF 并在编写代码时即时检索相关段落。
团队级共享上下文 – 可选的 HTTP 模式让多名开发人员将其代理指向一个共同的工作区（受验证保护）。
教训影响分析 – 仪表板告诉您代理实际遵循了哪些“规则”，帮助您修剪无用或嘈杂的教训。

限制与注意事项（如所述或暗示）

读取路径仅限离线 – 回忆时不调用 LLM；质量取决于嵌入器和混合排名。
嵌入模型大小 – 默认的多语言 MiniLM 模型（~450 MB）必须加载一次（pmb warmup）。
可选的基于 LLM 的功能 – 一些可选命令（pmb consolidate、自动写入合成）可以调用本地 Ollama/Claude/OpenAI 模型，但默认为禁用。
本地资源使用 – SQLite + LanceDB 索引占用磁盘空间；庞大的代码库或大量 PDF 会增加工作区的大小。
代理特定钩子 – 完全的优势需要代理支持 MCP 钩子；README 列出了支持的主机（Claude Code、Cursor、Codex 等）。

许可与社区

Apache 2.0 – 免费使用、修改和重新分发。
MCP 注册 – 列在 Model-Context-Protocol 注册表中，可被其他支持 MCP 的工具发现。
文档与 CI – 在线文档位于 docs.pmbai.dev，CI 徽章显示每次推送都通过测试。

结论

PMB 是一个真正的开源项目，解决了 AI 辅助开发人员的一个具体痛点：缺乏持久、低延迟的记忆。通过将所有内容存储在本地 SQLite 中，提供快速的混合搜索，并通过 MCP 自动连接到流行的编程代理，它让您可以在会话之间保留项目上下文、教训和决策，而无需任何云依赖。