## 项目概述

MemPalace 是一个本地优先的开源 AI 记忆系统，旨在为 AI 智能体提供持久、可检索的长期记忆。它通过语义搜索从对话历史中检索信息，并采用独特的“宫殿”结构（wings、rooms、drawers）来组织记忆。项目强调本地运行、数据隐私和零 API 依赖，在 LongMemEval 基准测试中，原始模式下的检索召回率（R@5）达到 96.6%。

## 核心功能

- **逐字存储与语义检索**：不进行摘要或改写，以原始文本存储对话，并通过语义搜索进行检索。
- **可插拔存储后端**：默认使用 ChromaDB，也支持 sqlite_exact、Milvus、Qdrant、pgvector 等后端。
- **MCP 服务器**：提供 45 个 MCP 工具，用于记忆读写、知识图谱操作、智能体协调等。
- **知识图谱**：内置时间感知的实体关系图，支持添加、查询、失效和 timeline 操作。
- **智能体支持**：为每个智能体提供独立的 wing 和 diary，支持运行时发现。
- **自动保存钩子**：为 Claude Code、Codex CLI 和 Cursor IDE 提供自动保存钩子，防止会话丢失。
- **多智能体协调**：通过 logstream 事件层实现任务委派、补丁交换和实时通知。
- **CLI 工具**：提供 `mine`、`search`、`wake-up` 等命令，方便内容挖掘和检索。

## 适用与不适用场景

**适用场景：**
- 需要为 AI 智能体（如 Claude Code、Codex）提供长期记忆和上下文恢复。
- 希望本地存储敏感对话数据，避免云端依赖。
- 需要跨会话、跨项目的知识检索和关联。
- 构建多智能体协作系统，需要任务委派和状态同步。

**不适用场景：**
- 需要实时、强一致性的数据同步（MemPalace 采用最终一致性）。
- 需要处理大规模二进制文件或多媒体内容（主要面向文本）。
- 需要跨用户共享记忆（当前主要面向单用户多设备）。

## 技术架构与依赖

- **语言**：Python 3.9+
- **默认向量存储**：ChromaDB（嵌入式）
- **可选后端**：sqlite_exact、Milvus、Qdrant、pgvector
- **嵌入模型**：默认 `all-MiniLM-L6-v2`（英文），可选 `embeddinggemma-300m`（多语言）
- **主要依赖**：chromadb、numpy、grpcio、huggingface_hub、tokenizers 等
- **可选依赖**：`mempalace[extract]` 用于办公文档提取，`mempalace[milvus]`、`mempalace[pgvector]` 用于相应后端
- **许可证**：MIT

## 安装与快速开始

### 安装

推荐使用 `uv` 或 `pipx` 在隔离环境中安装：

```bash
uv tool install mempalace
```

或使用 pip 在虚拟环境中安装：

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

### 快速开始

```bash
# 初始化宫殿
mempalace init ~/projects/myapp

# 挖掘内容
mempalace mine ~/projects/myapp
mempalace mine ~/.claude/projects/ --mode convos

# 搜索
mempalace search "why did we switch to GraphQL"

# 加载上下文
mempalace wake-up
```

## 典型使用方法

### 挖掘项目文件

```bash
mempalace mine /path/to/project
```

### 挖掘对话记录

```bash
mempalace mine ~/.claude/projects/ --mode convos
```

### 使用 MCP 服务器

在 MCP 客户端（如 Claude Code）中配置 stdio 服务器，即可通过 MCP 工具进行记忆读写、知识图谱操作等。

### 使用 Docker

```bash
docker pull ghcr.io/mempalace/mempalace:latest
docker run -i --rm -v mempalace-data:/data ghcr.io/mempalace/mempalace
```

## 配置与部署要点

- **配置**：配置文件位于 `~/.mempalace/config.json`，可设置后端、嵌入模型、钩子等。
- **环境变量**：支持 `MEMPALACE_BACKEND`、`MEMPALACE_EMBEDDING_MODEL`、`MEMPALACE_PALACE_PATH` 等。
- **存储后端**：通过 `--backend` 或配置选择，远程后端（如 Qdrant、pgvector）需设置连接信息。
- **Docker 部署**：数据持久化在 `/data` 卷，注意挂载权限（uid 1000）。
- **远程/团队服务器**：`mempalace serve` 可启动 HTTP 服务器，支持 bearer token 认证和 TLS。
- **自动保存钩子**：为 Claude Code、Codex、Cursor 配置钩子，防止会话丢失。

## 限制、风险与许可证

- **限制**：
  - 默认嵌入模型仅支持英文，多语言需切换模型并重建索引。
  - 本地后端（如 ChromaDB）不支持多进程并发写入。
  - 部分功能（如办公文档提取）需要额外安装可选依赖。
