GitHub 上 mempalace/mempalace 这个项目最近被频繁推到首页。58.5k stars,主打开源、本地优先、给 AI Agent 加长期记忆。我装了下,跑了一遍,把架构和代码都拆开看了。
它解决什么问题
长对话是 LLM 的硬伤。Claude 200k context window 听起来很大,但真正用起来你会发现:对话拉到 50 轮以上,前面聊过的技术选型、决策理由基本就丢了。
传统解法两种:
- 摘要 / 改写——把历史对话压成几段总结。问题:摘要会丢关键细节,Agent 后续做决策时引用错的概率很高。
- 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,但官方默认实现够用了。
检索流程两步:
- 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