PMB (Personal Memory Brain) | Local first memory layer

---

PMB 为 Claude Code、Cursor、Codex 以及其他支持 MCP 的 Agent 提供真正的记忆：你上周做出的决策、教给它们的经验、个人信息、项目结构和 PDF。无论重启、升级模型还是切换 Agent，这些记忆都能保留下来——因为它们存储在由你掌控的本地工作区中，SQLite 是持久化的事实来源，可重建的搜索索引也与之并存。

无需 API 密钥。无需订阅。读取时无需调用大模型。只有本地文件。

快速入门

pip install pmb-ai                 # 1. install
pmb setup                          # 2. detect your agent + wire the MCP entry
pmb warmup                         # 3. preload the model (first recall is instant)
# 4. restart your agent, then just talk to it - memory is automatic
pmb stats                          # 5. see what's stored
pmb recall "auth decision"         # 6. search memory from the terminal
pmb doctor                         # 7. confirm everything is wired

就这么简单——你的 Agent 现在能记住信息了。无需账户、密钥，任何数据都不会离开你的设备。

命令名称： CLI 命令是 pmb。通过 pip 安装时，还会获得别名 pmb-ai；通过 npm 安装时（npx pmb-ai setup），命令是 pmb-ai，它会先 安装 Python 包，再运行设置流程。它们是同一个工具——使用安装后提供的命令即可。

链接： pmbai.dev（网站） · docs.pmbai.dev（文档） · 入门指南 · 删除记忆。

---

演示

实际体验——同一个提示词，有记忆和没有记忆时的对比：

You:    fix that LoadGuard pricing bug we hit last Tuesday

Agent:  prepare(message="fix LoadGuard pricing bug")
        ↓ (6 ms)
        → project_context: 12 events about LoadGuard,
          4 lessons (incl. "never lower NEGOTIATE/SKIP under 25%"),
          3 decisions, 2 open goals
        → active_arcs: "LoadGuard verdict-policy refactor (started Tue)"
        → lessons: 1 directly matches "pricing"
        → recent_activity: 8 commits this week

        Looking at src/engine/verdict-policy.ts (you opened it Tuesday
        14:32, last changed Wednesday). The pricing bug is on line 142
        where the bundle fallback tightened below the rate-floor. Per the
        lesson you saved, we never drop the threshold under 25% - restoring
        the guard there.

Agent 没有提问，也没有猜测。它在 6 毫秒内读取了自己的记忆，一开始就掌握了相关信息。

---

为什么选择 PMB

• 本地优先，零配置。 SQLite 保存持久记忆；可重建的搜索索引保留在本地。无需账号、API 密钥、遥测数据，也无需信任云服务。
• 真正用得起来。 在 Claude Code / Codex 中，钩子会在模型思考前注入正确的记忆——你无需记得调用工具。
• 支持多语言，无需设置。 嵌入模型支持 50 多种语言；俄语查询也能找到英文事实。无需按语言配置。
• 原生支持 MCP。 执行一次 pmb connect，即可连接 Claude Code、Cursor、Codex、Windsurf、Zed、VS Code 等。
• 读取速度快。 热缓存下，召回约需 35 毫秒；写入不到 1 毫秒即可返回——记忆时无需调用大模型。
• 如实呈现效果。 仪表板会显示哪些经验教训真正改变了结果，而不是声称「提升了 +X%」。
• 数据公开透明。 pmb export 会将所有内容导出为 Markdown/JSON。Apache 2.0 许可证。

---

查看你的记忆

pmb dashboard 会在 http://127.0.0.1:8765 打开本地的液态玻璃风格网页界面， 展示 PMB 捕获的所有内容——只需正常工作，内容便会自动写入。它仅绑定到 127.0.0.1，因此数据不会离开你的设备。

共有九个标签页：地图（实时实体图谱）、时间线（按项目展示的 git 图谱）、 概览、实体、叙事线（叙事脉络）、经验教训（按规则统计的遵循率、 检测失效经验教训）、重复项（行内合并）、性能（按工具统计延迟）、 召回（调试排序器）。

