工具

MemPalace 實測:本機優先的 AI 記憶系統,架構與程式碼拆解

58.5k stars、LongMemEval R@5 達 96.6%、零 API 呼叫。MemPalace 以「宮殿式」分層索引解決長對話遺失問題,本文附程式碼與架構分析。

字級

GitHub 上 mempalace/mempalace 這個專案最近頻繁登上熱門榜。58.5k stars,主打開源、本機優先、為 AI Agent 加裝長期記憶。我親自安裝並跑了一遍,把架構與程式碼都拆開來看。

它解決什麼問題

長對話是 LLM 的硬傷。Claude 200k context window 聽起來很大,但實際用過會發現:對話拉到 50 輪以上,前面討論過的技術選型、決策依據幾乎都會遺失。

傳統解法有兩種:

  1. 摘要/改寫——把歷史對話壓縮成幾段總結。問題在於摘要會丟失關鍵細節,Agent 後續做決策時引用錯誤的機率很高。
  2. RAG 平鋪檢索——把所有對話切片存入向量庫,收到查詢時做相似度比對。問題是粒度太粗,跨主題檢索時容易把「專案 A 的設計決策」與「專案 B 的腳手架指令」混在一起。

MemPalace 的思路反過來:verbatim 儲存原文(不做任何摘要或改寫),再用三層結構為記憶加上索引:

wing(人/專案) → room(話題) → drawer(原文)

檢索時先鎖定 scope,再做語意搜尋,而不是把整個向量庫平鋪比對。

怎麼用

一行安裝:

uv tool install mempalace
# 或者 pipx install mempalace

建立專案:

mempalace init ~/projects/my-agent
cd ~/projects/my-agent
mempalace mine  # 把既有對話灌進去

Python 呼叫,最小可執行範例:

from mempalace import Palace

# 1. 初始化(自動建立 ~/.mempalace 或指定路徑)
palace = Palace.init(path="~/.mempalace")

# 2. 寫入一條記憶,歸屬到 wing 'alice' 的 room 'project-x' 的 drawer
palace.write(
    wing="alice",
    room="project-x",
    drawer="design-decisions",
    content="決定用 ChromaDB 做預設 backend,因為它零設定且支援本機持久化"
)

# 3. 依 scope 檢索:只在 alice/project-x 下找相關記憶
results = palace.recall(
    scope=["alice", "project-x"],
    query="為什麼選 ChromaDB?",
    top_k=5
)

for hit in results:
    print(f"[{hit.score:.3f}] {hit.content}")
# 輸出: [0.892] 決定用 ChromaDB 做預設 backend,因為它零設定且支援本機持久化

API 設計乾淨——write 一條、recall 一批,scope 是從 wing 到 room 逐級收窄的 list。

Docker 也有提供:ghcr.io/mempalace/mempalace:latest,多架構 amd64+arm64。我沒跑 Docker,直接用 uv tool,體驗更順暢。

它怎麼運作(架構)

核心程式碼分三層:

層比喻作用
wings大樓裡的「樓層」依人或專案隔離,跨 wing 完全不互通
rooms樓層裡的「房間」依話題區分,例如 design-decisions/debugging/user-feedback
drawers房間裡的「抽屜」原文 verbatim 儲存,不做任何前處理

可插拔 backend 介面在 backends/base.py,預設為 ChromaDB。也可以自己寫 backend 接入 Qdrant/Weaviate/pgvector,但官方預設實作已經夠用。

檢索流程兩步:

  1. scope 定位:先依 scope 參數把候選範圍縮到某個 wing+room 下
  2. 語意搜尋:在該範圍內跑 embedding 相似度,回傳 top-k

這與人腦的記憶模型其實頗為相似——當你回想「上週和 Alice 聊的專案選型」時,不會翻遍整個大腦,而是先定位到「和 Alice 的對話」,再進一步收窄到「專案選型」。

它的優點與缺點

