项目快照：MemPalace/mempalace，约 59,152 个 Star，7,563 个 Fork；最新推送时间 2026-09-18T07:55:23Z。本文基于仓库公开资料撰写。
项目地址：https://github.com/MemPalace/mempalace · http://mempalaceofficial.com/
项目速览（TL;DR）
MemPalace 是一个以本地优先（local-first）为设计取向的开源人工智能记忆系统，使用 Python 编写，采用 MIT 许可证。它把对话历史以原文形式保存，并通过语义搜索（semantic search）进行检索；根据 README，默认检索后端为 ChromaDB，数据在用户明确选择加入外部服务前不会离开本机。
仓库资料显示，项目版本为 3.10.0，要求 Python 3.9 或更高版本，默认分支为 develop。GitHub 元信息显示该仓库有 59152 个 Star 和 7563 个 Fork；README 宣称其在 LongMemEval 上取得 96.6% R@5 raw，且不需要 API 调用。该性能数字属于仓库 README 的项目声明，不应替代在相同数据、模型、硬件和参数下的独立复现。
| 项目属性 | 资料中的值 |
|---|---|
| 项目名称 | MemPalace |
| 仓库 | MemPalace/mempalace |
| 主要语言 | Python |
| 版本 | 3.10.0 |
| Python 要求 | >=3.9 |
| 许可证 | MIT |
| 默认分支 | develop |
| GitHub Star / Fork | 59152 / 7563 |
定位与目标用户
MemPalace 的核心定位不是把历史压缩成一段摘要，而是保存可检索的原始对话文本，并通过结构化索引缩小搜索范围。它更适合需要保留上下文原貌、希望记忆服务运行在本地、或需要把记忆能力接入编码代理（coding agent）的人。
项目 README 将其描述为“Local-first AI memory”，并提供命令行工具（CLI，Command-Line Interface）和模型上下文协议（MCP，Model Context Protocol）相关入口。对于希望由代理引导完成安装的用户，仓库提供了面向技能（skills）的安装方式；对于希望明确控制 Python 环境、数据目录和容器生命周期的用户，仓库也提供了直接 CLI、Docker 和 Docker Compose 路径。
核心功能
核心能力可以归纳为“原文存储、分层组织、语义检索、可插拔后端和代理集成”。这些能力并非彼此独立：原文存储保证返回内容可追溯，分层组织负责限定检索范围，嵌入模型和向量后端负责语义匹配，MCP 则负责将能力暴露给外部代理。
原文存储与语义检索
MemPalace 保存对话历史的逐字内容，不进行摘要、信息抽取或改写。检索阶段使用语义搜索，将查询文本与已建立索引的内容进行匹配；输入是查询语句和已有记忆，输出是与查询相关的原始内容，而不是由系统重新生成的摘要。
这一机制依赖嵌入模型（embedding model）和检索后端。根据 pyproject.toml，项目的核心依赖包括 chromadb、huggingface_hub、tokenizers 和 numpy；README 还说明新安装可选择 embeddinggemma，默认模型为 minilm。模型会在首次使用时延迟下载，而不是在安装 Python 包时立即下载。
“宫殿—翼—房间—抽屉”的组织模型
项目没有把所有历史内容当作一个扁平语料库，而是使用“palace、wings、rooms、drawers”的层次化概念。README 的解释是：人员和项目成为“wings”，主题成为“rooms”，原始内容存放在“drawers”。这种结构允许检索限定在特定人员、项目或主题范围内。
触发条件是用户在搜索或记忆操作中提供相应范围，系统再结合语义索引完成检索。资料没有给出全部命令参数、返回字段或筛选表达式，因此不能据此编写未在仓库资料中出现的接口签名；实际参数应以当前 README 和 CLI 帮助输出为准。
代理技能与 MCP 接入
仓库提供三个技能：mempalace 用于引导安装和日常操作，mempalace-recall 用于在回答前执行搜索记忆，mempalace-task 用于日志流任务委派。技能安装本身不会自动安装 MemPalace CLI 或 MCP 服务端，README 明确说明，后续系统变更和连接验证由设置技能引导完成。
Python 项目入口点定义了 mempalace-mcp 和 mempalace-light-mcp 两个可执行命令。Docker 默认运行 MCP 服务，并通过标准输入输出（stdio）承载 JSON-RPC；因此运行容器时需要保留标准输入，官方示例使用了 docker run -i。
可插拔检索后端
后端接口位于 mempalace/backends/base.py，默认实现是 ChromaDB。项目入口点列出了 chroma、milvus、pgvector、qdrant、sqlite_exact 和 rust_exact，这意味着后端选择被隔离在检索层，不要求上层业务逻辑随存储实现一起修改。
Milvus 和 PostgreSQL 加 pgvector 属于可选依赖路径。milvus extra 包含 pymilvus 和符合条件的 milvus-lite；pgvector 需要客户端驱动，并且服务端必须具备 vector 扩展。资料没有提供 Qdrant、SQLite exact 或 Rust exact 的安装细节，因此这些后端的部署步骤应以仓库最新文档为准。
系统架构与关键模块
从项目文件和入口点看，系统由 CLI、MCP 服务、记忆组织层、嵌入与检索层、后端适配层以及本地持久化目录组成。其设计重点是让上层记忆操作不直接绑定 ChromaDB，同时为本地进程、Docker 容器和代理技能提供不同接入方式。
- 命令行入口：
mempalace = mempalace.cli:main，用于初始化和执行 CLI 操作。 - MCP 入口：
mempalace-mcp = mempalace.mcp_proxy:main，用于提供 MCP 代理入口。 - 轻量 MCP 入口：
mempalace-light-mcp = mempalace.mcp_light_server:main。 - 后端接口：
mempalace/backends/base.py定义后端抽象，入口点负责加载具体实现。 - 向量与模型依赖：ChromaDB、NumPy、Hugging Face Hub 和 Tokenizers 共同支撑嵌入与检索链路。
- 容器入口：Docker 镜像通过
docker-entrypoint.sh选择 MCP 或 CLI 运行模式。
Dockerfile 将构建阶段和运行阶段分开：构建阶段使用 uv 根据锁文件安装依赖，运行阶段只复制虚拟环境和入口脚本，并删除构建工具链。运行镜像将 HOME 设置为 /data，使 palace、配置文件和嵌入模型缓存集中落在可挂载的数据卷中；运行用户为 UID 和 GID 均为 1000 的 mempalace 用户。
依赖与运行环境
直接安装需要 Python 3.9 或更高版本。pyproject.toml 的分类器列出了 Python 3.9、3.10、3.11、3.12、3.13 和 3.14，但资料没有说明每个版本都经过相同程度的验证，实际兼容性应结合当前 CI 和 README 判断。
核心依赖包括 chromadb>=1.5.4,<2、pyyaml>=6.0,<7、huggingface_hub>=0.20、tokenizers>=0.15、numpy>=1.24、python-dateutil>=2.8。Python 3.9 和 3.10 以下环境还会使用 tomli>=2.0.0；资料明确标注该依赖由环境标记控制。
Dockerfile 的默认构建参数为 Python 3.12，并使用 CPU 镜像；GPU 加速位于单独的 Dockerfile.gpu。官方镜像支持 amd64 和 arm64，README 特别说明 Apple Silicon 可以原生运行多架构镜像。
快速开始：安装、运行与验证
下面的路径使用 uv 安装隔离的 CLI 环境，避免将 ChromaDB、NumPy、grpcio 等依赖写入全局 Python。示例只执行本地初始化和本地搜索，不包含外部服务调用，也不要求填写 API 密钥。
最小可运行示例
# 1. 安装 CLI
uv tool install mempalace
# 2. 初始化一个本地 palace
mempalace init ~/projects/myapp
# 3. 验证 CLI 可以执行本地搜索
mempalace search "why GraphQL"上面的安装和初始化命令来自 README，搜索命令形式来自 Docker 使用示例中的 docker run ... cli search "why GraphQL"。如果初始化目录尚无可检索内容，搜索结果的具体数量和文本由本地数据决定，仓库资料没有提供固定输出，因此不应把空结果视为安装失败。
使用 pipx 或虚拟环境
如果系统没有 uv，可以使用 pipx 安装相同的 CLI。若需要在 Python 代码中直接执行 import mempalace，README 建议仅在已激活的虚拟环境中使用 pip。
# pipx 路径
pipx install mempalace
# Python 虚拟环境路径
python -m venv .venv
source .venv/bin/activate
pip install mempalace在 Debian、Ubuntu 或 Homebrew Python 环境中，隔离安装还可以避开 PEP 668 相关限制。Windows 激活虚拟环境的命令未出现在给定资料中，本文不补写未核验的系统特定命令。
通过技能引导安装
需要让编码代理参与设置时，可以先安装仓库技能，再让代理完成后续配置。该方式会检测系统、安装 Python 包、配置 MCP，并询问使用私有本地 palace、共享大脑 hub，还是连接到现有 hub。
npx skills add MemPalace/mempalace技能安装并不等同于完成 CLI 或 MCP 安装。README 还说明，周度稳定版本检查默认关闭；启用后只访问 PyPI，不会自动安装更新，并会记录运行时来自 uv tool、pipx 还是 pip，以便后续升级计划使用匹配的安装命令。
配置说明
配置重点在于后端、模型、数据路径和 Docker 持久化位置。以下表格只列出资料中明确出现的字段；对于 README 或配置文件没有给出具体默认值的字段，按照要求标记为“未提供”，不对实现行为作推断。
| 字段名 | 类型 | 默认值 | 作用 |
|---|---|---|---|
MEMPALACE_EMBEDDING_MODEL |
字符串 | minilm |
选择嵌入模型；Compose 注释列出的另一个值为 embeddinggemma。 |
MEMPALACE_PALACE_PATH |
路径字符串 | 未提供；Docker 默认数据根为 /data |
自定义 palace 位置；Docker Compose 示例将其设置为 /data/custom/palace。 |
MEMPALACE_BACKEND |
字符串 | ChromaDB | 选择检索后端；资料明确给出 pgvector 作为一种可选值。 |
MEMPALACE_MILVUS_URI |
字符串 | 未提供 | 将 Milvus 后端指向 Milvus Server 或 Zilliz Cloud 时使用。 |
MEMPALACE_MILVUS_TOKEN |
字符串 | 未提供 | 连接 Milvus Server 或 Zilliz Cloud 的令牌配置项。 |
HOME |
路径字符串 | Docker 中为 /data |
Docker 运行时将 palace、配置和模型缓存集中到数据卷。 |
EXTRAS |
逗号分隔字符串 | extract,spellcheck |
Docker 构建参数，用于将可选 extra 编译进镜像。 |
embeddinggemma 模型缓存约为 300 MB，默认 minilm 模型缓存约为 80 MB，这些数值来自 Dockerfile 注释。模型在首次使用时延迟下载，因此部署验证需要考虑首次检索会触发模型缓存；网络不可用时的具体错误行为，官方仓库未提供该信息，建议以最新 README 为准。
Docker 与 Docker Compose
容器化路径适合不希望在宿主机维护 Python 工具链的场景。镜像默认启动 MCP 服务，所有持久化内容位于 /data，包括 palace、配置和缓存的嵌入模型；因此必须挂载卷，才能在容器重建后保留数据。
# 获取官方镜像
docker pull ghcr.io/mempalace/mempalace:latest
# 以 stdio 方式运行 MCP 服务
docker run -i --rm \
-v mempalace-data:/data \
ghcr.io/mempalace/mempalace
# 使用同一个数据卷执行 CLI 搜索
docker run --rm \
-v mempalace-data:/data \
ghcr.io/mempalace/mempalace \
search "why GraphQL"-i 对 MCP 服务是必要的，因为 JSON-RPC 需要从标准输入读取数据。Docker Compose 文件定义名为 mempalace-data 的卷，并把服务配置为保持标准输入打开、不开启 TTY；它适合通过 docker compose run 交互执行，而不是以 detached 模式长期运行。
docker compose build
docker compose run --rm mcp
docker compose run --rm mcp cli search "GraphQL"Compose 中的 environment 配置块不能只保留注释而没有键值映射，否则 Compose 会将其解析为 null 并拒绝文件。需要自定义模型或 palace 路径时，应同时取消对应环境变量及其值的注释。
进阶用法
进阶部署主要围绕后端替换、共享服务和代理工作流展开。选择方案时应先确认数据位置、连接方式和依赖安装方式，不能仅凭入口点名称推断某个后端已经完成远程服务配置。
选择 Milvus 或 pgvector
Milvus extra 支持每个 palace 使用 Milvus Lite，也可以通过 MEMPALACE_MILVUS_URI 和 MEMPALACE_MILVUS_TOKEN 指向 Milvus Server 或 Zilliz Cloud。pgvector 后端需要安装对应可选依赖，并要求服务端已安装 vector 扩展。
在希望使用项目默认本地检索路径的场景，应保留 ChromaDB；在已有 Milvus 或 PostgreSQL 加 pgvector 基础设施、且团队已有连接管理流程的场景，可评估相应可插拔后端。上述选择属于根据配置和依赖资料作出的使用建议，具体容量、并发和迁移能力官方仓库未提供。
私有本地 palace、共享 hub 与客户端
安装技能时，设置流程可以询问使用私有本地 palace、共享大脑 hub 或连接现有 hub。资料没有给出 hub 的监听地址、端口、认证协议、网络拓扑或服务端部署命令，因此不能在本文中构造远程部署示例。
如果需要在生产网络中部署共享服务，应先从官方文档确认传输层、认证、访问控制和数据隔离方式。没有这些信息时，较可核查的选择是先使用单机本地 palace，并将数据目录纳入本地备份策略。
可观测性与运维
给定资料明确覆盖的是数据持久化、模型缓存和运行入口，没有提供指标端点、日志字段、健康检查接口、告警规则或服务级别协议（SLA）。因此，运维验证应从进程是否能够启动、数据卷是否可写、模型是否完成缓存和搜索命令是否能够执行这几个可观察结果开始。
- 确认容器使用了
-v mempalace-data:/data或等价宿主机挂载。 - 确认 MCP 场景保留标准输入，不要删除官方示例中的
-i。 - 首次使用模型时检查网络和数据卷空间；模型缓存位置由 Dockerfile 的
HOME=/data规则决定。 - 升级前确认安装来源是
uv tool、pipx还是pip，避免使用与实际安装方式不匹配的升级命令。 - 需要后端替换时，先确认对应 extra 和服务端扩展，而不是只修改环境变量。
备份方面，资料明确指出 Docker 的 palace、配置和模型缓存都落在 /data 下。如何在原生安装场景执行一致性备份、如何恢复索引以及是否支持在线迁移，官方仓库未提供该信息，建议以最新 README 和项目文档为准。
安全与合规边界
MemPalace 涉及对话历史、项目文件和代理上下文，数据中可能包含源代码、个人信息、凭据或内部业务内容。README 的“Nothing leaves your machine unless you opt in”描述的是本地优先边界，不等于已经完成企业级隐私合规、访问控制、加密存储或审计认证。
- 仅在拥有数据处理授权的本地或测试环境中导入对话和项目内容。
- 启用共享 hub、Milvus Server、Zilliz Cloud 或其他外部服务前，核对数据传输范围、访问权限和组织合规要求。
- 不要把 API 密钥、数据库令牌或个人敏感信息直接写入 palace、Compose 文件、命令历史或日志。
- 使用 Docker 时保留数据卷边界，核对挂载目录的读写权限，避免把不必要的宿主机路径暴露给容器。
- 代理技能会影响记忆检索和任务委派流程，应在授权范围内审查其输入、输出和可访问项目。
README 还特别提醒 Claude Code 会话在没有自动保存 hooks 的情况下 30 天后过期，并提供了保留设置清单。该提示属于项目使用说明，不应被理解为 MemPalace 对第三方会话平台数据保留策略的控制或承诺。
许可证与商用条款
仓库 LICENSE 文件声明项目采用 MIT License，版权所有信息为“Copyright (c) 2026 MemPalace Contributors”。MIT 许可证允许获得软件的个人使用、复制、修改、合并、发布、分发、再许可和销售副本，因此从许可证文本看，可以将其用于商业软件或商业服务。
分发软件或其重要组成部分时，必须保留版权声明和许可声明。许可证同时明确软件按“原样”提供，不提供适销性、特定用途适用性和不侵权等保证，作者不承担由软件使用产生的责任；具体权利义务以仓库 LICENSE 为准。
MIT 许可证并不自动解决数据保护、第三方模型许可、云服务合同、企业内部审批或个人信息处理问题。项目本身的商用部署仍需单独核查这些外部约束，本文不对其作额外法律结论。
局限性与已知限制
项目资料对核心方向描述较完整，但没有给出完整的容量模型、并发上限、索引构建耗时、恢复流程、升级兼容矩阵或生产 SLA。使用者不应仅根据 GitHub Star 数量或 README 中的单项 benchmark 声明推导出适用于自身数据规模的性能结论。
- 原生 Termux 当前不受支持，因为 ChromaDB 和 ONNX Runtime 的编译依赖提供 Linux wheel，而不是 Android wheel。
- Android ARM64 用户需要在 Debian PRoot 容器中运行常规 Linux 包，官方资料提到有对应安装指南和 argv 保留启动器。
- Docker 默认是 CPU 镜像，GPU 加速需要使用单独的
Dockerfile.gpu；资料没有提供 GPU 镜像的完整运行命令。 - 模型首次使用时会延迟下载，模型缓存空间和首次启动网络条件会影响首次检索流程。
- 后端虽通过入口点扩展，但不同后端的部署、迁移、故障恢复和性能数据并未在给定资料中完整说明。
- Claude Code 的 30 天会话保留问题需要自动保存 hooks 配合；MemPalace 并不会自动替代第三方会话平台的保留机制。
适合谁
以下信号表明 MemPalace 与需求较匹配，判断依据来自项目的本地优先、原文存储、CLI、MCP 和可插拔后端设计。
- 需要在本机保留编码对话、项目知识和代理上下文，并希望默认不调用外部 API。
- 需要检索原始对话，而不是只接受摘要、抽取字段或重新改写后的记忆。
- 正在使用支持技能或 MCP 的编码代理，希望在回答前执行历史召回。
- 已经使用 ChromaDB，或已有 Milvus、pgvector 等基础设施，希望通过后端入口点适配。
- 能够维护 Python 虚拟环境、Docker 数据卷、模型缓存和本地备份流程。
不适合谁
以下信号意味着需要谨慎评估，或者应先等待官方资料补充，而不是直接把项目当作已验证的企业记忆平台。
- 要求官方明确提供高并发上限、SLA、审计报表、灾备指标或长期维护承诺，但当前资料没有这些信息。
- 目标环境是原生 Android/Termux，且无法使用 Debian PRoot 容器。
- 团队不允许保存原始对话，或合规要求强制使用已审计的外部数据平台。
- 需要完整的远程 hub、认证、租户隔离和网络端口文档，而当前给定资料没有提供这些接口细节。
- 只能使用非 Python 运行环境，且不接受 Docker；项目明确以 Python 包和 CLI 为主要分发形式。
常见问题与排查（FAQ / Troubleshooting）
排查应优先围绕安装来源、数据卷、标准输入和模型缓存展开。下面的问题和回答只使用仓库资料中明确的命令与行为，不扩展未核验的内部接口。
为什么不建议直接在系统 Python 中执行 pip install？
README 建议使用 uv 或 pipx 的隔离环境，以避免 Debian、Ubuntu 和 Homebrew Python 的 PEP 668 错误，也避免 chromadb、numpy、grpcio 等依赖与全局 site-packages 冲突。若确实需要直接导入 Python 包，应先创建并激活虚拟环境。
Docker 容器重启后为什么看不到原来的数据？
检查是否把宿主机或命名卷挂载到了 /data。Dockerfile 将 HOME 设置为 /data，palace、配置和模型缓存都依赖这一持久化根目录；没有卷挂载时，容器删除会丢失容器内数据。
MCP 容器启动后为什么无法完成 JSON-RPC 通信？
官方示例使用 docker run -i，因为 MCP 通过标准输入输出传输 JSON-RPC。Docker Compose 也将 stdin_open 设置为 true，并关闭 TTY；运行 MCP 时应保留这些 stdio 条件。
首次搜索时为什么需要等待或联网？
嵌入模型采用延迟下载策略，第一次使用会触发模型缓存。Dockerfile 注释列出默认 minilm 缓存约 80 MB，embeddinggemma 缓存约 300 MB；具体下载错误和重试行为，官方仓库未提供该信息。
如何确认后端配置没有写错？
先确认环境变量名称与资料一致，再确认对应依赖是否安装。ChromaDB 是默认后端；Milvus 需要相关 extra，远程连接还涉及 MEMPALACE_MILVUS_URI 和 MEMPALACE_MILVUS_TOKEN；pgvector 则要求服务端具备 vector 扩展。
为什么安装技能后 CLI 仍然不可用？
README 明确说明，安装技能本身不会安装 MemPalace CLI 或 MCP 服务端。应让 mempalace 设置技能继续完成系统变更和连接验证，或直接使用 uv tool install mempalace、pipx install mempalace 等官方安装路径。
项目地址与资源
以下链接均来自仓库资料中列出的项目地址、官方文档或 README 认可的官方来源。使用前应留意 README 对冒牌网站的警告，项目官方来源以仓库、PyPI 和官方文档为准。