---

已验证的本地备份

pmb snapshot create --note "before maintenance"
pmb snapshot list
pmb snapshot verify <snapshot-id>
# Stop PMB servers, agent connections, and dashboards before restoring.
pmb snapshot restore <snapshot-id>

快照使用 SQLite 在线备份，包含已提交的 WAL 数据，并记录文件校验和。 恢复前会检查快照，并保存上一状态的已验证副本。在脚本中使用 pmb snapshot list --json。有关适用范围和限制，请参阅备份与恢复。

可以存储哪些内容

# Personal facts that change (time-travel: old values archived, never lost)
record_keyed_fact("user", "city", "Warsaw")

# Project structure - symbols, imports, .gitignore-aware
pmb index project .

# Why each file exists + the intent behind every commit (Haiku-summarised, local)
pmb track modules                # one-line purpose per indexed file
pmb track changes                # new commits: what changed and WHY

# PDFs (research papers, manuals, contracts)
pmb index pdf paper.pdf
pmb index pdf ~/docs --recurse

# Whatever your agent logs as it works: decisions, lessons, completed tasks, goals

PMB 不限制内容类型。只要是 Agent 之后还会用到的文本，PMB 就会记住并检索出来。

Agent 会收到哪些内容

一次 MCP 调用——prepare(message)——即可在 4–16 毫秒内返回合适的内容和详细程度：

字段	内容
project_context	如果消息提及某个项目，则返回完整的项目概览：关键信息、经验教训（需遵循的 RULES）、决策、待办目标、相关实体，以及项目的叙事脉络
lessons	与查询匹配的操作规则；每条规则都带有 surface_id，便于 Agent 之后确认自己是否遵循了规则
recent_activity	过去 24 小时的决策、编辑和完成事项，帮助保持会话连贯
open_goals	进行中的目标，让 Agent 了解你正在推进什么
active_arcs	项目当前所处的叙事脉络

其他需求可使用 recall(query)（混合搜索，热缓存下 35 毫秒）以及 docs/reference/COMMANDS.md 中的另外 27 个工具。

---

工作原理

flowchart LR
    A[Your agent] -->|MCP stdio| B[PMB MCP server]
    B --> C[Engine]
    C -->|read 35 ms| R[Hybrid recall<br/>BM25 + vector + graph + rerank]
    C -->|write under 1 ms| W[Async embed queue<br/>SQLite first, vectors later]
    R --> D[(SQLite)]
    R --> E[(LanceDB)]
    W --> D
    W --> E
    style A fill:#dbeafe,color:#1e3a8a
    style B fill:#ede9fe,color:#5b21b6
    style C fill:#dcfce7,color:#14532d

• 存储 - 每个持久事件都存放在 SQLite 中，它是唯一可信来源。可重建的向量索引存放在旁边的 LanceDB 中。整个工作区都保存在你的磁盘上，可随时复制或导出。
• 召回 - BM25（词法）+ 稠密向量（语义）+ 实体图 + 可选的交叉编码器重排，通过 Reciprocal-Rank-Fusion 融合。
• 写入 - 异步进行。MCP 工具在不到一毫秒内返回；嵌入和 LanceDB 插入在后台线程中完成。
• 去重 - 分为四层：文本完全匹配 -> 余弦相似度 >= 0.92 时自动合并 -> 余弦相似度为 0.80-0.92 时列为待定（之后由 LLM 验证） -> 在仪表板中手动审核。旧值会归档，绝不删除；使用 keyed_fact_as_of(t) 可查看完整历史。
• 多语言 - 无需语言包。 默认嵌入器（paraphrase-multilingual-MiniLM-L12-v2）支持 50 多种语言，因此 где я живу 可以找到存储为 user.city = Warsaw 的键值事实。意图检测依赖可跨语言迁移的英文语义锚点，而冷启动词法路径会根据你自己的流量自动构建。在约 11 种语言中，召回效果依然出色（在 101 条查询的评估中，top-3 ~= 0.9；en/fr/pt/ru 的 top-1 = 1.00）。请参阅 docs/contributing/adding-a-language.md。