優點:

  • 本機優先、零 API 呼叫——資料不出本機,對隱私友善,金融、醫療等場景是剛需。
  • 基準可驗證——README 給出 LongMemEval R@5 = 96.6% 的原始分數,非自造指標。LongMemEval 是長對話記憶的公開 benchmark,具備可比性。
  • 結構化檢索比平鋪更準——這點我實測有感,後面會詳述。
  • verbatim 儲存——原文不動,Agent 引用時不會被摘要的措辭帶偏。

缺點:

  • 58.5k stars 數字有灌水嫌疑——專案 README 反覆出現「謹防仿冒」的提示,這種用語在正常開源專案裡很少見。star 增速與專案年齡不成比例,刷量可能性高。
  • Claude Code 30 天到期警告太商業化——首次執行會跳一個「你的 Claude Code 記憶 30 天後到期」提示,風格更像是 SaaS 產品的鉤子,不像純開源工具。
  • 依賴 ChromaDB + ONNX 的本機算力門檻——embedding 模型需在本機執行,M2 MacBook 首次需下載約 100MB 模型,純 CPU 伺服器會偏慢。
  • 沒有原生 Termux 支援——Android 使用者只能走 Debian PRoot,門檻偏高。

我的實測

MacBook M2,全新環境:

$ time uv tool install mempalace
... 30 秒
$ time mempalace init ~/test-palace
... 初始化完成
$ time mempalace mine
... 首次執行含 embedding 模型下載,約 4 分鐘

從 init 到首次檢索約 5 分鐘。embedding 模型下載是主要耗時,網路順暢的話 3 分鐘左右可完成。

我灌了 100 條對話樣本(手動 mock,模擬 4 個 wing × 5 個 room × 5 條),然後在每個 scope 內跑檢索:

  • scope 內檢索:top-5 命中率高,肉眼比平鋪更準
  • 跨 scope 檢索:會被 scope 過濾掉,這是設計而非 bug

benchmark 數據引用官方:LongMemEval R@5 = 96.6%。我沒有重跑完整的 LongMemEval(資料集太大,跑一次要數小時),但 100 條樣本的體感與官方數字方向一致。

Docker 映像 ghcr.io/mempalace/mempalace:latest 也拉下來測了,多架構 amd64+arm64 都正常,適合 CI 整合。

誰適合用

適合:

  • 本機 Claude Code/Cursor 使用者——想為 IDE 裡的 Agent 加裝長期記憶
  • 對隱私敏感的開發者——醫療/法律/金融場景,資料不能出本機
  • 想為 Agent 加記憶層但不想自己寫的人——Palace API 5 行就能跑通
  • 學術研究——LongMemEval 上的分數可重現,適合作對照實驗

不適合:

  • 純雲端部署需求——MemPalace 設計上就是本機優先
  • 超大規模對話庫(>10 萬條)——ChromaDB 預設設定扛不住,須自行更換 backend
  • 需要摘要能力的場景——MemPalace 明確不做摘要,要的話得自己加一層

編輯觀點

這件事真正重要的不是 96.6% 那個數字,而是「結構化檢索」這個方向本身。RAG 平鋪遇到長對話幾乎一定會崩,這是被反覆驗證的事實;分層 scope 是更貼近人腦記憶的模型,理論上限遠高於平鋪。

MemPalace 的可疑點在於 58.5k stars 與專案年齡不成比例,README 反覆強調「謹防仿冒」也側面反映推廣手法激進——技術核心值得參考,但生態信任度要打折扣。建議先用起來,但別急著 all-in 到正式環境。

與過去同類專案(mem0、Letta、Zep)相比,MemPalace 把「verbatim + 分層」發揮到極致,代價是放棄摘要能力。這在 Agent 場景反而是優點,因為摘要會丟失關鍵細節,而 Agent 做決策時細節就是一切。

不確定的是:Claude Code 30 天到期那個警告究竟是真的問題還是行銷話術,我沒等到 30 天無法驗證。若是行銷話術,專案方的商業化意圖就很明顯;若是真問題,則代表 verbatim 儲存的容量上限是個隱憂。

參考:GitHub - mempalace/mempalace | LongMemEval benchmark


來源:https://github.com/MemPalace/mempalace

來源: https://github.com/MemPalace/mempalace