- **风险**：
  - 存在仿冒网站，请仅使用官方 GitHub、PyPI 和文档站点。
  - 数据存储在本地，需注意备份和加密。
- **许可证**：MIT

## 官方链接

- GitHub 仓库：https://github.com/MemPalace/mempalace
- PyPI 包：https://pypi.org/project/mempalace/
- 文档站点：https://mempalaceofficial.com
- 发布版本：https://github.com/MemPalace/mempalace/releases

你的这两个问题问得很关键，正好触及了MemPalace这类AI记忆系统的技术核心与设计哲学。我帮你分别梳理一下：

### 1. 向量模型的使用

没错，MemPalace虽然主打“零API调用”，但它的确使用了向量模型来驱动语义搜索。它只是**不需要联网调用商业API**，而是使用本地运行的开源模型。

具体来说，它会下载并本地运行向量模型，主要有两个选项：

| 模型 | 特点 | 适用场景 |
| :--- | :--- | :--- |
| **minilm (默认)** | `all-MiniLM-L6-v2`，轻量（约80MB），但仅支持英语。 | 纯英文项目。 |
| **embeddinggemma** | 多语言支持（100+种语言），体积稍大（约300MB），首次使用时会从HuggingFace下载。 | 非英语项目，或需要处理多语言内容。 |

> 核心机制是：文本被转换为向量后存储在ChromaDB等后端中，搜索时通过计算向量相似度来查找相关内容。如果切换模型，需要重建索引，因为不同模型的向量空间不同。

此外，为了更彻底地实现“零LLM依赖”，它甚至尝试过用规则或符号索引(AAAK)取代向量模型来进行分类和检索，但这是实验性功能，性能有下降。

### 2. 与LLM Wiki及RAG框架的核心区别

你提到的这几个系统虽然都处理知识，但设计理念差异很大。除了隐私，核心区别在于**知识的生产与积累方式**。这里把MemPalace和LLM Wiki、传统RAG放在一起对比，会更清晰。

**核心区别：记忆（存储）与知识（理解）**

| 特性 | **MemPalace** | **LLM Wiki** | **传统RAG框架** |
| :--- | :--- | :--- | :--- |
| **核心理念** | **存储原始“证据”**：逐字保存对话和文件，坚信“好记性不如烂笔头”。 | **构建动态知识库**：将原始信息消化、整合，形成一篇篇有结构的、不断更新的Wiki文章。 | **按需检索上下文**：将文档切片、向量化，在收到问题时检索最相关的片段拼进提示词。 |
| **知识处理** | **写入时零LLM干预**：几乎不进行总结或提取，只是存储原文。 | **写入时深度理解**：LLM会阅读新资料，更新现有Wiki页面、标记矛盾、完善链接，知识持续累积。 | **写入时预处理**：进行文档解析、切片和向量化。部分系统会在检索后由LLM生成最终答案。 |
| **知识形态** | **原始档案库**：一个可以精确查找原文的档案馆。 | **活的知识网络**：一份由AI持续维护的、有层级和链接的Markdown文档集。 | **动态上下文片段**：一组按相关性拼接的文本块，用完即抛。 |
| **查询方式** | 语义搜索 + 结构化过滤（通过“翼”、“房间”等元数据）。 | 直接阅读和编辑知识库、浏览链接、提出总结性问题。 | 向量相似度检索，查找与问题语义最匹配的文本块。 |
| **记忆/知识特点** | **可追溯、原子化**：你能看到决定背后的完整讨论。 | **精炼、体系化**：得到的是某个主题的“最佳理解”和综述。 | **灵活、碎片化**：能应对开放域问题，但知识不积累，每次都是“重新发现”。 |

**总结来说：**

*   **MemPalace**像一个严谨的档案管理员，它**存储“事实发生了什么”**，把原始资料整理得井井有条（按项目、主题归档），让你或AI能随时回溯查找。它的强大在于**检索原始证据的能力**。
*   **LLM Wiki**则像一个学者，它**构建“我们对世界的理解”**，通过持续阅读和思考，将信息内化为一个不断增长、修正的知识体系。它的价值在于**知识本身的精炼和积累**。
*   **传统RAG框架**更像一个图书馆的索引员，它帮你快速找到可能包含答案的书页，但不会帮你做读书笔记或总结核心思想。

希望这个对比能帮你理清它们的定位。如果对某个具体的技术细节（比如AAAK压缩或MCP工具）感兴趣，我们可以再深入聊聊。

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、CHANGELOG、文档及 RFC 文件。
- 分析时间：2026-08-31（基于最新发布版本 v3.9.0）。