MemPalace: 最佳基准测试的开源AI记忆系统

这是什么

MemPalace 是一个本地优先（Local-first）的 AI 记忆系统，主要使用 Python 开发。它旨在为本地 AI 应用提供持久化的上下文记忆能力，同时严格保护用户隐私。

该项目在 GitHub 上获得了极高的关注度（Star 数约 53,648+），其核心理念是“逐字存储”（Verbatim storage）。与许多通过摘要或提取关键信息来压缩上下文的 AI 记忆工具不同，MemPalace 原始地保存对话历史和文件内容，并通过语义搜索进行检索。它不依赖云端 API，所有数据均存储在用户本地机器上，除非用户主动选择共享，否则没有任何数据离开本地环境。

解决的问题

1. 上下文丢失与“失忆”问题：大型语言模型（LLM）的上下文窗口有限，随着对话进行或项目迭代，早期的关键信息容易被遗忘。MemPalace 通过长期记忆存储解决了这一限制。
2. 隐私泄露风险：许多现有的 AI 记忆解决方案（如 Mem0、Zep 等）通常依赖云端服务或需要发送数据到外部 API 进行处理。MemPalace 解决了用户对数据隐私的担忧，确保敏感的项目代码、对话记录完全本地化。
3. 非结构化数据的检索困难：传统的文件搜索或简单的向量数据库难以处理复杂的语义关系。MemPalace 引入了类似“宫殿”的层级结构（人/项目为翼，话题为房间，原始内容为抽屉），使得搜索可以针对特定范围（Scoped Search），而非在扁平的语料库中盲目匹配。
4. 依赖冲突与环境污染：MemPalace 提供了独立的 CLI 工具，并推荐使用 uv 或 pipx 进行隔离安装，避免了其依赖项（如 chromadb, numpy, grpcio）与用户全局 Python 环境发生冲突。

核心功能

• 逐字存储与语义检索：
  • 存储：完整保留对话原文和文件内容，不进行摘要、提取或改写。
  • 检索：基于语义搜索（Semantic Search）快速定位相关信息。
• 分层索引架构（The Palace）：
  • Wings（翼）：代表人或项目。
  • Rooms（房间）：代表特定话题。
  • Drawers（抽屉）：存放原始内容。
  • 这种结构允许用户进行范围限定搜索，提高检索精度。
• 可插拔的后端支持：
  • 默认后端为 ChromaDB。
  • 接口定义在 mempalace/backends/base.py，开发者可以轻松替换为其他向量数据库后端，而无需修改核心逻辑。
• 时间实体关系图谱（Temporal Entity-Relationship Graph）：
  • 基于本地 SQLite 构建，支持有效性窗口（Validity Windows）。
  • 支持添加、查询、失效和查看时间线等操作，适合管理随时间变化的知识状态。
• MCP 工具集成：
  • 提供 29 个 MCP（Model Context Protocol）工具，涵盖宫殿读写、知识图谱操作、跨翼导航、抽屉管理及代理日记等功能。
• 多源数据摄入：
  • 支持扫描项目文件。
  • 支持导入 Claude Code 会话记录（.claude/projects/）。
  • 支持对转录文件进行逐消息级别的扫描（mempalace sweep），生成逐条消息的抽屉存储。

亮点 / 与同类相比

• 极高的检索召回率（Recall）：
  • 在 LongMemEval 基准测试中，MemPalace 在 500 个问题上的原始检索召回率（R@5）达到 96.6%。
  • 这一成绩是在零 API 调用、零云端依赖、零 LLM 参与（纯本地处理）的情况下取得的。
  • 混合管道结合了关键词增强、时间邻近性增强和偏好模式提取，在保留集上的泛化召回率可达 98.4%。
• 重排管道（Rerank Pipeline）的灵活性：
  • 虽然核心检索无需 LLM，但 MemPalace 提供了可选的重排管道，利用 LLM 对前 20 个候选结果进行重排序。
  • 支持任意具备合理能力的模型（如通过 Ollama Cloud 运行的 Claude Haiku/Sonnet, minimax-m2.7 等），且结果与特定模型无关。
• 诚实的基准测试方法：
  • 项目明确拒绝与 Mem0、Mastra、Hindsight、Supermemory 或 Zep 进行直接的横向对比，因为它们的评估指标和数据集划分不同。
  • 提供完整的基准复现脚本和结果文件，确保数据透明。
• Agent 隔离与发现：
  • 每个专用 Agent 拥有独立的“翼”和“日记”，运行时可通过 mempalace_list_agents 发现，避免系统提示词（System Prompt）膨胀。
• Claude Code 深度集成：
  • 提供两个钩子（Hooks），用于定期保存和上下文压缩前保存，防止会话过期导致记忆丢失。
  • 提供专门的恢复/设置清单，简化 Claude Code 用户的上手流程。

适合谁用 / 上手

适合人群：

• 注重隐私的开发者：希望将 AI 记忆能力集成到本地工作流，但不愿将代码或对话上传至云端。
• 长期项目维护者：需要跨会话、跨天甚至跨周保持上下文连贯性的开发者。
• Claude Code / Gemini CLI 用户：特别是那些希望自动保存会话历史并实现智能检索的用户。
• AI 应用开发者：需要构建本地优先的 Agent 系统，并需要可插拔后端和 MCP 支持的技术人员。

上手指南：

1. 安装要求：

   • Python 3.9+
   • 向量存储后端（默认 ChromaDB）
   • 约 300 MB 磁盘空间用于嵌入模型（推荐 embeddinggemma-300m，支持 100+ 语言；或 all-MiniLM-L6-v2，仅英语，约 30 MB）。

2. 推荐安装方式： 为避免依赖冲突，建议使用 uv 或 pipx 在隔离环境中安装 CLI：

   # 使用 uv 安装
   uv tool install mempalace
   
   # 或使用 pipx
   pipx install mempalace
   

3. 初始化与数据摄入：

   # 初始化宫殿
   mempalace init ~/projects/myapp
   
   # 挖掘项目文件
   mempalace mine ~/projects/myapp
   
   # 挖掘 Claude Code 会话记录
   mempalace mine ~/.claude/projects/ --mode convos
   

4. 搜索与唤醒：

   # 语义搜索
   mempalace search "why did we switch to GraphQL"
   
   # 加载上下文以用于新会话
   mempalace wake-up
   

5. 进阶配置：

   • 对于 Claude Code 用户，务必配置保留钩子（Retention Hooks）以防止会话过期丢失记忆。
   • 如需逐消息级别的记忆，定期运行 mempalace sweep <transcript-dir>。

官方文档与资源：

• 概念架构：mempalaceofficial.com/concepts/the-palace
• 入门指南：mempalaceofficial.com/guide/getting-started
• 基准测试复现：benchmarks/BENCHMARKS.md
• 注意事项：项目警告用户警惕仿冒网站，唯一官方来源为 GitHub 仓库、PyPI 包及 mempalaceofficial.com。