MemPalace / mempalace

MemPalace Local-first AI memory. Verbatim storage, pluggable backend, 96.6% R@5 raw on LongMemEval — zero API calls. MemPalace 是一个本地优先的 AI 记忆系统。它提供逐字存储、可插拔后端，在 LongMemEval 测试中原始 R@5 指标达到 96.6% —— 且无需任何 API 调用。

Caution: Beware of impostor sites. MemPalace has no other official websites. The only official sources are this GitHub repository, the PyPI package, and the docs at mempalaceofficial.com. Any other domain (including .tech, .net, or other .com variants) is an impostor and may distribute malware. Details and timeline: docs/HISTORY.md. 警告：谨防冒充网站。MemPalace 没有其他官方网站。唯一的官方来源是此 GitHub 仓库、PyPI 软件包以及 mempalaceofficial.com 上的文档。任何其他域名（包括 .tech、.net 或其他 .com 变体）均为冒充，可能传播恶意软件。详情及时间线请见：docs/HISTORY.md。

Important: Claude Code sessions expire in 30 days without auto-save hooks wired. Read this → Need the shortest recovery/setup path? Use the Claude Code retention setup checklist. 重要提示：若未配置自动保存钩子，Claude Code 会话将在 30 天后过期。请阅读此内容 → 需要最快捷的恢复/设置路径？请使用 Claude Code 保留设置清单。

What it is: MemPalace stores your conversation history as verbatim text and retrieves it with semantic search. It does not summarize, extract, or paraphrase. The index is structured — people and projects become wings, topics become rooms, and original content lives in drawers — so searches can be scoped rather than run against a flat corpus. The retrieval layer is pluggable. The current default is ChromaDB; the interface is defined in mempalace/backends/base.py and alternative backends can be dropped in without touching the rest of the system. Nothing leaves your machine unless you opt in. Architecture, concepts, and mining flows: mempalaceofficial.com/concepts/the-palace. 它是什么：MemPalace 将您的对话历史记录存储为逐字文本，并通过语义搜索进行检索。它不会进行总结、提取或改写。索引结构化——人员和项目成为“侧翼（wings）”，主题成为“房间（rooms）”，原始内容存放在“抽屉（drawers）”中——因此搜索可以限定范围，而不是在扁平的语料库中运行。检索层是可插拔的。目前默认使用 ChromaDB；接口定义在 mempalace/backends/base.py 中，无需触动系统其余部分即可替换其他后端。除非您主动选择，否则没有任何数据会离开您的机器。架构、概念和挖掘流程请见：mempalaceofficial.com/concepts/the-palace。

Install: MemPalace ships a CLI, so install it in an isolated environment to avoid PEP 668 errors on Debian/Ubuntu/Homebrew Pythons and to keep mempalace’s deps (chromadb, numpy, grpcio, …) from conflicting with anything else in your global site-packages. We recommend uv — uv tool install puts the mempalace CLI in an isolated environment on your PATH: 安装：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 works the same way if you prefer it: 如果您更喜欢 pipx，它的工作方式相同：

pipx install mempalace

Prefer plain pip only inside an activated virtualenv where you explicitly want import mempalace available: 如果您明确希望在激活的虚拟环境中导入 mempalace，则可以使用普通的 pip：

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

Docker: A container image is also available for running the MCP server or the CLI without a local Python toolchain. Everything persists under /data (palace, config, and the cached embedding model), so mount a volume there. Docker：我们还提供了一个容器镜像，用于在没有本地 Python 工具链的情况下运行 MCP 服务器或 CLI。所有内容都持久化在 /data 下（包括 palace、配置和缓存的嵌入模型），因此请务必挂载卷。

# Build the image (CPU; bundles the `extract` + `spellcheck` extras)
docker build -t mempalace .

# MCP server over stdio — note the `-i` flag (JSON-RPC needs stdin)
docker run -i --rm -v mempalace-data:/data mempalace

# Run any CLI command instead (mount the host directory you want to mine)
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"

Wire it into an MCP client (e.g. Claude Code) as a stdio server: 将其作为 stdio 服务器连接到 MCP 客户端（例如 Claude Code）：

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

docker compose run —rm mcp works too (see docker-compose.yml). For CUDA-accelerated embeddings, build the GPU variant with docker build -f Dockerfile.gpu -t mempalace:gpu . and run it with --gpus all. Customise the bundled extras at build time, e.g. docker build --build-arg EXTRAS="extract,spellcheck" -t 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 ..

