AI-Chain
AI 工具指南 MemPalace RAG 開源

讓 AI 記住但不把資料送上雲端：MemPalace 的 local-first 記憶系統拆解

AI Agent 的上下文視窗會重置，但團隊決策、程式碼脈絡與對話不該跟著消失。本文從 MemPalace 的 verbatim 儲存、分層檢索、可插拔後端與 MCP 整合出發，實際拆解如何在本機建立可搜尋、可恢復的 AI 記憶層，也整理安裝版本、非互動初始化、模型下載與資料權限等容易踩坑的細節。

分享:
讓 AI 記住但不把資料送上雲端：MemPalace 的 local-first 記憶系統拆解

本文大綱

  1. 為什麼 AI Agent 需要獨立的記憶層
  2. MemPalace 解決什麼問題
  3. 從 verbatim 儲存到分層檢索的架構
  4. 實際安裝、初始化與第一次搜尋
  5. MCP、auto-save hooks 與多 Agent 工作流
  6. Benchmark 怎麼看，以及哪些數字不能過度解讀
  7. 安全性、版本差異與部署前檢查

先說結論：上下文視窗不是記憶

只要使用過 AI coding agent，就很容易遇到同一個斷點：上一個 session 明明已經決定了資料模型、記錄了踩坑原因，下一次對話卻必須重新解釋。把完整對話塞進新的 prompt 不是好解法，因為 token 成本會上升，檢索範圍也會變得模糊；只保留摘要則可能把「為什麼做這個決定」等關鍵細節遺失。

MemPalace 的切入點很直接：把對話與專案資料留在本機，以原文（verbatim）保存，再用語意搜尋找回需要的片段。它不是另一個雲端聊天紀錄服務，而是一個可以由 CLI、MCP server 和 hooks 共同使用的記憶層。這個定位很適合需要長期維持專案脈絡、又不希望原始資料離開工作站的 AI 工作流。

本文以 GitHub 上的 MemPalace/mempalace 為主體查證。查證時 GitHub API 回報約 58,553 顆星、7,508 個 forks，最近一次 push 為 2026-08-22，專案標示 MIT license；實際執行的 PyPI 版本是 3.7.1。星數與活動資料會變動，以下功能與數字以本次查證為準。

MemPalace 的核心模型：Palace、Wing、Room、Drawer

MemPalace 沒有把所有內容丟進一個扁平的向量資料庫。它用一個具象的「宮殿」模型來組織記憶：

  • Palace：整個本機記憶庫。
  • Wing：人、專案或工作範圍，例如一個 repo 或一位 specialist agent。
  • Room：wing 裡的主題區域，例如 general、成本或架構。
  • Drawer：原始內容的最小可取回單位，保留來源與內容脈絡。

這個分層有兩個工程上的好處。第一，搜尋可以先限定範圍，不必每次在整個歷史語料中找相似段落；第二，原始內容和索引可以分開思考，日後替換向量儲存後端時，不必重寫整個上層工作流。

專案 README 明確表示，預設後端是本機 ChromaDB，後端介面位於 mempalace/backends/base.py。除此之外，專案列出 sqlite_exact、Milvus、Qdrant 與 pgvector 等選項；後三者可以連到服務端，代表「local-first」是預設與資料流設計，不等於永遠只能使用單機嵌入式儲存。

另一個重要取捨是「不先摘要」。摘要很適合壓縮上下文，但也會把原始措辭、時間與不確定性折疊掉。MemPalace 先保存 verbatim drawer，再由搜尋、hybrid boosting 或可選的 LLM rerank 決定要把哪些內容帶回新 session。這讓資料保存層與回答生成層保持分離。

安裝：先固定可取得的版本

README 的 develop 分支徽章顯示 3.8.0，但本次查證 PyPI 最新可安裝版本與 GitHub latest release 都是 3.7.1。因此不要直接把 README 的開發中版本當成已發布套件；要重現本文指令，可使用：

uv tool install mempalace==3.7.1
mempalace --version

實測 uvx --from mempalace==3.7.1 mempalace --help 可以正常啟動，CLI 目前提供 init、mine、sweep、search、wake-up、mcp、serve、status 等命令。專案本身也建議用 uv tool install 或 pipx，避免 ChromaDB、NumPy、gRPC 等依賴污染全域 Python 環境。

如果使用 Docker，README 提供 multi-arch image：

docker pull ghcr.io/mempalace/mempalace:latest
docker run -i --rm -v mempalace-data:/data \
  ghcr.io/mempalace/mempalace

