内容
# mcp-brain-tools
MCP 服务器，为 AI 代理提供持久记忆，内置新鲜度跟踪和间隔重复。由 Elasticsearch 支持。
与简单的键值记忆存储不同，mcp-brain-tools 跟踪每个知识片段的年龄，标记需要审查的内容，并允许代理验证信息以保持其新鲜度 — 灵感来自间隔重复如何帮助人类保持知识。
## 功能
- **间隔重复新鲜度** — 每个实体都有一个审查间隔，在验证时翻倍（上限为 365 天）。置信度标签（新鲜/正常/老化/过时/存档）告诉代理哪些信息值得信赖。
- **渐进搜索** — 查询返回最新的结果，然后自动扩展以包括较旧的数据，仅在需要时。
- **观察作为实体** — 每个观察都有自己的新鲜度生命周期，因此“构建已损坏”（1 天审查）和“成立于 2015 年”（365 天审查）独立老化。
- **记忆区** — 按项目、团队或领域隔离知识。
- **AI 驱动的过滤** — 可选的 Groq 集成根据相关性为搜索结果评分。
- **DRY 设计** — 工具描述指导代理不要存储已经存在于代码、git 或文档中的信息。
## 安装
### 先决条件
- Node.js >= 18
- Docker（用于 Elasticsearch）或远程 Elasticsearch 实例
### 安装和构建
```bash
npm install
npm run build
```
### 启动 Elasticsearch
```bash
npm run es:start
```
或通过 `ES_NODE` 环境变量指向您自己的实例。
### 配置您的 MCP 客户端
在您的 Claude Code、Claude Desktop 或其他 MCP 客户端配置中添加：
```json
{
"mcpServers": {
"memory": {
"command": "node",
"args": ["/path/to/mcp-brain-tools/dist/index.js"],
"env": {
"ES_NODE": "http://localhost:9200",
"GROQ_API_KEY": "your-key-here"
}
}
}
}
```
`GROQ_API_KEY` 是可选的 — 启用 AI 驱动的搜索过滤和区域相关性评分。
### 安装自动记忆钩子（仅限 Claude Code）
记忆钩子在每个用户消息上运行，并自动注入相关上下文 — 无需代理协作。
在 `~/.claude/settings.json` 中添加：
```json
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "node /path/to/mcp-brain-tools/dist/memory-hook.js"
}
]
}
]
}
}
```
钩子使用相同的 `ES_NODE`、`AI_API_KEY`/`GROQ_API_KEY`、`AI_API_BASE` 和 `AI_MODEL` 环境变量（在设置的 `env` 块中设置，或在 shell 配置文件中导出）。
`AI_API_BASE` 默认使用 Groq 的端点，但接受任何 OpenAI 兼容的 API URL。
## 工作原理
### 实体和观察
实体代表任何值得记忆的事物 — 人、项目、决定、事实。每个实体都有：
- **名称** 和 **类型**
- **间隔重复字段**：`verifiedAt`、`reviewInterval`、`nextReviewAt`
- 根据新鲜度计算的 **置信度标签**：`1 - (daysSinceVerified / reviewInterval)`
观察作为单独的实体存储，通过 `is_observation_of` 关系链接。每个观察都有自己的审查节奏：
```
实体：“iaptic-server”（类型：项目，审查间隔：30 天）
<- “iaptic-server: 使用 TypeScript”（审查间隔：180 天）
<- “iaptic-server: 迁移中”（审查间隔：7 天）
```
### 新鲜度生命周期
1. **实体创建** — `confidence: "fresh"`，默认 7 天后审查
2. **审查日期通过** — `confidence: "aging"`，`needsReview: true`
3. **代理验证**（通过 `verify_entity`）— 间隔翻倍，置信度重置为新鲜
4. **长期逾期** — `confidence: "stale"` 然后 `"archival"`，从默认搜索中排除
### 渐进搜索
搜索时，服务器使用三个步骤：
1. `freshness >= 0` — 新鲜和正常的实体
2. `freshness >= -2` — 添加老化和过时的实体
3. 无过滤器 — 添加存档实体
这样可以在确保不会永久丢失任何信息的同时保持结果的清洁。
## MCP 工具
| 工具 | 描述 |
|------|-------------|
| `create_entities` | 创建带有可选观察和审查间隔的实体 |
| `update_entities` | 更新现有实体 |
| `delete_entities` | 删除实体（可选级联删除） |
| `add_observations` | 添加观察作为具有自己新鲜度的单独实体 |
| `verify_entity` | 确认实体仍然准确，延长审查间隔 |
| `search_nodes` | 搜索具有渐进新鲜度过滤 |
| `open_nodes` | 通过名称获取具有新鲜度元数据的特定实体 |
| `get_recent` | 获取最近访问的实体 |
| `create_relations` | 创建实体之间的关系 |
| `delete_relations` | 删除关系 |
| `inspect_knowledge_graph` | 具有试探性答案的 AI 驱动实体检索 |
| `inspect_files` | AI 驱动的文件内容检查 |
| `list_zones` | 列出记忆区（带有 AI 相关性评分） |
| `create_zone` / `delete_zone` | 管理记忆区 |
| `copy_entities` / `move_entities` | 在区域之间传输实体 |
| `merge_zones` | 合并区域并解决冲突 |
| `zone_stats` | 获取区域的实体/关系计数 |
| `mark_important` | 提升实体相关性评分 |
| `get_time_utc` | 获取当前 UTC 时间 |
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `ES_NODE` | `http://localhost:9200` | Elasticsearch URL |
| `ES_USERNAME` | — | Elasticsearch 用户名 |
| `ES_PASSWORD` | — | Elasticsearch 密码 |
| `GROQ_API_KEY` | — | Groq API 密钥，用于 AI 过滤 |
| `GROQ_MODELS` | `openai/gpt-oss-120b,llama-3.3-70b-versatile` | 以逗号分隔的模型列表 |
| `KG_INDEX_PREFIX` | `knowledge-graph` | Elasticsearch 索引前缀 |
| `KG_DEFAULT_ZONE` | `default` | 默认记忆区 |
| `DEBUG` | `false` | 启用调试日志 |
## 推荐的代理指令
要在代理中主动使用记忆服务器，请在您的 `CLAUDE.md`（或等效的指令文件）中添加类似以下内容：
```markdown
## 记忆
使用 MCP 记忆（`mcp__memory__*` 工具）— 跨所有代理、项目和计算机的共享知识图。
**何时保存（立即，在继续之前）：**
- 尝试失败（非瞬时） → 保存失败的内容和原因，以免代理重复尝试
- 做出了决定（架构、设计、工作流） → 保存决定和原因
- 用户纠正您或给出明确的指示 → 保存规则
- 您学习到了不容易忘记的非显而易见的东西 → 保存它
**何时搜索（在开始之前，而不是失败后）：**
- **每个非琐碎任务的开始** — 在思考之前搜索，而不是在遇到障碍后
- 即将尝试可能已经有人尝试过的方法 → 先搜索
- 用户引用了过去会话中的某些内容 → 在询问之前搜索
**规则：**
- 跳过代码、git 日志或文档中容易找到的内容
- 使用项目名称作为项目特定知识的区域；`default` 用于一般知识
- 保持条目简短 — AI 服务器端过滤，因此请随意而不是选择性地
- 短 `reviewInterval`（例如 3-7 天）用于易变事实；较长（30-180）用于稳定事实
```
关键的洞察：代理需要基于触发器的明确指令（“当 X 时，做 Y”），而不只是工具功能的描述。
## 开发
```bash
npm run build # 编译 TypeScript
npm run dev # 监视模式
npm run test:jest # 运行 Jest 测试
npm run es:start # 启动 Elasticsearch
npm run es:stop # 停止 Elasticsearch
npm run es:reset # 清除数据并重启
npm run import # 从 JSON 导入
npm run export # 导出到 JSON
```
## 许可证
MIT
MCP 市场