📦 MemPalace/mempalace —— 最佳基准测试的开源 AI 记忆系统

注意

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

---

MemPalace 将你的对话历史以逐字文本形式存储，并通过语义搜索进行检索。它不会进行摘要、提取或转述。索引是结构化的——人与项目成为 侧翼（wings），主题成为 房间（rooms），原始内容驻留在 抽屉（drawers） 中——因此搜索可以限定范围，而不是在扁平语料库上运行。

检索层是可插拔的。当前默认为 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。

如果你希望直接使用 import mempalace，请仅在已激活的虚拟环境中使用 pip 安装：

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

还提供了容器镜像，无需本地 Python 工具链即可运行 MCP 服务器或 CLI。所有数据（宫殿、配置及缓存的嵌入模型）均持久化在 /data 下，因此请将卷挂载到该路径。

# 构建镜像（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"

在 MCP 客户端（如 Claude Code）中以 stdio 服务器方式接入：

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

docker compose run --rm mcp 也可用（参见 docker-compose.yml）。如需 CUDA 加速嵌入，可构建 GPU 版本：docker build -f Dockerfile.gpu -t mempalace:gpu . 并使用 --gpus all 运行。你还可以在构建时自定义内置的 extras，例如 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），防止在错误的服务器上静默打开宫殿。

当 MEMPALACE_QDRANT_URL 或 MEMPALACE_PGVECTOR_DSN 指向非本地或非你自己托管的受信服务时，MemPalace 会将逐字抽屉文本和元数据发送并存储到那里。这是一种显式选择的后端行为，绝非默认设置。

# 将内容挖掘到宫殿中
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、Antigravity、兼容 MCP 的工具和本地模型的用法，请参阅 mempalaceofficial.com/guide/getting-started。

---

以下所有数值均可通过本仓库中的命令复现，详见 benchmarks/BENCHMARKS.md。每个问题的完整结果文件已提交在 benchmarks/results_* 下。

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

模式	R@5	是否需要 LLM
Raw（纯语义搜索，无启发式，无 LLM）	96.6%	不需要
Hybrid v4，留出 450 题（在 50 开发集上调优，未参与训练）	98.4%	不需要
Hybrid v4 + LLM 重排（全部 500 题）	≥99%	任何有能力模型

纯语义搜索的 96.6% 无需 API 密钥、无需云服务、且任何阶段都不需要 LLM。混合管线增加了关键词增强、时间邻近度增强和偏好模式提取；留出的 98.4% 是可靠的泛化结果。

重排管线利用 LLM 阅读器从检索到的前 20 个会话中选出最佳候选项。它可与任何能力足够强的模型配合使用——我们已用 Claude Haiku、Claude Sonnet 以及通过 Ollama Cloud 运行的 minimax-m2.7 验证（不依赖 Anthropic）。原始得分与重排之间的提升与模型无关；我们未以“100%”作为标题，因为那最后的 0.6% 是通过检查特定错误实现的，benchmarks/BENCHMARKS.md 中已指出这属于针对测试的训练。

其他基准测试（完整结果见 benchmarks/BENCHMARKS.md）：

基准	指标	得分	备注
LoCoMo（会话，Top-10，无重排）	R@10	60.3%	1,986 个问题
LoCoMo（hybrid v5，Top-10，无重排）	R@10	88.9%	同组
ConvoMem（所有类别，250 项）	平均召回	92.9%	每类 50
MemBench（ACL 2025，8,500 项）	R@5	80.3%	所有类别

我们有意未与 Mem0、Mastra、Hindsight、Supermemory 或 Zep 进行并列对比。这些项目在不同划分上报告了不同指标，将检索召回与端到端问答准确率放在一起对比并不公正。相关发布数据请查阅各项目的研究页面。

复现所有结果：

git clone https://github.com/MemPalace/mempalace.git
cd mempalace
uv sync --extra dev   # 或者：pip install -e ".[dev]"
# 参见 benchmarks/README.md 了解数据集下载命令
uv run python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json

---

MemPalace 内置了一个带有有效期窗口的时态实体关系图——支持添加、查询、失效、时间线——由本地 SQLite 支持。用法与工具参考：mempalaceofficial.com/concepts/knowledge-graph。

35 个 MCP 工具覆盖了宫殿的读写、知识图谱操作、跨翼导航、抽屉管理和代理日记。安装和完整工具列表见：mempalaceofficial.com/reference/mcp-tools。

每个专家代理在宫殿中都拥有自己的翼和日记。运行时可通过 mempalace_list_agents 发现——不会向系统提示中添加冗余信息：mempalaceofficial.com/concepts/agents。

为 Claude Code、Codex CLI 和 Cursor IDE 提供的自动保存钩子会定期保存并在上下文压缩前保存：

