mempalace

MemPalace 是一个开源、本地优先的 AI 记忆系统，目标是在不依赖云端的前提下长期保存并检索对话与项目数据。它把对话历史以逐字文本（verbatim）形式存储，检索时使用语义搜索，不对内容做摘要、抽取或改写，从而尽可能保留原始信息。

用途与定位 MemPalace 面向需要长期记忆的编码代理和个人助手场景，也适合需要检索自己历史对话、项目资料的用户。它强调“本地优先”：除非用户主动选择，否则数据不会离开本机。

主要能力

• 逐字存储与语义检索：保存完整对话历史，检索基于语义相似度，不做摘要或改写。
• 层次化索引结构：人物和项目构成 wings，话题构成 rooms，原始内容存放在 drawers，使搜索可以限定范围，而非面对扁平语料库。
• 可插拔检索后端：默认使用 ChromaDB，接口定义在 mempalace/backends/base.py，可替换其他后端。提供基于本地 SQLite 的原生 Rust 引擎 rust_exact，以及与 sqlite_exact 共用同一数据库文件的适配器。
• 基准成绩：在 LongMemEval 检索召回（R@5，500 题）上，原始得分为 96.6%，该路径无需 API 密钥、无需云服务、任一步骤都不使用大语言模型。混合管线加入关键词提升、时间邻近提升和偏好模式抽取；留出集上为 98.4%，被视为更诚实的泛化指标。重排管线使用 LLM 阅读器从检索到的前 20 个会话中提升最佳候选，可与多种模型配合，但不作为主打的“100%”成绩。
• 47 个 MCP 工具：覆盖宫殿读写、知识图谱操作、跨翼导航、抽屉管理、代理日记和代理协调（logstream 事件和工件移交）。
• 知识图谱：包含带有效时间窗口的时序实体关系图，支持添加、查询、失效和时间线操作，由本地 SQLite 支撑。
• 代理专属空间：每个专家代理在宫殿中获得自己的 wing 和日记，可通过 mempalace_list_agents 在运行时发现，不会挤占系统提示词。
• 自动保存钩子：支持 Claude Code、Codex CLI 和 Cursor IDE，定期及在上下文压缩前保存。

使用方式 安装方式：

• 推荐使用 uv：uv tool install mempalace，将 CLI 安装到 PATH 上的隔离环境。
• 也可使用 pipx：pipx install mempalace。
• 仅在已激活的虚拟环境中使用普通 pip 安装，以便使用 import mempalace。
• 支持容器镜像运行 MCP 服务器或 CLI，多架构（amd64 + arm64）。所有持久数据位于 /data，需要挂载卷。首次需要嵌入的命令会下载模型（默认 minilm 约 80 MB，embeddinggemma 约 300 MB），首次调用较慢且需要网络。
• Android / Termux 原生安装暂不支持，因为 ChromaDB 和 ONNX Runtime 等编译依赖只发布 Linux 轮子，不发布 Android 轮子。Android ARM64 用户可在隔离的 Debian PRoot 容器中运行常规 Linux 包。
• GPU 镜像仅支持 x86_64，因为 onnxruntime-gpu 没有 aarch64 Linux 轮子。 配置与选择：
• 使用 --backend <name>、MEMPALACE_BACKEND=<name> 或 config.json 中的 "backend": "<name>" 选择后端。
• 嵌入可本地计算，也可选用 OpenAI 兼容端点。在 ~/.mempalace/config.json 中设置 embedding_model: "openai-compat" 及 embedding_api_url、embedding_api_model、embedding_api_key，可通过对应的 MEMPALACE_EMBEDDING_API_* 环境变量覆盖。切换到该方式需要执行 mempalace repair rebuild-index。
• 引导设置 python -m mempalace.onboarding 提供 embeddinggemma-300m（多语言，100+ 语言，推荐）或 all-MiniLM-L6-v2（仅英语，约 30 MB）。 连接与集成：
• 可作为 stdio 服务器接入 MCP 客户端（如 Claude Code）。需挂载希望服务器挖掘的内容，服务器无法访问未挂载的对话记录。
• 仓库提供三个技能：mempalace 用于引导安装和操作，mempalace-recall 用于先搜索再回答，mempalace-task 用于 logstream 委托。安装技能本身不会安装 CLI 或 MCP 服务器，需通过设置技能引导完成系统更改并验证连接。
• 引导设置期间，代理可提供每周稳定版检查。该功能默认关闭，启用时仅连接 PyPI，不会自动安装更新。设置会记录运行时来自 uv tool、pipx 还是 pip，以便升级计划不会给出错误的安装命令。

适用场景

• 为编码代理提供长期记忆，保存完整会话并在需要时检索。
• 需要本地保存对话历史、且不希望依赖云端或 API 的用户。
• 需要跨代理协调、共享记忆空间的多代理工作流。
• 需要在自己的数据上运行检索基准测试的用户，可使用 mempalace-native bench --db <sqlite_exact.sqlite3> 本地测量。

限制与注意事项

• 原生 Termux 安装暂不支持；需使用 Debian PRoot 容器。
• GPU 镜像仅支持 x86_64，在 ARM 主机（包括 Apple Silicon）上构建会因依赖解析失败而报错。
• 容器内运行 uid 为 1000，Linux 上绑定的挂载目录需对该 uid 可读（0755 可以，0700 不行），失败时表现为 PermissionError: [Errno 13]，不要用 --user 绕过。
• rust_exact 遇到复杂过滤、请求返回嵌入或未安装原生扩展时，会回退到 Python 后端；memapalace-native 可执行文件仅 Rust 实现，无 Python 回退。
• 切换嵌入端点需要重建索引。
• 从克隆构建使用当前分支（develop 为默认分支），如需发布版本应拉取已发布镜像。
• 官方来源仅限 GitHub 仓库、PyPI 包和 mempalaceofficial.com 文档；其他域名（包括 .tech、.net 或其他 .com 变体）为冒名站点，可能分发恶意软件。
• 项目未发布与 Mem0、Mastra、Hindsight、Supermemory 或 Zep 的并列比较数据，因为各项目在不同切分上发布不同指标，直接比较被认为不诚实。
• 项目采用 MIT 许可证。

其他事实

• 官方网站：mempalaceofficial.com。
• 文档链接包括：概念（宫殿）、CLI 参考、Python API、MCP 工具、代理、钩子等。
• 项目鼓励 PR 贡献，详见 CONTRIBUTING.md。