GitHub 上 mempalace/mempalace 這個專案最近頻繁登上熱門榜。58.5k stars,主打開源、本機優先、為 AI Agent 加裝長期記憶。我親自安裝並跑了一遍,把架構與程式碼都拆開來看。
它解決什麼問題
長對話是 LLM 的硬傷。Claude 200k context window 聽起來很大,但實際用過會發現:對話拉到 50 輪以上,前面討論過的技術選型、決策依據幾乎都會遺失。
傳統解法有兩種:
- 摘要/改寫——把歷史對話壓縮成幾段總結。問題在於摘要會丟失關鍵細節,Agent 後續做決策時引用錯誤的機率很高。
- 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,但官方預設實作已經夠用。
檢索流程兩步:
- scope 定位:先依
scope參數把候選範圍縮到某個 wing+room 下 - 語意搜尋:在該範圍內跑 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