如果你在时间紧迫的情况下安装，请从 Claude Code 保留设置清单 开始：配置钩子，备份已有的 JSONL 转录文件，并使用 mempalace mine ~/.claude/projects/ --mode convos 进行回填。

若要在钩子生成的文件级块之上获取每条消息的召回，可定期运行 mempalace sweep <transcript-dir> ——它会为每条用户/助手消息存储一个逐字抽屉，幂等且支持中断恢复。

---

• Python 3.9+
• 一个向量存储后端（默认为 ChromaDB）
• 约 300 MB 磁盘空间用于嵌入模型。引导流程（python -m mempalace.onboarding）提供了 embeddinggemma-300m（多语言，支持 100+ 语言，推荐）或 all-MiniLM-L6-v2（仅英文，~30 MB）。详情与迁移说明见 mempalace/embedding.py。

核心基准测试路径无需 API 密钥。

欢迎提交 PR。参见 CONTRIBUTING.md。

MIT 许可 —— 详见 LICENSE。

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 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 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:

uv tool install mempalace
mempalace init ~/projects/myapp

pipx works the same way if you prefer it: pipx install mempalace.

Prefer plain pip only inside an activated virtualenv where you explicitly want import mempalace available:

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

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.

# 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:

{
  "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 ..

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.

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

# Qdrant backend, defaulting to http://localhost:6333
MEMPALACE_QDRANT_URL=http://localhost:6333 \
  mempalace 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 \
  mempalace 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.

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

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

# Load context for a new session
mempalace wake-up

For Claude Code, Gemini CLI, Antigravity, MCP-compatible tools, and local models, see mempalaceofficial.com/guide/getting-started.

---

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_*.

LongMemEval — retrieval recall (R@5, 500 questions):

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. It works with any reasonably capable model — we have reproduced it with Claude Haiku, Claude Sonnet, and minimax-m2.7 via Ollama Cloud (no Anthropic dependency). The gap between raw and reranked is model-agnostic; we do not headline a "100%" number because the last 0.6% was reached by inspecting specific wrong answers, which benchmarks/BENCHMARKS.md flags as teaching to the test.

Other benchmarks (full results inbenchmarks/BENCHMARKS.md):

Benchmark	Metric	Score	Notes
LoCoMo (session, top-10, no rerank)	R@10	60.3%	1,986 questions
LoCoMo (hybrid v5, top-10, no rerank)	R@10	88.9%	Same set
ConvoMem (all categories, 250 items)	Avg recall	92.9%	50 per category
MemBench (ACL 2025, 8,500 items)	R@5	80.3%	All categories

We deliberately do not include a side-by-side comparison against Mem0, Mastra, Hindsight, Supermemory, or Zep. Those projects publish different metrics on different splits, and placing retrieval recall next to end-to-end QA accuracy is not an honest comparison. See each project's own research page for their published numbers.

Reproducing every result:

git clone https://github.com/MemPalace/mempalace.git
cd mempalace
uv sync --extra dev   # or: pip install -e ".[dev]"
# see benchmarks/README.md for dataset download commands
uv run python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json

---

MemPalace includes a temporal entity-relationship graph with validity windows — add, query, invalidate, timeline — backed by local SQLite. Usage and tool reference: mempalaceofficial.com/concepts/knowledge-graph.

35 MCP tools cover palace reads/writes, knowledge-graph operations, cross-wing navigation, drawer management, and agent diaries. Installation and the full tool list: mempalaceofficial.com/reference/mcp-tools.

Each specialist agent gets its own wing and diary in the palace. Discoverable at runtime via mempalace_list_agents — no bloat in your system prompt: mempalaceofficial.com/concepts/agents.

Auto-save hooks for Claude Code, Codex CLI, and Cursor IDE save periodically and before context compression:

If you are installing under time pressure, start with the Claude Code retention setup checklist: wire the hooks, back up existing JSONL transcripts, and backfill them with mempalace mine ~/.claude/projects/ --mode convos.

For per-message recall on top of the file-level chunks the hooks produce, run mempalace sweep <transcript-dir> periodically — it stores one verbatim drawer per user/assistant message, idempotent and resume-safe.

---

• Python 3.9+
• A vector-store backend (ChromaDB by default)
• ~300 MB disk for the embedding model. Onboarding (python -m mempalace.onboarding) offers embeddinggemma-300m (multilingual, 100+ languages, recommended) or all-MiniLM-L6-v2 (English-only, ~30 MB). See the docstring at mempalace/embedding.py for details and migration notes.

No API key is required for the core benchmark path.

PRs welcome. See CONTRIBUTING.md.

MIT — see LICENSE.