---

安装

上面的快速入门已满足大多数人的需求。其他方式：

# From source
git clone https://github.com/oleksiijko/pmb.git && cd pmb
python -m venv .venv && source .venv/bin/activate
pip install -e .
pmb warmup                       # prime the ~450 MB embedder once

连接一个或多个 Agent（全部使用 stdio - 服务作为 Agent 的子进程运行； 无需网络、端口或令牌）：

pmb connect claude-code   # also: codex · cursor · windsurf · gemini · vscode · zed · opencode · continue

让多个 Agent 使用同一份记忆：

pmb connect claude-code --workspace personal
pmb connect cursor      --workspace personal   # both read/write the same workspace

想要在多台机器或团队间共享一份记忆？可选的 HTTP 模式支持 bearer-token 身份验证 - 请参阅 docs/guide/TEAM.md。本地使用无需此模式。

要运行测试？ 使用虚拟环境中的 Python：.venv/bin/python -m pytest （Windows 上使用 .venv\Scripts\python.exe -m pytest）。在虚拟环境之外直接运行 pytest，只会报告缺少 numpy/fastmcp/typer。

---

CLI 速查

# Memory
pmb stats                                   show counts and storage info
pmb recall "query"                          search with full debug
pmb dashboard                               web UI on port 8765 (graph, settings, errors)

# Ingest
pmb index pdf paper.pdf                     extract + chunk + embed
pmb index pdf ~/docs --recurse              entire directory
pmb index project .                         scan codebase
pmb track changes                           summarise commit intent (why)
pmb track modules                           one-line purpose per module
pmb import chatgpt ~/Downloads/export.json  bring existing history

# Continuity & efficiency (opt-in)
pmb resume save                             write .pmb/resume.md (commit it)
pmb resume install                          refresh resume.md at every turn end
pmb health lessons-impact                   which lessons actually help outcomes
pmb memory ledger                           Memory Delta handles this session

# Maintenance
pmb regraph                                 rebuild entity graph
pmb consolidate                             run sleep pass (optional)
pmb compact                                 archive old events
pmb dedupe                                  resolve borderline duplicates

# Hooks (force-feed PMB at the protocol level - no model cooperation)
pmb hooks install claude-code               wire all lifecycle hooks
pmb hooks list                              show what's installed
pmb hooks capabilities                      ambient mechanism each agent supports
pmb hooks uninstall claude-code             remove them
pmb auto-context "fix bug in PMB"           preview per-turn injection
pmb session-restore -m 180                  preview post-compaction restore
pmb lesson-followcheck --dry-run            preview follow-through scoring

# Ambient memory (the write side - memory journals the agent's work)
pmb autowrite --dry-run                     preview ambient auto-write for this turn
pmb ambient-watch .                         ambient auto-write for MCP-only hosts (git observer)
pmb forget-auto                             drop memory the ambient layer wrote itself

# Config
pmb config list                             default tier (25 keys you care about)
pmb config list --pro                       every key, including 80 advanced knobs
pmb config set recall.ppr_enabled true      toggle a feature
pmb connect --rules-only                    refresh CLAUDE.md only

各 Agent 的分步指南：docs/guide/usage.md。完整 参考：docs/reference/COMMANDS.md。

---

Hooks - 不等人询问的记忆

Agent 记忆的难点不在于存储，而在于让 Agent 使用 存储的内容。规则文件中的软性指令常常会被跳过。因此，PMB 在协议层接入 hooks （pmb hooks install claude-code），让每个 hook 都不再依赖模型记得采取行动：

