mempalace--mempalace/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

MemPalace

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

Caution

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

Important

若未接入自动保存钩子，Claude Code 会话会在 30 天后过期。 阅读此文 →

需要最短的恢复/设置路径？使用 Claude Code 保留设置清单.

---

它是什么

MemPalace 将你的对话历史以逐字文本形式存储，并通过语义搜索（semantic search）检索。它不进行摘要、抽取或改写。索引是结构化的——人物和项目成为 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。

仅在已激活的 virtualenv 中、且你明确希望 import mempalace 可用时，才使用纯 pip：

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

Docker

也提供容器镜像，可在无本地 Python 工具链的情况下运行 MCP server 或 CLI。所有内容持久化在 /data（palace、config 及缓存的 embedding 模型）下，因此请在那里挂载卷。

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

作为 stdio server 接入 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 加速的 embedding，请用 docker build -f Dockerfile.gpu -t mempalace:gpu . 构建 GPU 变体，并以 --gpus all 运行。可在构建时自定义捆绑的 extras，例如 docker build --build-arg EXTRAS="extract,spellcheck" -t mempalace .。

存储后端

ChromaDB 为默认后端，无需配置。MemPalace 还提供可插拔后端契约，并在刻意不同的底层上验证，以免契约无意间围绕单一厂商定型。所有非默认后端均需主动启用。

Backend	Mode	Install	Namespaces	Lexical	Configure with
chroma （默认）	本地（嵌入式）	内置	–	✓	–
sqlite_exact	本地（精确）	内置	–	✓	–
milvus	本地（Lite）· 服务端可选	mempalace[milvus]	✓	✓	MEMPALACE_MILVUS_URI
qdrant	服务端（REST）	内置	✓	✓	MEMPALACE_QDRANT_URL
pgvector	服务端（Postgres）	mempalace[pgvector]	✓	✓	MEMPALACE_PGVECTOR_DSN

通过 --backend <name>、MEMPALACE_BACKEND=<name> 或 "backend": "<name>" 在 config.json 中选择。连接变量、命名空间行为与部署说明见 存储后端。

快速开始

# 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

适用于 Claude Code、Gemini CLI、Antigravity,、兼容 MCP 的工具及本地模型，见 mempalaceofficial.com/guide/getting-started.

---

基准测试

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

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

Mode	R@5	LLM required
原始（语义搜索，无启发式，无 LLM）	96.6%	无
Hybrid v4，held-out 450 题（在 50 题 dev 上调优，训练时未见）	98.4%	无
Hybrid v4 + LLM rerank（完整 500 题）	≥99%	任意能力足够的模型

原始 96.6% 在任何阶段都不需要 API key、云服务或 LLM。hybrid 流水线增加了关键词增强、时间邻近增强与偏好模式抽取；held-out 98.4% 是诚实的可泛化指标。

rerank 流水线使用 LLM reader 从检索到的 top-20 会话中提升最佳候选。它可与任意能力足够的模型配合——我们已在 Claude Haiku、Claude Sonnet 以及通过 Ollama Cloud 的 minimax-m2.7 上复现（不依赖 Anthropic）。原始与 rerank 之间的差距与模型无关；我们不以「100%」作为标题数字，因为最后 0.6% 是通过检查特定错误答案达到的，而 benchmarks/BENCHMARKS.md 将其标记为对测试集过拟合（teaching to the test）。

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

Benchmark	Metric	Score	Notes
LoCoMo（session，top-10，无 rerank）	R@10	60.3%	1,986 题
LoCoMo（hybrid v5，top-10，无 rerank）	R@10	88.9%	同一数据集
ConvoMem（全类别，250 条）	平均召回	92.9%	每类 50 条
MemBench（ACL 2025，8,500 条）	R@5	80.3%	全类别

我们刻意不与 Mem0、Mastra、Hindsight、Supermemory 或 Zep 做并排对比。这些项目在不同划分上发布不同指标，将检索召回与端到端 QA 准确率并列并非诚实比较。请参阅各项目自己的研究页面获取其公布数字。

复现所有结果：

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 包含带有效期窗口（validity windows）的时态实体关系图（temporal entity-relationship graph）——支持 add、query、invalidate、timeline——由本地 SQLite 支撑。 用法与工具参考： mempalaceofficial.com/concepts/knowledge-graph.

MCP server

35 个 MCP 工具涵盖 palace 读写、knowledge-graph 操作、跨 wing 导航、drawer 管理和 agent diary。安装说明与完整工具列表： mempalaceofficial.com/reference/mcp-tools.

Agents

每位 specialist agent 在 palace 中拥有独立的 wing 和 diary。 运行时可通过 mempalace_list_agents 发现——不会让你的 system prompt 臃肿： mempalaceofficial.com/concepts/agents.

Auto-save hooks

面向 Claude Code、Codex CLI 和 Cursor IDE 的 Auto-save hooks 会定期保存，并在上下文压缩（context compression）之前保存：

• Claude Code + Codex → mempalaceofficial.com/guide/hooks
• Cursor IDE（增加 session-start recall，并在压缩前生成 transcript 快照）→ mempalaceofficial.com/guide/cursor-hooks

如果你是在时间紧迫的情况下安装，请先从 Claude Code retention setup checklist: 开始，配置 hooks，备份现有 JSONL transcript，并用 mempalace mine ~/.claude/projects/ --mode convos 回填它们。

若要在 hooks 生成的文件级 chunk 之上实现逐消息 recall，请定期运行 mempalace sweep <transcript-dir>——它为每条 user/assistant 消息存储一个 verbatim drawer，具有幂等性且可安全恢复。

---

Requirements

• Python 3.9+
• 向量存储后端（vector-store backend，默认 ChromaDB）
• 嵌入模型约需 ~300 MB 磁盘空间。入门流程（python -m mempalace.onboarding）提供 embeddinggemma-300m（多语言，100+ 种语言，推荐）或 all-MiniLM-L6-v2（仅英语，约 ~30 MB）。详见 mempalace/embedding.py 中的 docstring 及迁移说明。

核心 benchmark 路径无需 API key。

Docs

• 入门 → mempalaceofficial.com/guide/getting-started
• CLI 参考 → mempalaceofficial.com/reference/cli
• Python API → mempalaceofficial.com/reference/python-api
• 完整 benchmark 方法论 → benchmarks/BENCHMARKS.md
• 发行说明 → CHANGELOG.md
• 勘误与公开说明 → docs/HISTORY.md

Contributing

欢迎提交 PR。请参阅 CONTRIBUTING.md。

License

MIT — 详见 LICENSE。