MemPalace：本地优先的 AI 记忆系统

1. 项目概述

MemPalace 是一个本地优先、开源的 AI 记忆系统，原样存储 AI 智能体的对话历史，并通过语义搜索进行检索，解决了编码智能体和聊天机器人在会话结束或上下文窗口压缩后“忘记”一切的问题。

2. 背景与定位

MemPalace 的诞生是为了解决一个非常具体的痛点：长时间运行的智能体会话（例如在 Claude Code 等工具中）在压缩后会丢失早期上下文，迫使智能体即使在数小时的前期工作之后还要问“我们今天在做什么？”。其核心使命是将大多数记忆工具需要权衡取舍的两件事结合起来——以完全保真的方式存储一切，并即时找到其中正确的部分，包括通过模糊、只记得一半的查询。

在架构上，它借鉴了 Zettelkasten 方法（小型、交叉引用的索引卡片），将记忆组织为 wings（人员/项目）、rooms（主题）、closets（压缩的、AI 可读的索引条目）和 drawers（原始逐字内容）的层级结构。这与大多数记忆框架有两个不同之处：它从不总结或改写所存储的内容（检索始终返回原始文本），并且其检索后端是可插拔的，而不是绑定到某一个向量数据库，因此团队可以从纯本地开始，再迁移到服务器支持的后端，而无需改变系统其余部分的工作方式。

3. 功能类别

🗂️ Palace 存储 — 跨 wings/rooms/closets/drawers 的逐字、结构化存储；核心操作包括 mine、search、wake-up 和逐条消息的 sweep；目的：在保持完整对话保真度的同时，使其易于导航。
🔌 可插拔后端 — 支持 5 种存储：chroma（默认，嵌入式）、sqlite_exact、milvus、qdrant、pgvector；目的：让用户从本地开始，无需重新设计架构即可扩展到共享服务器。
🕸️ 知识图谱 — 一个带有效性窗口的时间实体-关系图谱，由本地 SQLite 支持；支持添加/查询/失效/时间线操作；目的：追踪事实和关系如何随时间变化，而不仅仅是静态快照。
🔧 MCP 服务器与工具 — 45 个 MCP 工具，涵盖 palace 读写、知识图谱操作、跨 wing 导航、drawer 管理、智能体日记和多智能体协调；目的：将记忆作为一等能力暴露给任何兼容 MCP 的智能体。
🪝 自动保存钩子 — 适用于 Claude Code、Codex CLI 和 Cursor IDE 的钩子，可定期保存并在上下文压缩前保存；目的：自动捕获会话，无需手动“请记住这个”的步骤。
🤖 多智能体支持 — 每个专业智能体都有自己的 wing 和日记，可在运行时通过 mempalace_list_agents 发现；目的：让多个智能体共享一个记忆系统，而不会污染彼此的上下文或系统提示。

4. 关键亮点

逐字检索，而非总结 — 搜索结果返回原始文本，因此在此过程中不会因有损压缩而丢失任何内容。
本地优先且支持离线 — 核心基准路径（LongMemEval 上 96.6% 的 R@5）在任何阶段都不需要 API 密钥、不需要云、也不需要 LLM 调用。
有基准测试、可复现的结果 — 每个已发布的数字（LongMemEval、LoCoMo、ConvoMem、MemBench）都附带了从仓库复现的确切命令。
可选混合 + LLM 重排流水线 — 关键词加权、时间邻近加权和偏好模式提取将召回率提升至 98.4%（留出集），LLM 重排选项可达到 ≥99%，并且与模型无关（已使用 Claude 以及通过 Ollama Cloud 的开源模型进行测试）。
静默后台运行 — 根据当前设计，日记写入和 palace 归档在后台钩子/子智能体中运行，而不是在可见聊天中运行，从而减少了重新传输状态更新带来的 token 开销。
多架构 Docker 支持 — 已发布的容器镜像可在 amd64 和 arm64（包括 Apple Silicon）上原生运行，并提供单独的 CUDA 构建用于 GPU 工作负载。

5. 按角色的使用场景

普通开发者 — 在会话之间保留 AI 编码助手的项目上下文，而不是在每次压缩或重启后重新解释决策。
数据/研究科学家 — 以语义方式挖掘和搜索大量过去的对话或笔记，并将项目自身的检索基准作为参考实现进行复现。
项目经理/团队 — 将共享的 Claude Code 记录挖掘到一个公共 palace（一个“共享大脑中心”）中，使团队知识和决策保持在一个可搜索的地方，而不是分散在个人聊天历史中。