• UserPromptSubmit -> 自动召回。 每条消息都会经过分类（正则表达式、多语言、亚毫秒级），匹配的记忆 - 经验教训、过往决策、召回结果、项目概览 - 会在模型思考之前注入。无关紧要的消息不会注入任何内容。
• PostToolUse -> 后台观察。 Agent 执行的每个工具都会追加到轻量级操作日志中（单条 SQLite INSERT，不调用模型）。读取操作和 ls 会被过滤；编辑、测试和提交则会保留。
• SessionStart -> 恢复会话。 上下文压缩后，Agent 会根据会话记录重建“你上次停下时的状态”，而不是再次询问你。
• Stop -> 跟进 + 后台自动写入。 (a) 它会确定 Agent 实际采取的行动中是否体现了已呈现的经验教训，并以确定性方式标记为已遵循。(b) 如果 Agent 没有调用 record_* 工具，它会根据观察到的行动合成一条活动记录 - 即使 Agent 没有主动记录，实际工作也会被捕获。

无需使用 Agent，即可预览任意功能：pmb auto-context "..."、pmb session-restore -m 180、pmb lesson-followcheck --dry-run、pmb autowrite --dry-run。

环境记忆 - 写入侧

自动召回解决了读取侧的问题；环境记忆则为写入侧做了同样的事——即使 Agent 忘记调用 record_batch，记忆也会记录 Agent 的工作：

• 协同工作。 如果 Agent 本轮已经调用过 record_* 工具，环境记忆就会保持静默；它只会填补空缺。
• 按结果评分，而非按变更量。 只有结果达到质量门槛（测试通过、修复故障、执行部署）时，才会记录本轮，而不是仅根据文件数量判断。
• 诚实且可撤销。 每条环境记忆条目都会标记为 source=autowrite，在仪表板中显示为自动生成，并可通过 pmb forget-auto 移除。默认开启；使用 pmb config set autowrite.enabled false 可禁用。
• 适用于所有宿主。 Claude Code（钩子）、Codex（pmb codex-notify）、仅支持 MCP 的宿主（如 Cursor/Zed/VS Code）（Git 观察器，pmb ambient-watch .）。使用 pmb hooks capabilities 查看你的环境。

默认情况下，综合内容采用基于模板的方式生成（即时完成，不需要模型）。使用 pmb config set autowrite.synthesizer llm:ollama 或 llm:openai，即可选择本地/API/CLI 模型摘要（它设有超时机制，超时后会回退到模板）。

自我改进循环

每条呈现的经验都会带有一个 surface_id。后续跟进会以两种方式记录：Agent 通过 mark_lesson_followed(surface_id, True) 确认，停止钩子则根据已记录的活动推断。随后，Lessons 选项卡会按规则显示：展示次数、跟进次数、★ USEFUL（已跟进至少 2 次）、? UNVERIFIED（已展示但未确认），以及仅在规则被反复忽略（至少 2 次）时显示的 💀 DEAD。你可以看到哪些规则有帮助，并清理无用规则。

---

设置 - 你关心的 25 项，以及你不关心的 80 项

PMB 有 105 个可调参数。影响日常体验质量的 25 项属于默认级别（pmb config list）。其余参数是内部权重和实验性标志，通过 --pro 隐藏，以便列表易于浏览。所有高级键仍可通过 pmb config get 读取，并通过 pmb config set 写入——仅从 list 中隐藏，不会限制访问。

键	默认值	功能
recall.top_k	5	召回返回的结果数量
recall.bm25_weight	0.7	BM25 与向量的混合权重（1.0 = 纯 BM25）
recall.ppr_enabled	true	多跳图扩散，由意图控制
recall.keyed_fact_boost	0.35	个人查询中个人属性事实的优先程度
recall.rerank	false	始终启用的交叉编码器（会导致 LoCoMo 性能回退，保持关闭）
embedding.model	paraphrase-multilingual-MiniLM-L12-v2	向量模型
graph.extractor	regex	regex / spacy / llm:claude / llm:openai / llm:ollama / llm:codex
mcp.record_batch_async	true	即发即弃式写入（亚毫秒级返回）
agent.apply_lessons	true	Agent 在采取行动前呈现经验
dedup.enable	true	启用全部四层去重
decay.factor_per_day	0.985	重要性的半衰期
chat.model	haiku	pmb-chat 的默认模型

