内容
# recall-mcp
> **为你使用的每个 AI CLI 提供一个共享、分层、本地优先的记忆库。**
> Claude Code、Gemini CLI、Cursor、Continue、Zed — 它们都会忘记。recall-mcp 是它们共享的记忆库。
[](LICENSE)
[](https://www.python.org)
[](https://modelcontextprotocol.io)
[](#storage-location)
<p align="center">
<img src="docs/demo.gif" alt="Gemini CLI 调用 recall-mcp 的 memory_recall 工具来回答 '今天我们发布了什么，为什么不叫 brain-mcp？' — 从分层记忆库中检索重命名决策和发布的架构" width="820">
<br>
<em>Gemini CLI 从它与 Claude Code 和 Hermes 共享的记忆库中回忆今天的决策。</em>
</p>
> 构建在 [Hermes Agent](https://github.com/NousResearch/hermes-agent) 的分层记忆引擎之上，由 Nous Research (MIT) 开发。recall-mcp 将该引擎打包成一个独立的 MCP 服务器，以便任何 AI 客户端 — 而不仅仅是 Hermes — 都可以连接到同一个记忆库。原始架构：他们。打包、MCP 接口、跨 CLI 集成：本项目。参见 [Credits](#credits)。
## 快速开始
```bash
# 安装
pipx install recall-mcp
# 配置到 Claude Code（一次性）
echo '{"mcpServers":{"recall-mcp":{"type":"stdio","command":"recall-mcp"}}}' >> ~/.claude.json
# 重启 Claude Code。完成。
```
就这样。每次对话现在都写入并读取相同的持久记忆库 — Gemini CLI、Cursor 和任何其他通过相同方式连接的 MCP 感知客户端也是如此。
## 功能
```mermaid
flowchart TD
A[Claude Code] -- MCP --> M[recall-mcp]
B[Gemini CLI] -- MCP --> M
C[Cursor / Continue / Zed] -- MCP --> M
M --> S[(SQLite<br/>事实)]
M --> V[(ChromaDB<br/>向量)]
M --> E[(实体<br/>图)]
M --> T[(时间<br/>血统)]
M --> F[(FTS5<br/>关键词)]
classDef client fill:#1f6feb,stroke:#1f6feb,color:#fff,stroke-width:0
classDef brain fill:#a371f7,stroke:#a371f7,color:#fff,stroke-width:0
classDef store fill:#0d1117,stroke:#30363d,color:#7d8590
class A,B,C client
class M brain
class S,V,E,T,F store
```
每个 AI CLI 都有相同的盲点：每个新会话都以失忆开始。本地 `save_memory` 工具会存储扁平列表，随着时间的推移会使系统膨胀。云记忆服务需要帐户、付费层级和对供应商的信任。
**recall-mcp 为你提供一个所有 MCP 感知 AI 客户端共享的记忆库：**
- 🧠 **7 个记忆层** — 向量相似性、BM25 关键词、实体图、时间血统、重要性评分、遗忘引擎、混合检索
- 🔌 **通过 MCP 插件** — 与 Claude Code、Gemini CLI、Cursor、Continue、Zed 兼容，任何支持 Model Context Protocol 的客户端
- 🏠 **本地优先** — SQLite + ChromaDB 在你的机器上。无需帐户，无需 Docker，无需云锁定
- 🔄 **记忆库可切换** — 在 Claude、Gemini、MiniMax、Qwen 之间切换 — 它们都共享同一个记忆库
- 🛡️ **优雅降级** — 当嵌入达到速率限制时，BM25 + 实体 + 时间血统承担负载。永远不会污染索引
## 安装
```bash
pipx install recall-mcp
```
或使用 [`uv`](https://github.com/astral-sh/uv)：
```bash
uv tool install recall-mcp
```
或从源代码安装：
```bash
git clone https://github.com/Dhari-Q/recall-mcp
cd recall-mcp
pip install -e .
```
## 配置你的 AI 客户端
### Claude Code
在项目下的 `~/.claude.json` 中添加：
```json
{
"mcpServers": {
"recall-mcp": {
"type": "stdio",
"command": "recall-mcp"
}
}
}
```
### Gemini CLI
在 `~/.gemini/settings.json` 中添加：
```json
{
"mcpServers": {
"recall-mcp": {
"command": "recall-mcp",
"trust": true
}
}
}
```
### Cursor
在 `~/.cursor/mcp.json` 中添加：
```json
{
"mcpServers": {
"recall-mcp": {
"command": "recall-mcp"
}
}
}
```
重启你的客户端。完成。
## 你将使用的五个工具
| 工具 | 目的 |
|---|---|
| `memory_recall(query, top_k)` | 跨所有层的混合搜索 — 向量 + BM25 + 实体 + 时间 |
| `memory_remember(content, type, confidence, tags)` | 存储事实、决策、偏好或注意事项 |
| `memory_recent_sessions(limit)` | 列出最近的会话摘要，包括决策和错误修复 |
| `memory_search_entity(name, limit)` | 查找与特定文件、项目、人员或工具相关的记忆 |
| `memory_stats()` | 健全性检查每个层的计数 |
## 可选：真正的语义搜索
默认情况下，recall-mcp 配备了 BM25 关键词 + 实体图 + 时间检索 — 这些无需任何 API 密钥即可工作。
要启用 **向量 / 语义搜索** （查询如 “如何交换 AI” 查找 “可通过 /model 交换” 而无需共享关键词），请将 recall-mcp 指向嵌入提供商：
创建 `~/.recall-mcp/.env` （或在你的 shell 中导出）：
```bash
# MiniMax（全局）— 最快路径
MINIMAX_API_KEY=sk-...
# 或 OpenAI
OPENAI_API_KEY=sk-...
# 或 OpenRouter
OPENROUTER_API_KEY=sk-...
```
向量层在下次启动时自动激活。
## 可选：Claude Code 的自动预取钩子
上述 MCP 工具是 **刻意的** — 模型必须 *调用* 它们。对于 *静默自动回忆* （在每个提示上，如 Claude Code 的本地记忆但分层），请添加一个 `UserPromptSubmit` 钩子。参见 [`examples/claude_code_hook.md`](examples/claude_code_hook.md) 获取配方。
## 记忆类型
当你要求模型记住某些东西时，它会选择以下之一：
| 类型 | 衰减 | 示例 |
|---|---|---|
| `architecture` | 永久 | “我们使用 ChromaDB 进行向量存储” |
| `decision` | 永久 | “我们选择了 MIT 而不是 GPL” |
| `convention` | 永久 | “所有 API 调用都通过 retry_utils 进行” |
| `pattern` | 永久 | “对 sqlite 连接使用 `with` 语句” |
| `gotcha` | 永久 | “MiniMax 嵌入与 OpenAI 不兼容” |
| `preference` | 永久 | “用户更喜欢简洁的回应” |
| `progress` | 7 天 | “于 2026-04-28 完成 MCP 连接” |
| `context` | 30 天 | 杂项背景事实 |
## 存储位置
所有数据都存储在 `$RECALL_MCP_HOME` （默认为 `~/.recall-mcp/`）：
```
~/.recall-mcp/
├── memory/ # SQLite — 事实 + 实体图 + 时间血统
├── episodic/ # SQLite — 会话摘要
└── chroma/ # ChromaDB — 向量嵌入
```
设置 `RECALL_MCP_HOME` 以将多个机器指向一个同步的文件夹（例如 Syncthing），你的 AI 的记忆就会随你而去。
## 架构
recall-mcp 暴露了七个记忆层（最初在 [Hermes Agent](https://github.com/NousResearch/hermes-agent) 中设计），每个层都由一个专注的存储引擎支持：
1. **情景** （每回合 / 每会话事件）— SQLite
2. **语义** （提取的事实，决策）— SQLite + ChromaDB
3. **实体图** （谁 / 什么 / 为什么，依赖关系）— SQLite
4. **时间血统** （毫秒时间戳，之前 / 之后查询）— SQLite
5. **重要性评分** （并非所有记忆都相等）— 派生
6. **遗忘引擎** （衰减 + Jaccard 去除重复）— 派生
7. **混合检索** （BM25 + 向量 + 实体 + 时间，带有可选的 LLM 重新排序）— 运行时
当你调用 `memory_recall` 时，所有四个检索路径并行运行，结果进行去重，按源质量 + 重要性评分，并返回排名。
## 鸣谢
记忆架构源自 **[Hermes](https://github.com/NousResearch/hermes-agent)**，由 Nous Research (MIT) 开发。recall-mcp 将分层记忆 + 检索引擎泛化为一个独立的 MCP 服务器，任何 AI 客户端都可以连接到它。
## 许可证
MIT — 参见 [`LICENSE`](LICENSE)。
