工具

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 平铺检索——把所有对话切片存进向量库,query 来了做相似度匹配。问题:粒度太粗,跨话题检索时会把「项目 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 是一个 list 从 wing 到 room 逐级收窄。

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