Storage backends: ChromaDB is the default. For the pluggable-backend preview, MemPalace also ships sqlite_exact for local exact-vector correctness checks, and two opt-in external service backends — qdrant (REST) and pgvector (Postgres). The two external backends exercise the storage contract on different substrates (a REST/dict store and a SQL/JSONB store), so it is not accidentally shaped around one vendor. 存储后端：默认使用 ChromaDB。作为可插拔后端的预览，MemPalace 还提供了用于本地精确向量正确性检查的 sqlite_exact，以及两个可选的外部服务后端——qdrant (REST) 和 pgvector (Postgres)。这两个外部后端在不同的基底（REST/字典存储和 SQL/JSONB 存储）上执行存储契约，因此不会意外地绑定在某个特定供应商上。

# local no-service backend
memaplace mine ~/projects/myapp --backend sqlite_exact

# Qdrant backend, defaulting to http://localhost:6333
MEMPALACE_QDRANT_URL=http://localhost:6333 \
memaplace mine ~/projects/myapp --backend qdrant

# Postgres + pgvector backend, defaulting to postgresql://localhost:5432/mempalace
# needs the optional driver: pip install mempalace[pgvector]
# and the `vector` extension available on the server
MEMPALACE_PGVECTOR_DSN=postgresql://localhost:5432/mempalace \
memaplace mine ~/projects/myapp --backend pgvector

Qdrant can also be configured with MEMPALACE_QDRANT_API_KEY, MEMPALACE_QDRANT_NAMESPACE, and MEMPALACE_QDRANT_TIMEOUT; pgvector with MEMPALACE_PGVECTOR_NAMESPACE. Both external backends isolate tenants by namespace (advertised via the supports_namespace_isolation capability) and write a local marker (qdrant_backend.json / pgvector_backend.json) to guard against silently opening a palace against the wrong server. When MEMPALACE_QDRANT_URL or MEMPALACE_PGVECTOR_DSN points anywhere other than your own local or trusted self-hosted service, MemPalace will send and store verbatim drawer text and metadata there. That is an explicit opt-in backend choice, never the default. Qdrant 还可以通过 MEMPALACE_QDRANT_API_KEY、MEMPALACE_QDRANT_NAMESPACE 和 MEMPALACE_QDRANT_TIMEOUT 进行配置；pgvector 则通过 MEMPALACE_PGVECTOR_NAMESPACE 配置。两个外部后端都通过命名空间隔离租户（通过 supports_namespace_isolation 能力声明），并写入本地标记文件（qdrant_backend.json / pgvector_backend.json）以防止错误地连接到错误的服务器。当 MEMPALACE_QDRANT_URL 或 MEMPALACE_PGVECTOR_DSN 指向非本地或非受信任的自托管服务时，MemPalace 会将逐字抽屉文本和元数据发送并存储在那里。这是一种明确的选择性后端配置，绝非默认行为。

Quickstart: 快速入门：

# Mine content into the palace
memaplace mine ~/projects/myapp # project files
memaplace mine ~/.claude/projects/ --mode convos # Claude Code sessions (scope with --wing per project)

# Search
memaplace search "why did we switch to GraphQL"

# Load context for a new session
memaplace wake-up

For Claude Code, Gemini CLI, MCP-compatible tools, and local models, see mempalaceofficial.com/guide/getting-started. 关于 Claude Code、Gemini CLI、MCP 兼容工具和本地模型的使用，请参阅 mempalaceofficial.com/guide/getting-started。

Benchmarks: All numbers below are reproducible from this repository with the commands in benchmarks/BENCHMARKS.md. Full per-question result files are committed under benchmarks/results_. 基准测试：以下所有数据均可使用 benchmarks/BENCHMARKS.md 中的命令从本仓库中复现。每个问题的完整结果文件已提交至 benchmarks/results_。

LongMemEval — retrieval recall (R@5, 500 questions): LongMemEval — 检索召回率（R@5，500 个问题）：

Mode	R@5	LLM required
Raw (semantic search, no heuristics, no LLM)	96.6%	None
Hybrid v4, held-out 450q (tuned on 50 dev, not seen during training)	98.4%	None
Hybrid v4 + LLM rerank (full 500)	≥99%	Any capable model

The raw 96.6% requires no API key, no cloud, and no LLM at any stage. The hybrid pipeline adds keyword boosting, temporal-proximity boosting, and preference-pattern extraction; the held-out 98.4% is the honest generalisable figure. The rerank pipeline promotes the best candidate out of the top-20 retrieved sessions using an LLM reader. 原始的 96.6% 召回率在任何阶段都不需要 API 密钥、云服务或 LLM。混合流水线增加了关键词增强、时间邻近度增强和偏好模式提取；98.4% 是在留出数据集上的真实可泛化数据。重排序流水线使用 LLM 阅读器从检索到的前 20 个会话中提升最佳候选者。