mcp-brain-tools

一个为 AI 智能体提供持久化记忆的 MCP 服务器，内置新鲜度跟踪和间隔重复功能。由 Elasticsearch 提供支持。

与简单的键值对记忆存储不同，mcp-brain-tools 会跟踪每条知识的陈旧程度，标记需要复习的内容，并允许智能体验证信息以保持其新鲜度——灵感来源于间隔重复如何帮助人类保持记忆。

功能特性

间隔重复新鲜度 — 每个实体都有一个复习间隔，验证后该间隔会翻倍（上限为 365 天）。置信度标签（新鲜/正常/老化/陈旧/归档）告诉智能体哪些信息值得信任。
渐进式搜索 — 查询优先返回新鲜结果，仅在需要时自动扩大范围以包含旧数据。
作为实体的观察结果 — 每个观察结果都有其独立的新鲜度生命周期，因此“构建失败”（1 天复习）和“成立于 2015 年”（365 天复习）会独立老化。
记忆区域 — 按项目、团队或领域隔离知识。
AI 驱动的过滤 — 可选的 Groq 集成，根据相关性对搜索结果进行评分。
DRY 设计原则 — 工具描述引导智能体不要存储代码、git 或文档中已有的内容。

Related MCP server: Logseq MCP Tools

设置

前置要求

Node.js >= 18
Docker（用于 Elasticsearch）或远程 Elasticsearch 实例

安装与构建

npm install
npm run build

启动 Elasticsearch

npm run es:start

或者通过 ES_NODE 环境变量指向您自己的实例。

配置您的 MCP 客户端

添加到您的 Claude Code、Claude Desktop 或其他 MCP 客户端配置中：

{
  "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：

{
  "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 关系链接的独立实体存储。每个观察结果都有自己的复习节奏：

Entity: "iaptic-server" (type: Project, reviewInterval: 30 days)
  <- "iaptic-server: uses TypeScript" (reviewInterval: 180 days)
  <- "iaptic-server: migration in progress" (reviewInterval: 7 days)

新鲜度生命周期

创建实体 — confidence: "fresh"，默认 7 天后复习
复习日期已过 — confidence: "aging"，needsReview: true
智能体验证（通过 verify_entity） — 间隔翻倍，置信度重置为新鲜
严重逾期 — confidence: "stale" 然后变为 "archival"，从默认搜索中排除

渐进式搜索

搜索时，服务器使用三轮筛选：

freshness >= 0 — 新鲜和正常的实体
freshness >= -2 — 增加老化和陈旧的实体
无过滤器 — 增加归档实体

这既保持了结果的整洁，又确保了信息不会永久丢失。

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`	—	用于 AI 过滤的 Groq API 密钥
`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（或等效指令文件）中添加类似以下内容：

## Memory

Use MCP Memory (`mcp__memory__*` tools) — a shared knowledge graph across all agents, projects, and computers.

**When to SAVE (immediately, before moving on):**
- Something you tried didn't work (non-transient) → save what failed and why, so no agent repeats it
- A decision was made (architectural, design, workflow) → save the decision and the reason
- The user corrects you or gives explicit instructions → save the rule
- You learn something non-obvious that took effort to discover → save it

**When to SEARCH (before starting, not after failing):**
- **At the start of every non-trivial task** — search before thinking, not after hitting a wall
- About to try an approach that might have been attempted before → search first
- User references something from a past session → search before asking

**Rules:**
- Skip anything easy to find in code, git log, or docs
- Use the project name as the zone for project-specific knowledge; `default` for general knowledge
- Keep entries short — the AI filters server-side, so be generous rather than selective
- Short `reviewInterval` (e.g. 3–7 days) for volatile facts; longer (30–180) for stable ones

关键见解：智能体需要明确的基于触发器的指令（“当 X 时，做 Y”），而不仅仅是工具功能的描述。

开发

npm run build          # Compile TypeScript
npm run dev            # Watch mode
npm run test:jest      # Run Jest tests
npm run es:start       # Start Elasticsearch
npm run es:stop        # Stop Elasticsearch
npm run es:reset       # Wipe data and restart
npm run import         # Import from JSON
npm run export         # Export to JSON

许可证

MIT

Elasticsearch Knowledge Graph for MCP