# MemPalace
本地优先的 AI 记忆。逐字存储、可插拔后端，LongMemEval 上 R@5 raw 达 96.6% —— 零 API 调用。
[![][version-shield]][release-link]
[![][python-shield]][python-link]
[![][license-shield]][license-link]
[![][discord-shield]][discord-link]
> [!CAUTION]
> **谨防仿冒网站。** MemPalace 没有其他官方网站。**唯一**官方来源是本 **[GitHub 仓库](https://github.com/MemPalace/mempalace)**,、**[PyPI 包](https://pypi.org/project/mempalace/)**,以及 **[mempalaceofficial.com](https://mempalaceofficial.com)**. 上的文档。任何其他域名（包括 `.tech`、`.net` 或其他 `.com` 变体）均为仿冒站点，可能分发恶意软件。详情与时间线见 [docs/HISTORY.md](docs/HISTORY.md)。
> [!IMPORTANT]
> **若未接入自动保存钩子，Claude Code 会话会在 30 天后过期。** [阅读此文 →](https://github.com/MemPalace/mempalace/discussions/1388)
>
> 需要最短的恢复/设置路径？使用 [Claude Code 保留设置清单](https://mempalaceofficial.com/guide/claude-code-retention.html).
---
## 它是什么
MemPalace 将你的对话历史以逐字文本形式存储，并通过语义搜索（semantic search）检索。它不进行摘要、抽取或改写。索引是结构化的——人物和项目成为 *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 上的隔离环境中：
```bash
uv tool install mempalace
mempalace init ~/projects/myapp
```
若你更偏好它，[`pipx`](https://pipx.pypa.io/) 用法相同：
`pipx install mempalace`。
仅在已激活的 virtualenv 中、且你明确希望 `import mempalace` 可用时，才使用纯 `pip`：
```bash
python -m venv .venv && source .venv/bin/activate
pip install mempalace
```
### Docker
也提供容器镜像，可在无本地 Python 工具链的情况下运行 MCP server 或 CLI。所有内容持久化在 `/data`（palace、config 及缓存的 embedding 模型）下，因此请在那里挂载卷。
```bash
# 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）：
```json
{
"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