/data 會保存 palace、設定與 embedding model cache。Linux 使用 bind mount 時，容器以 uid 1000 執行，來源目錄必須可讀；不要看到 PermissionError 就直接用 --user 覆蓋，因為那可能讓容器無法寫入 /data。

第一次使用：初始化、挖掘、搜尋

最短的 CLI 路徑如下：

# 對專案目錄建立記憶結構，--yes 避免互動確認，--no-llm 不嘗試連外部模型
mempalace --palace ~/.mempalace/palace init ~/projects/myapp --yes --no-llm

# 將專案檔案寫入 palace
mempalace --palace ~/.mempalace/palace mine ~/projects/myapp

# 搜尋一個設計決策
mempalace --palace ~/.mempalace/palace search "why did we switch to GraphQL"

# 為新的 session 載入 L0 + L1 wake-up context
mempalace --palace ~/.mempalace/palace wake-up

這裡有一個容易忽略的 CLI 細節：--palace 是全域參數，應放在子命令之前。第一次執行 init 時，如果不加 --yes，CLI 會讓使用者確認自動偵測的 rooms；在 CI、容器或自動化 hook 中，應使用 --yes，而沒有 Ollama 時則加上 --no-llm。

我用臨時目錄建立一個只含一行決策紀錄的專案做實測。mine 成功處理 1 個檔案，第一次使用時下載約 79.3 MB 的 all-MiniLM-L6-v2 embedding 模型；接著 search "why did we switch to GraphQL" 找回正確檔案，輸出同時顯示 cosine similarity 與 BM25 分數。這個結果也說明第一次執行較慢不一定是掛住，embedding model 需要先下載並快取。

對話資料則可以用 conversation mode：

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

mempalace search "我們為什麼改用這個資料庫" --wing myapp

README 也列出 sweep，用來補捉主要 miner 沒有處理到的逐訊息內容；它會保留每一則 user/assistant message，並以可重複、可恢復的方式執行。對需要保留細粒度審計脈絡的專案，這比只保存整個 session 的粗粒度 chunks 更容易定位。

Embedding 與資料邊界

預設路徑不需要 API key，embedding 在本機執行。README 提到 onboarding 可選 embeddinggemma-300m 或 all-MiniLM-L6-v2；前者涵蓋 100 多種語言但約需要 300 MB 磁碟，後者較小、偏英文。若改用本機或 LAN 上的 OpenAI-compatible /v1/embeddings endpoint，也可以把 embedding 工作移到自建服務，但切換向量空間後必須執行 mempalace repair rebuild-index。

這裡應該把「資料不離開機器」拆成三件事檢查：

  1. 內容傳輸：預設 local embedding 不需要雲端 API。
  2. 模型下載：第一次安裝仍需要下載套件與模型；若是嚴格隔離環境，必須預先準備 cache。
  3. 可選整合：若設定外部 embedding endpoint、外部 LLM rerank 或遠端 backend，資料邊界會依設定改變。

因此，local-first 是可驗證的部署選擇，不是「設定任何模式都不會送資料」的保證。團隊導入前仍應檢查 config.json、環境變數、Docker volume 與 MCP client 的 mount 路徑。

MCP 與 AI Agent 工作流

MemPalace 的價值不只在 CLI。README 宣稱目前有 44 個 MCP tools，覆蓋 palace 讀寫、knowledge graph、cross-wing navigation、drawer 管理、agent diary，以及透過 logstream 與 artifact handoff 進行 agent coordination。這些工具讓 agent 可以在需要時查記憶，而不是把整個專案歷史永久塞進 system prompt。

以 Claude Code 類型的 MCP client 為例，Docker stdio 設定需要注意兩點：

{
  "mcpServers": {
    "mempalace": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "mempalace-data:/data",
        "-v", "/absolute/path/to/.claude/projects:/transcripts:ro",
        "ghcr.io/mempalace/mempalace"
      ]
    }
  }
}

第一，JSON-RPC 走 stdin，所以 Docker 需要 -i；第二，MCP client 不一定會展開 ~ 或 $HOME，應使用絕對路徑，而且後續命令看到的是容器內的 /transcripts，不是主機上的原始路徑。只 mount 了 /data 而沒有 mount transcript 目錄時，server 不可能挖掘主機上看不到的檔案。

