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 ms（p50）與約 110 ms（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	一個本地網頁介面（`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 + 向量 + 圖譜擴散），並回傳最相關的實體、學習內容、近期動作等。
環境式寫入 – 每次工具使用後，監聽器會記錄動作；「停止」監聽器會評估學習內容的執行程度，並可合成遺漏的 record_* 條目。
儀表板 – UI 顯示實體與弧線的即時圖譜、事件時間軸，以及診斷資訊（哪些學習內容實際改變結果、各工具的延遲、重複檢測）。

快速入門（來自 README）

pip install pmb-ai          # 安裝套件
pmb setup                    # 綁定所選代理（Claude Code、Cursor、…）
pmb warmup                   # 預載入約 450 MB 的嵌入模型
# 重新啟動代理 – 記憶體現在已啟用
pmb stats                    # 查看儲存項目數量
pmb recall "auth decision"   # 即時終端搜尋
pmb dashboard                # 在 http://127.0.0.1:8765 開啟本地 UI

所有指令也可透過 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 自動整合至流行的編碼代理，讓您在不依賴雲端的情況下，跨會話保留專案背景、學習內容與決策。