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

让 AI 记住但不把资料送上云端：MemPalace 的 local-first 记忆系统拆解

分享:
让 AI 记住但不把资料送上云端：MemPalace 的 local-first 记忆系统拆解

本文大纲

1. 为什么 AI Agent 需要独立的记忆层

1. MemPalace 解决什么问题

1. 从 verbatim 储存到分层检索的架构

1. 实际安装、初始化与第一次搜寻

1. MCP、auto-save hooks 与多 Agent 工作流

1. Benchmark 怎么看，以及哪些数字不能过度解读

1. 安全性、版本差异与部署前检查

先说结论：上下文视窗不是记忆

只要使用过 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。

1. 模型下载：第一次安装仍需要下载套件与模型；若是严格隔离环境，必须预先准备 cache。

1. 可选整合：若设定外部 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 与专案文件后续变更时，请重新验证。