MemPalace：本地優先的 AI 記憶系統

1. 專案概覽

MemPalace 是一套本地優先、開放原始碼的 AI 記憶系統，原樣儲存 AI 代理的對話歷史，並以語意搜尋加以檢索，解決程式開發代理與聊天機器人在工作階段結束或上下文視窗壓縮後就「忘光一切」的問題。

2. 背景與定位

MemPalace 是為了解決一個非常具體的痛點而生：長時間運行的代理工作階段（例如在 Claude Code 這類工具中）在壓縮之後會失去較早的上下文，迫使代理即使在先前已工作數小時後，仍要問「我們今天要做什麼？」。其核心使命是結合多數記憶工具往往必須取捨的兩件事——以完整保真度儲存一切，以及立即找到正確的那段內容，包括從模糊、只記得一半的查詢中找出來。

在架構上，它借鑑了 Zettelkasten 方法（小型、互相參照的索引卡），將記憶組織成 wings（人物／專案）、rooms（主題）、closets（壓縮後、AI 可讀的索引條目）與 drawers（原始逐字內容）的階層。這與多數記憶框架有兩點不同：它從不摘要或改寫所儲存的內容（檢索結果一律回傳原始文字），而且其檢索後端是可插拔的，而非綁定單一向量資料庫，因此團隊可以先從純本地開始，再遷移到伺服器支援的儲存後端，而不必改變系統其餘部分的運作方式。

3. 功能分類

🗂️ Palace 儲存 — 跨 wings/rooms/closets/drawers 的逐字、結構化儲存；核心操作包括 mine、search、wake-up 與逐訊息 sweep；目的：保留完整對話保真度，同時維持可瀏覽性。
🔌 可插拔後端 — 支援 5 種儲存：chroma（預設、嵌入式）、sqlite_exact、milvus、qdrant、pgvector；目的：讓使用者從本地開始，並在無需重新設計架構的情況下擴展到共享伺服器。
🕸️ 知識圖譜 — 具有效性時間窗的時序實體關係圖，由本地 SQLite 支援；支援新增／查詢／失效／時間軸操作；目的：追蹤事實與關係如何隨時間變化，而不只是靜態快照。
🔧 MCP 伺服器與工具 — 45 個 MCP 工具，涵蓋 palace 讀寫、知識圖譜操作、跨 wing 導覽、drawer 管理、代理日誌與多代理協調；目的：將記憶作為一等能力，提供給任何相容 MCP 的代理。
🪝 自動儲存掛鉤 — 適用於 Claude Code、Codex CLI 與 Cursor IDE 的掛鉤，會定期儲存，並在上下文壓縮前儲存；目的：自動擷取工作階段，無需手動執行「請記住這個」的步驟。
🤖 多代理支援 — 每個專業代理都有自己的 wing 與日誌，可在執行期間透過 mempalace_list_agents 探索；目的：讓多個代理共享一套記憶系統，而不互相污染彼此的上下文或系統提示。

4. 重點特色

逐字檢索，而非摘要 — 搜尋結果回傳原始文字，因此過程中不會因有損壓縮而遺失任何內容。
本地優先且可離線運作 — 核心基準測試路徑（LongMemEval 上 R@5 達 96.6%）在任何階段都不需要 API 金鑰、不需要雲端，也不需要呼叫 LLM。
可重現的基準測試結果 — 每個已發表的數字（LongMemEval、LoCoMo、ConvoMem、MemBench）都附有可從儲存庫重現結果的精確指令。
可選的混合式 + LLM 重排序管線 — 關鍵字加權、時間鄰近性加權與偏好模式擷取可將保留資料集的召回率推升至 98.4%，而 LLM 重排序選項可達 ≥99%，且與模型無關（已使用 Claude 測試，並透過 Ollama Cloud 使用開放模型測試）。
靜默背景運作 — 依目前設計，日誌寫入與 palace 歸檔在背景掛鉤／子代理中執行，而非在可見的聊天中執行，藉此減少因重新傳輸狀態更新而產生的 token 開銷。
多架構 Docker 支援 — 已發布的容器映像可在 amd64 與 arm64（包括 Apple Silicon）上原生執行，並提供獨立的 CUDA 建置供 GPU 工作負載使用。

5. 依角色的使用案例

一般開發者 — 跨工作階段保留 AI 程式開發助理的專案上下文，不必在每次壓縮或重啟後重新解釋決策。
資料／研究科學家 — 以語意方式挖掘並搜尋大量過往對話或筆記，並將本專案自身的檢索基準測試重現為參考實作。
專案經理／團隊 — 將共享的 Claude Code 逐字稿挖掘到一個共用 palace（一個「共享大腦中樞」），讓團隊知識與決策集中在一個可搜尋的地方，而不是散落在個別聊天歷史中。