---

数据

预热状态下召回 p50 / p95	35 ms / 110 ms
预热状态下的 prepare(message)	4-16 ms
record_batch_async	< 1 ms
MCP 冷启动	3.7 s
LoCoMo recall@10 (n=10)	94.5 %
多语言 mega-stress top-10（900 个查询）	99.2 %

# Reproduce locally
python scripts/benchmarks/benchmark_locomo.py --n-conversations 10
python scripts/benchmarks/mega_stress_test.py

---

隐私

• 默认 100 % 离线。引擎不会进行网络调用，也没有任何遥测数据——没有 PMB 服务会连接到家中服务器。
• 工作区 = ~/.pmb/<name>/ 下的一个目录。你可以将它复制到 Dropbox、推送到 Git，或通过 USB 驱动器分享。由你决定。
• 写入时会自动遮盖机密信息（OpenAI / Anthropic / AWS / Stripe / GitHub 密钥；可配置）。
• 采用 Apache 2.0 许可证。欢迎分叉。

---

常见问题

PMB 会调用大模型吗？ 读取时：绝不会。写入时：默认绝不会。可选： pmb consolidate 可以调用本地 Ollama、Claude CLI、Anthropic 或 OpenAI 进行处理，写入简短反思——需主动选择启用。

费用是多少？ $0。PMB 不提供服务。

Agent 需要了解 PMB 吗？ 执行 pmb connect 后，规则会自动追加到 CLAUDE.md / AGENTS.md。默认配置文件会开放 10 个核心 MCP 工具（包括 prepare() 先读取模式）；此外还有用于摄取和管理的更广泛配置文件。

这会拖慢我的 Agent 吗？ 除 recall（预热后为 35-110 毫秒）外，所有工具的返回时间都在个位数毫秒内，低于人类感知阈值。

两个 Agent 可以共享同一份记忆吗？ 可以——将它们指向同一个工作区即可。 SQLite WAL 和 10 秒忙碌超时可处理并发写入。

如何清除一条事实？ pmb forget <ulid> 会将其归档（不纳入召回，但可恢复）。 彻底删除：pmb delete <ulid> --hard。

支持 Windows 吗？ 支持——已在 Windows 11、macOS 14、Ubuntu 22.04 上测试。支持西里尔字母路径，并可处理控制台编码。

支持 PDF / 代码 / Markdown 吗？ pmb index pdf paper.pdf、pmb index project .、 pmb import markdown ~/notes/、pmb import chatgpt path.json。

冷启动很慢。 首次召回时会加载嵌入模型（约 3 秒）。运行一次 pmb warmup，或让预热线程在后台处理。

路线图？ 请参阅 docs/ROADMAP.md：litestream 备份、可选 云同步（自带存储桶）、tree-sitter 项目索引、图像 OCR。

---

贡献

欢迎提交问题和 PR。我们只有一位全职维护者；进行大型改动前，请先发起讨论，以便我们就方向达成一致。

git clone https://github.com/oleksiijko/pmb.git && cd pmb
python -m venv .venv && source .venv/bin/activate
pip install -c requirements-dev.lock -e ".[dev,crypto]"
python scripts/prewarm_models.py
pytest                  # full suite, ~4 minutes
pytest -k recall        # fast subset, ~12 s

开发命令

bash scripts/test.sh                 # whole suite (CI-equivalent)
bash scripts/test.sh tests/recall    # a subset (any pytest args pass through)
bash scripts/codeql_local.sh         # run CI's CodeQL security-extended locally
bash scripts/install-dev-hooks.sh    # pre-commit hook: ruff + CodeQL before each commit

scripts/codeql_local.sh 会在首次运行时自动安装 CodeQL bundle，并运行 CI 使用的 完全相同的套件，因此可以在本地发现安全问题，而不是等到推送后才发现。通过 git commit --no-verify 可跳过 pre-commit 钩子（或者使用 SKIP_CODEQL=1 仅跳过扫描）。

许可证：Apache 2.0。