Auto-save hooks 則是另一條路：README 提供 Claude Code、Codex CLI 與 Cursor IDE 的 hooks，讓 session 定期保存，並在 context compression 前建立快照。這解決的是「記憶何時寫入」問題；MCP 解決的是「agent 何時讀取」問題。兩者一起使用，才比較接近可持續的工作流。

Benchmark：數字很漂亮，仍要看測量邊界

MemPalace README 提供 LongMemEval 500 題的 retrieval recall：raw semantic search 為 96.6% R@5，不需要 LLM 或 API；hybrid v4 在 held-out 450 題為 98.4%；加入 LLM rerank 則標示至少 99%。另外也列出 LoCoMo、ConvoMem 與 MemBench 的結果。

這些數字可以支持「檢索層值得研究」的主張，但不能直接等同於「所有問答都 99% 正確」。README 自己也提醒不同專案使用不同資料切分與指標，不能把 retrieval recall 和 end-to-end QA accuracy 放在同一欄直接比較。實際導入時，至少要回答三個問題：

  • 你的資料型態是否接近 benchmark 的對話與長期記憶？
  • 你需要的是找回原文，還是需要模型根據原文做正確回答？
  • 你的延遲、磁碟與 embedding 模型大小預算是多少？

比較務實的做法是先用自己的歷史 session 建立小型 evaluation set，測 top-k 找回率、誤召回率、首次查詢延遲與索引更新時間，再決定是否啟用 hybrid 或 LLM rerank。

Knowledge graph 與多 Agent 協作

除了向量檢索，MemPalace 也包含以 local SQLite 為後端的 temporal entity-relationship graph，可以新增、查詢、失效化關係並查看 timeline。這對「某個決定在哪段時間有效」這種問題特別有用，因為單純相似度搜尋不一定能處理時間有效區間。

多 Agent 工作流則可以將每個 specialist agent 放在自己的 wing 與 diary。這種 namespace 設計的重點不是把 agent 變得更聰明，而是避免不同角色的中間狀態混成一個無法管理的上下文池。當 agent 需要交接時，logstream event 與 artifact handoff 可以提供比複製整段對話更明確的介面。

適合誰，以及目前的限制

MemPalace 值得優先試用的情境包括：

  • 長期維護同一個 codebase，常需要找回決策與歷史脈絡。
  • 使用 Claude Code、Codex CLI、Cursor 或 MCP-compatible client。
  • 對敏感程式碼、內部文件或個人對話，希望預設留在本機。
  • 想把記憶保存、檢索、agent 協作拆成可替換元件。

但它不是零成本方案。第一次 embedding 需要下載模型；大規模資料仍需要規劃磁碟、索引重建與備份；如果選擇 Qdrant、pgvector 或遠端 embedding，部署複雜度與資料治理責任會增加。Android/Termux 原生安裝目前也不是支援路徑，README 建議在 Debian PRoot container 中執行。

另外，專案目前的 GitHub 預設 branch 是 develop，而 latest release / PyPI 版本落後於 README 顯示的開發中版本。正式部署時應固定套件版本與 Docker image digest，並在升級前備份 palace 與 transcripts，不要只依賴 latest。

結語：把記憶當成基礎設施，而不是 prompt 技巧

AI Agent 的記憶問題，最後通常不是再寫一段更長的 system prompt 就能解決。你需要一個能持續寫入、可範圍化檢索、保留原文、能在 session 中斷後恢復的資料層。MemPalace 用 Palace/Wing/Room/Drawer 的組織模型、local-first embedding、可插拔 backend、MCP tools 與 auto-save hooks，把這個資料層包成一個可執行的工具。

它最值得注意的地方不是 README 上某一個 benchmark 數字，而是把「資料保存」和「模型回答」拆開：先把可追溯的內容留住，再讓不同的檢索策略或模型按需讀取。對 AI Chain 讀者而言，建議從單一專案、單一本機 palace 開始，先驗證 mine → search → wake-up 是否真的減少重複說明，再逐步接上 MCP、hooks 與多 Agent namespace。

查證來源

  • GitHub repository：https://github.com/MemPalace/mempalace
  • GitHub API repository metadata：https://api.github.com/repos/MemPalace/mempalace
  • PyPI package：https://pypi.org/project/mempalace/
  • LongMemEval benchmark methodology：repository 內的 benchmarks/BENCHMARKS.md

本文中的星數、forks、更新時間、release 與 CLI 實測結果，均以 2026-08-23 這次自動查證為準；GitHub、PyPI 與專案文件後續變更時，請重新驗證。