6. 快速入門

找到你需要的內容 — 瀏覽文件網站以取得指南與參考資料：

https://mempalaceofficial.com/guide/getting-started.html

安裝／整合 — 建議透過 uv 進行隔離安裝，然後初始化一個 palace：

uv tool install mempalace
mempalace init ~/projects/myapp
mempalace mine ~/projects/myapp
mempalace search "why did we switch to GraphQL"

也可以透過安裝本專案的 skills 來使用代理引導式設定：

npx skills add MemPalace/mempalace

參與貢獻 — 在提出 PR 之前，請先閱讀貢獻指南：

https://github.com/MemPalace/mempalace/blob/main/CONTRIBUTING.md

7. 專案結構

mempalace/
├── backends/          # 可插拔儲存後端實作（chroma、qdrant、pgvector、...）
├── data/              # 隨附的資料資產
├── i18n/              # 國際化資源
├── instructions/      # 面向代理的指令集
├── integrations/      # 第三方工具整合
├── sources/           # 用於挖掘的擷取來源
├── cli.py             # `mempalace` 命令列進入點
├── mcp_server.py       # MCP 伺服器實作（工具暴露）
├── knowledge_graph.py  # 時序實體關係圖
├── palace.py           # 核心 palace 讀寫邏輯
├── miner.py / convo_miner.py  # 內容與對話挖掘管線
├── searcher.py         # 語意搜尋／檢索邏輯
└── onboarding.py        # 首次執行設定與嵌入模型選擇

其他值得認識的頂層目錄：benchmarks/（可重現的基準測試腳本與結果）、hooks/（支援編輯器／代理的自動儲存掛鉤實作）、skills/（可安裝的代理技能）以及 website/（文件網站原始碼）。

8. 相關生態系

上游相依項目：ChromaDB（預設向量儲存），並可選支援 Milvus、Qdrant 與 pgvector；ONNX Runtime 與嵌入模型（all-MiniLM-L6-v2、embeddinggemma-300m）用於本地嵌入。
代理／編輯器整合：Claude Code、Codex CLI、Cursor IDE、Gemini CLI 與 Antigravity，透過 Model Context Protocol（MCP）連接。
互補工具：任何相容 OpenAI 的 /v1/embeddings 端點（LM Studio、llama.cpp、vLLM、Ollama）都可用於遠端或 GPU 加速嵌入，取代本地運算。

9. 授權條款

✅ 在 MIT 授權條款下，允許商業使用、修改、散布與私人使用。
❌ 本授權不提供任何擔保，也不為作者承擔任何責任。
ℹ️ 在軟體的副本或實質部分中，必須保留原始著作權與授權聲明。

10. 常見問題

問：MemPalace 需要 API 金鑰或雲端服務才能運作嗎？
答：不需要。核心基準測試路徑，包括 LongMemEval 上 96.6% 的 R@5 原始檢索分數，完全在本地以預設的 chroma 後端執行，且不呼叫任何 LLM。

問：MemPalace 使用哪個向量資料庫？
答：預設使用 ChromaDB，並可插拔支援 sqlite_exact、milvus、qdrant 與 pgvector，可透過 --backend <name> 或 MEMPALACE_BACKEND 選擇。

問：MemPalace 可以在沒有本地 Python 環境的情況下執行嗎？
答：可以，透過已發布的多架構 Docker 映像：

docker pull ghcr.io/mempalace/mempalace:latest

問：如何在壓縮後保留 Claude Code 工作階段的上下文？
答：依照 Claude Code 保留設定檢查清單所述，接上自動儲存掛鉤，然後用以下指令回填現有逐字稿：

mempalace mine ~/.claude/projects/ --mode convos

問：除了 GitHub 儲存庫之外，還有官方網站嗎？
答：唯一的官方來源是 GitHub 儲存庫、PyPI 套件（mempalace）以及 mempalaceofficial.com 上的文件；其他名稱相似的網域與本專案無關。

11. 快速連結

儲存庫：https://github.com/MemPalace/mempalace
官方文件：https://mempalaceofficial.com
貢獻指南：https://github.com/MemPalace/mempalace/blob/main/CONTRIBUTING.md
社群：https://discord.com/invite/ycTQQCu6kn

12. 總結

MemPalace 為任何建置或使用長時間運行 AI 代理的人填補了一個實際缺口：它保留完整、逐字的對話歷史，同時維持快速且精確的搜尋，而不必在「儲存一切」與「找到任何內容」之間被迫取捨。整合 Claude Code、Codex 或 Cursor 這類程式開發代理的開發者，可獲得持久、具可重現基準測試的記憶，且沒有強制性的雲端相依；而團隊則可隨著需求成長，將同一套系統從私有的本地 palace 擴展到共享後端。