MemPalace mempalace

MemPalace

本地优先的 AI 记忆。逐字存储，可插拔后端，在 LongMemEval 上达到 96.6% R@5 原始分数——零 API 调用。

注意 谨防冒名网站。MemPalace 没有其他官方网站。唯一官方来源是此 GitHub 仓库、PyPI 包以及 mempalaceofficial.com 上的文档。任何其他域名（包括 .tech、.net 或其他 .com 变体）均为冒名网站，可能分发恶意软件。详情和时间线：docs/HISTORY.md。

重要提示 未接入自动保存钩子的 Claude Code 会话将在 30 天后过期。阅读此内容 → 需要最短的恢复/设置路径？请使用 Claude Code 保留设置检查清单。

它是什么

MemPalace 将您的对话历史存储为逐字文本，并通过语义搜索进行检索。它不会进行摘要、提取或改写。索引是结构化的——人员和项目成为翼，主题成为房间，原始内容存放在抽屉中——因此搜索可以限定范围，而不是针对扁平语料库运行。

检索层是可插拔的。当前默认使用 ChromaDB；接口定义在 mempalace/backends/base.py 中，可以替换其他后端而无需触及系统其余部分。除非您主动选择，否则不会有任何数据离开您的机器。

架构、概念和挖掘流程：mempalaceofficial.com/concepts/the-palace。

安装

MemPalace 附带一个 CLI，因此请在隔离环境中安装，以避免在 Debian/Ubuntu/Homebrew Python 上出现 PEP 668 错误，并防止 mempalace 的依赖项（chromadb、numpy、grpcio 等）与全局 site-packages 中的其他包冲突。

我们推荐使用 uv——uv tool install 会将 mempalace CLI 安装在隔离环境中并加入 PATH：

uv tool install mempalace
mempalace init ~/projects/myapp

如果您更喜欢 pipx，其工作方式相同：

pipx install mempalace

仅在已激活的虚拟环境中使用普通 pip，且您明确希望 import mempalace 可用时：

python -m venv .venv && source .venv/bin/activate
pip install mempalace

Docker

也可使用容器镜像来运行 MCP 服务器或 CLI，无需本地 Python 工具链。所有数据持久化在 /data 下（palace、配置和缓存的嵌入模型），因此请在此处挂载卷。

# 构建镜像（CPU；包含 `extract` + `spellcheck` 扩展）
docker build -t mempalace .

# 通过 stdio 运行 MCP 服务器——注意 `-i` 标志（JSON-RPC 需要 stdin）
docker run -i --rm -v mempalace-data:/data mempalace

# 运行任意 CLI 命令（挂载您要挖掘的主机目录）
docker run --rm -v mempalace-data:/data -v /path/to/project:/work mempalace mine /work
docker run --rm -v mempalace-data:/data mempalace search "why GraphQL"

将其作为 stdio 服务器接入 MCP 客户端（例如 Claude Code）：

{
  "mcpServers": {
    "mempalace": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "mempalace-data:/data", "mempalace"]
    }
  }
}

docker compose run --rm mcp 也可用（参见 docker-compose.yml）。

对于 CUDA 加速的嵌入，使用 docker build -f Dockerfile.gpu -t mempalace:gpu . 构建 GPU 变体，并使用 --gpus all 运行。在构建时自定义捆绑的扩展，例如 docker build --build-arg EXTRAS="extract,spellcheck" -t mempalace .。

存储后端

ChromaDB 是默认后端。对于可插拔后端的预览，MemPalace 还提供了 sqlite_exact 用于本地精确向量正确性检查，以及两个可选的外部服务后端——qdrant（REST）和 pgvector（Postgres）。这两个外部后端在不同基础架构（REST/字典存储和 SQL/JSONB 存储）上验证存储契约，因此不会意外地围绕某个供应商进行设计。

# 本地无服务后端
mempalace mine ~/projects/myapp --backend sqlite_exact

# Qdrant 后端，默认连接到 http://localhost:6333
MEMPALACE_QDRANT_URL=http://localhost:6333 \
  mempalace mine ~/projects/myapp --backend qdrant

# Postgres + pgvector 后端，默认连接到 postgresql://localhost:5432/mempalace
# 需要可选驱动：pip install mempalace[pgvector]
# 并且服务器上需要 `vector` 扩展
MEMPALACE_PGVECTOR_DSN=postgresql://localhost:5432/mempalace \
  mempalace mine ~/projects/myapp --backend pgvector

Qdrant 还可以通过 MEMPALACE_QDRANT_API_KEY、MEMPALACE_QDRANT_NAMESPACE 和 MEMPALACE_QDRANT_TIMEOUT 进行配置；pgvector 通过 MEMPALACE_PGVECTOR_NAMESPACE 配置。两个外部后端都通过命名空间隔离租户（通过 supports_namespace_isolation 能力声明），并写入本地标记文件（qdrant_backend.json / pgvector_backend.json）以防止在错误的服务器上静默打开 palace。

当 MEMPALACE_QDRANT_URL 或 MEMPALACE_PGVECTOR_DSN 指向您自己的本地或可信自托管服务以外的任何位置时，MemPalace 会将逐字的抽屉文本和元数据发送并存储到该处。这是一个明确选择加入的后端选项，绝不是默认行为。

快速开始

# 将内容挖掘到 palace 中
mempalace mine ~/projects/myapp          # 项目文件
mempalace mine ~/.claude/projects/ --mode convos  # Claude Code 会话（使用 --wing 按项目限定范围）

# 搜索
mempalace search "why did we switch to GraphQL"

# 为新会话加载上下文
mempalace wake-up

有关 Claude Code、Gemini CLI、MCP 兼容工具和本地模型的更多信息，请参阅 mempalaceofficial.com/guide/getting-started。

基准测试

以下所有数字均可从此仓库中使用 benchmarks/BENCHMARKS.md 中的命令重现。完整的逐问题结果文件已提交到 benchmarks/results_* 目录下。

LongMemEval——检索召回率（R@5，500 个问题）：

| 模式 | R@5 | 需要 LLM | |------|-----|----------| | 原始（语义搜索，无启发式，无 LLM） | 96.6% | 无 | | 混合 v4，保留 450 个问题（在 50 个开发集上调优，训练期间未见） | 98.4% | 无 | | 混合 v4 + LLM 重排序（完整 500 个） | ≥99% | 任何有能力的模型 |

原始 96.6% 在任何阶段都不需要 API 密钥、云服务或 LLM。混合管道增加了关键词提升、时间邻近性提升和偏好模式提取；保留的 98.4% 是诚实的可泛化数字。重排序管道则提升最佳候选结果。