wehub-resource-sync
3e4a9af0d6
Tests / test-linux (3.11) (push) Has been cancelled
Tests / test-linux (3.13) (push) Has been cancelled
Tests / test-linux (3.9) (push) Has been cancelled
Tests / test-windows (push) Has been cancelled
Tests / test-macos (push) Has been cancelled
Tests / lint (push) Has been cancelled
Docker / build (push) Has been cancelled
Docker / build-gpu (push) Has been cancelled
236 lines
12 KiB
Markdown
236 lines
12 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/MemPalace/mempalace) · [上游 README](https://github.com/MemPalace/mempalace/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<div align="center">
|
||
|
||
<img src="assets/mempalace_logo.png" alt="MemPalace" width="240">
|
||
|
||
# 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]
|
||
|
||
</div>
|
||
|
||
> [!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 <name>`、`MEMPALACE_BACKEND=<name>` 或 `"backend": "<name>"` 在 `config.json` 中选择。连接变量、命名空间行为与部署说明见 [存储后端](/guide/configuration#storage-backends)。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 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](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 题）：**
|
||
|
||
| 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`](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 准确率并列并非诚实比较。请参阅各项目自己的研究页面获取其公布数字。
|
||
|
||
**复现所有结果：**
|
||
|
||
```bash
|
||
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](https://mempalaceofficial.com/concepts/knowledge-graph.html).
|
||
|
||
## MCP server
|
||
|
||
35 个 MCP 工具涵盖 palace 读写、knowledge-graph 操作、跨 wing 导航、drawer 管理和 agent diary。安装说明与完整工具列表：
|
||
[mempalaceofficial.com/reference/mcp-tools](https://mempalaceofficial.com/reference/mcp-tools.html).
|
||
|
||
## Agents
|
||
|
||
每位 specialist agent 在 palace 中拥有独立的 wing 和 diary。
|
||
运行时可通过 `mempalace_list_agents` 发现——不会让你的 system prompt 臃肿：
|
||
[mempalaceofficial.com/concepts/agents](https://mempalaceofficial.com/concepts/agents.html).
|
||
|
||
## Auto-save hooks
|
||
|
||
面向 **Claude Code、Codex CLI 和 Cursor IDE** 的 Auto-save hooks 会定期保存，并在上下文压缩（context compression）之前保存：
|
||
|
||
- Claude Code + Codex →
|
||
[mempalaceofficial.com/guide/hooks](https://mempalaceofficial.com/guide/hooks.html)
|
||
- Cursor IDE（增加 session-start recall，并在压缩前生成 transcript 快照）→
|
||
[mempalaceofficial.com/guide/cursor-hooks](https://mempalaceofficial.com/guide/cursor-hooks.html)
|
||
|
||
如果你是在时间紧迫的情况下安装，请先从
|
||
[Claude Code retention setup checklist](https://mempalaceofficial.com/guide/claude-code-retention.html):
|
||
开始，配置 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`](mempalace/embedding.py) 中的 docstring 及迁移说明。
|
||
|
||
核心 benchmark 路径无需 API key。
|
||
|
||
## Docs
|
||
|
||
- 入门 → [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)
|
||
- 完整 benchmark 方法论 → [benchmarks/BENCHMARKS.md](benchmarks/BENCHMARKS.md)
|
||
- 发行说明 → [CHANGELOG.md](CHANGELOG.md)
|
||
- 勘误与公开说明 → [docs/HISTORY.md](docs/HISTORY.md)
|
||
|
||
## Contributing
|
||
|
||
欢迎提交 PR。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
||
|
||
## License
|
||
|
||
MIT — 详见 [LICENSE](LICENSE)。
|
||
|
||
<!-- Link Definitions -->
|
||
[version-shield]: https://img.shields.io/badge/version-3.5.0-4dc9f6?style=flat-square&labelColor=0a0e14
|
||
[release-link]: https://github.com/MemPalace/mempalace/releases
|
||
[python-shield]: https://img.shields.io/badge/python-3.9+-7dd8f8?style=flat-square&labelColor=0a0e14&logo=python&logoColor=7dd8f8
|
||
[python-link]: https://www.python.org/
|
||
[license-shield]: https://img.shields.io/badge/license-MIT-b0e8ff?style=flat-square&labelColor=0a0e14
|
||
[license-link]: https://github.com/MemPalace/mempalace/blob/main/LICENSE
|
||
[discord-shield]: https://img.shields.io/badge/discord-join-5865F2?style=flat-square&labelColor=0a0e14&logo=discord&logoColor=5865F2
|
||
[discord-link]: https://discord.com/invite/ycTQQCu6kn
|