MemPalace/mempalace

## 它是什么 MemPalace 将你的对话历史记录存储为逐字文本，并通过语义搜索进行检索。它不会进行总结、提取或改写。 它的索引是结构化的 —— 人员和项目变身为*侧翼*（wings），主题变身为*房间*（rooms），而原始内容则存放在*抽屉*（drawers）中 —— 这样就可以对搜索进行范围限定，而不是针对扁平语料库进行搜索。 检索层是可插拔的。当前默认为 ChromaDB；其接口定义在 [`mempalace/backends/base.py`](mempalace/backends/base.py) 中，并且可以在不影响系统其余部分的情况下替换为其他后端。 除非你主动选择开启，否则任何数据都不会离开你的机器。 架构、概念和挖掘流程： [mempalaceofficial.com/concepts/the-palace](https://mempalaceofficial.com/concepts/the-palace.html)。 ## 安装说明 MemPalace 附带 CLI，因此请将其安装在隔离的环境中，以避免在 Debian/Ubuntu/Homebrew 的 Python 上出现 PEP 668 错误，并防止 mempalace 的依赖项（`chromadb`、`numpy`、`grpcio` 等）与全局 site-packages 中的其他内容发生冲突。 我们推荐使用 [`uv`](https://docs.astral.sh/uv/) —— `uv tool install` 会将 `mempalace` CLI 安装到你 PATH 上的一个隔离环境中： ``` uv tool install mempalace mempalace init ~/projects/myapp ``` 如果你愿意，[`pipx`](https://pipx.pypa.io/) 的工作方式相同： `pipx install mempalace`。 仅在你明确希望可以使用 `import mempalace` 的已激活虚拟环境中，才建议使用普通的 `pip`： ``` python -m venv .venv && source .venv/bin/activate pip install mempalace ``` ### Docker 我们还提供了容器镜像，用于在没有本地 Python 工具链的情况下运行 MCP server 或 CLI。所有数据（palace、配置和缓存的 embedding 模型）都持久化存储在 `/data` 下，因此请在该处挂载 volume。 ``` # 构建镜像（CPU；包含 `extract` + `spellcheck` extras） docker build -t mempalace . # 基于 stdio 的 MCP server — 注意 `-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 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 加速的 embeddings，请使用 `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/dict 存储和 SQL/JSONB 存储）上执行存储契约，因此它不会意外地被单一供应商的架构所局限。 ``` # 本地 no-service backend mempalace mine ~/projects/myapp --backend sqlite_exact # Qdrant backend，默认为 http://localhost:6333 MEMPALACE_QDRANT_URL=http://localhost:6333 \ mempalace mine ~/projects/myapp --backend qdrant # Postgres + pgvector backend，默认为 postgresql://localhost:5432/mempalace # 需要可选的 driver：pip install mempalace[pgvector] # 以及服务器上可用的 `vector` extension 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`。这两个外部后端都通过 namespace 隔离租户（通过 `supports_namespace_isolation` 能力对外宣告），并会写入一个本地标记文件（`qdrant_backend.json` / `pgvector_backend.json`），以防止在不知情的情况下错误地针对其他服务器开启 palace。 当 `MEMPALACE_QDRANT_URL` 或 `MEMPALACE_PGVECTOR_DSN` 指向非你自己本地或受信任的自托管服务时，MemPalace 会将逐字 drawer 文本和元数据发送并存储到那里。这是一个明确选择开启的后端选项，绝非默认行为。 ## 快速开始 ``` # 将内容挖掘到 palace 中 mempalace mine ~/projects/myapp # project files mempalace mine ~/.claude/projects/ --mode convos # Claude Code sessions (scope with --wing per project) # 搜索 mempalace search "why did we switch to GraphQL" # 为新会话加载上下文 mempalace wake-up ``` 有关 Claude Code、Gemini CLI、[Antigravity](https://mempalaceofficial.com/guide/antigravity.html)、 MCP 兼容工具和本地模型的详细信息，请参见 [mempalaceofficial.com/guide/getting-started](https://mempalaceofficial.com/guide/getting-started.html)。 ## 基准测试 下面所有数据都可以通过 [`benchmarks/BENCHMARKS.md`](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 key、云服务或 LLM。混合 pipeline 增加了关键词加权、时间邻近度加权和偏好模式提取；留出集的 98.4% 是真正具备泛化能力的客观数据。 重排 pipeline 使用 LLM 读取器从检索出的 top-20 会话中提升最佳候选内容。它适用于任何能力尚可的模型 —— 我们已经使用 Claude Haiku、Claude Sonnet 以及通过 Ollama Cloud 运行的 minimax-m2.7 复现了该结果（无 Anthropic 依赖）。原始分数和重排分数之间的差距与模型无关；我们没有将“100%”作为宣传重点，因为剩下的 0.6% 是通过检查特定的错误答案达到的，`benchmarks/BENCHMARKS.md` 将这种情况标记为“针对测试集进行教学”（teaching to the test）。 **其他基准测试 (完整结果见 [`benchmarks/BENCHMARKS.md`](benchmarks/BENCHMARKS.md)):** | 基准测试 | 指标 | 分数 | 备注 | |---|---|---|---| | LoCoMo (会话, top-10, 无重排) | R@10 | 60.3% | 1,986 个问题 | | LoCoMo (混合 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 的横向对比。这些项目在不同的数据集划分上发布了不同的指标，将检索召回率与端到端 QA 准确率放在一起对比是不客观的。如需了解其发布的数据，请查看各个项目自己的研究页面。 **复现所有结果：** ``` git clone https://github.com/MemPalace/mempalace.git cd mempalace uv sync --extra dev # or: 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](https://mempalaceofficial.com/concepts/knowledge-graph.html)。 ## MCP server 29 个 MCP 工具涵盖了 palace 读写、知识图谱操作、 跨侧翼导航、drawer 管理和 agent 日志。安装方式和完整的工具列表： [mempalaceofficial.com/reference/mcp-tools](https://mempalaceofficial.com/reference/mcp-tools.html)。 ## Agent 每个专门的 agent 在 palace 中都有自己专属的侧翼和日志。 可在运行时通过 `mempalace_list_agents` 发现 —— 不会增加你的 系统 prompt 的冗余： [mempalaceofficial.com/concepts/agents](https://mempalaceofficial.com/concepts/agents.html)。 ## 自动保存钩子 针对 **Claude Code、Codex CLI 和 Cursor IDE** 的自动保存钩子可以做到 定期保存，并在上下文压缩之前进行保存： - Claude Code + Codex → [mempalaceofficial.com/guide/hooks](https://mempalaceofficial.com/guide/hooks.html) - Cursor IDE (增加会话开始时的召回，并在压缩前进行 transcript 快照) → [mempalaceofficial.com/guide/cursor-hooks](https://mempalaceofficial.com/guide/cursor-hooks.html) 如果在时间紧迫的情况下进行安装，请从 [Claude Code 留存设置清单](https://mempalaceofficial.com/guide/claude-code-retention.html) 开始： 连接钩子，备份现有的 JSONL transcript，并使用 `mempalace mine ~/.claude/projects/ --mode convos` 对它们进行回填。 如果需要在钩子产生的文件级分块基础上实现单条消息召回， 请定期运行 `mempalace sweep ` —— 它会为每条用户/助手消息存储一个 逐字 drawer，操作是幂等的且支持断点续传。 ## 环境要求 - Python 3.9+ - 一个 vector-store 后端（默认为 ChromaDB） - 约 300 MB 磁盘空间用于 embedding 模型。引导程序 (`python -m mempalace.onboarding`) 提供 `embeddinggemma-300m`（多语言，支持 100 多种语言，推荐）或 `all-MiniLM-L6-v2`（仅限英语，约 30 MB）选项。有关详细信息和迁移说明，请参阅 [`mempalace/embedding.py`](mempalace/embedding.py) 中的 docstring。 核心基准测试流程不需要 API key。 ## 文档 - 快速开始 → [mempalaceofficial.com/guide/getting-started](https://mempalaceofficial.com/guide/getting-started.html) - CLI 参考 → [mempalaceofficial.com/reference/cli](https://mempalaceofficial.com/reference/cli.html) - Python API → [mempalaceofficial.com/reference/python-api](https://mempalaceofficial.com/reference/python-api.html) - 完整的基准测试方法 → [benchmarks/BENCHMARKS.md](benchmarks/BENCHMARKS.md) - 发布说明 → [CHANGELOG.md](CHANGELOG.md) - 更正与公开声明 → [docs/HISTORY.md](docs/HISTORY.md) ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：ChromaDB, Python, 人工智能, 无后门, 本地化, 用户模式Hook绕过, 记忆系统, 语义检索, 请求拦截, 逆向工具