6. 快速开始

找到你需要的内容 — 浏览文档站点获取指南和参考资料：

https://mempalaceofficial.com/guide/getting-started.html

安装/集成 — 推荐通过 uv 进行隔离安装，然后初始化一个 palace：

uv tool install mempalace
mempalace init ~/projects/myapp
mempalace mine ~/projects/myapp
mempalace search "why did we switch to GraphQL"

也可以通过安装项目的技能来进行智能体引导设置：

npx skills add MemPalace/mempalace

贡献 — 在提交 PR 之前请阅读贡献指南：

https://github.com/MemPalace/mempalace/blob/main/CONTRIBUTING.md

7. 项目结构

mempalace/
├── backends/          # 可插拔存储后端实现（chroma、qdrant、pgvector 等）
├── data/              # 捆绑的数据资产
├── i18n/              # 国际化资源
├── instructions/      # 面向智能体的指令集
├── integrations/      # 第三方工具集成
├── sources/           # 用于挖掘的摄取源
├── cli.py             # `mempalace` 命令行入口点
├── mcp_server.py       # MCP 服务器实现（工具暴露）
├── knowledge_graph.py  # 时间实体-关系图谱
├── palace.py           # 核心 palace 读写逻辑
├── miner.py / convo_miner.py  # 内容和对话挖掘流水线
├── searcher.py         # 语义搜索/检索逻辑
└── onboarding.py        # 首次运行设置和嵌入模型选择

其他值得了解的顶层目录：benchmarks/（可复现的基准脚本和结果）、hooks/（受支持编辑器/智能体的自动保存钩子实现）、skills/（可安装的智能体技能）和 website/（文档站点的源代码）。

8. 相关生态

上游依赖：ChromaDB（默认向量存储），可选支持 Milvus、Qdrant 和 pgvector；ONNX Runtime 和嵌入模型（all-MiniLM-L6-v2、embeddinggemma-300m）用于本地嵌入。
智能体/编辑器集成：Claude Code、Codex CLI、Cursor IDE、Gemini CLI 和 Antigravity，通过模型上下文协议（MCP）连接。
补充工具：任何兼容 OpenAI 的 /v1/embeddings 端点（LM Studio、llama.cpp、vLLM、Ollama）都可用于远程或 GPU 加速嵌入，替代本地计算。

9. 许可证

✅ 在 MIT 许可证下，允许商业使用、修改、分发和私人使用。
❌ 该许可证不提供任何担保，也不为作者承担任何责任。
ℹ️ 在软件的副本或实质性部分中必须保留原始版权和许可声明。

10. 常见问题

问：MemPalace 需要 API 密钥或云服务才能工作吗？
答：不需要。核心基准路径，包括 LongMemEval 上 96.6% 的 R@5 原始检索分数，完全在本地运行，使用默认的 chroma 后端，无需 LLM 调用。

问：MemPalace 使用哪个向量数据库？
答：默认使用 ChromaDB，可插拔支持 sqlite_exact、milvus、qdrant 和 pgvector，可通过 --backend <name> 或 MEMPALACE_BACKEND 选择。

问：MemPalace 可以在没有本地 Python 环境的情况下运行吗？
答：可以，通过已发布的多架构 Docker 镜像：

docker pull ghcr.io/mempalace/mempalace:latest

问：如何在压缩后保留 Claude Code 会话的上下文？
答：按照 Claude Code 保留设置清单中描述的自动保存钩子进行配置，然后使用以下命令回填现有记录：

mempalace mine ~/.claude/projects/ --mode convos

问：除了 GitHub 仓库之外，还有官方网站吗？
答：唯一的官方来源是 GitHub 仓库、PyPI 包（mempalace）以及 mempalaceofficial.com 上的文档；其他名称相似的域名与本项目无关。

11. 快速链接

仓库：https://github.com/MemPalace/mempalace
官方文档：https://mempalaceofficial.com
贡献指南：https://github.com/MemPalace/mempalace/blob/main/CONTRIBUTING.md
社区：https://discord.com/invite/ycTQQCu6kn

12. 总结

MemPalace 填补了任何构建或使用长时间运行 AI 智能体的人的一个实际空白：它保留了完整、逐字的对话历史，同时保持快速和精确的搜索，而不是强迫用户在存储一切和找到任何内容之间做出选择。集成 Claude Code、Codex 或 Cursor 等编码智能体的开发者可以获得持久、可复现基准测试的记忆能力，且没有强制性的云依赖，而团队可以根据需求增长，将同一系统从私有本地 palace 扩展到共享后端。