AI导哈

AI代理持久记忆工具

一个为AI代理提供持久记忆的服务，具有内置的新鲜度追踪和间隔重复功能，基于Elasticsearch后端。

  • by j3k0
  • TypeScript
  • 本地部署
  • 20 星标
  • 更新于
在 GitHub 查看 j3k0/mcp-brain-tools

使用说明

mcp脑工具

MCP服务器为AI代理提供持久内存，内置新鲜度跟踪和间隔重复。由Elasticsearch支持。

与简单的键值记忆存储不同，mcp大脑工具跟踪每条知识的年龄，标记需要审查的内容，并让代理验证信息以保持新鲜——灵感来自间隔重复如何帮助人类记忆知识。

特性

  • 间隔重复新鲜度 --每个实体的审查间隔在验证时加倍（上限为365天）。信任标签（新鲜/正常/老化/陈旧/存档）告诉代理要信任什么。
  • 渐进式搜索 --查询首先返回新的结果，仅在需要时自动扩展以包含旧数据。
  • 作为实体的观察 --每个观察都有自己的新鲜度生命周期，因此“构建被打破”（1天回顾）和“成立于2015年”（365天回顾）的年龄是独立的。
  • 内存区域 --按项目、团队或领域隔离知识。
  • AI驱动的过滤 --可选的Groq集成按相关性对搜索结果进行评分。
  • 按设计干燥 --工具描述指导代理不要存储代码、git或文档中已有的内容。

设置

先决条件

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

安装和构建

npm install
npm run build

启动Elasticsearch

npm run es:start

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

配置您的MCP客户端

添加到您的Claude代码、Claude桌面或其他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 是可选的——启用基于人工智能的搜索过滤和区域相关性评分。

安装自动记忆挂钩（仅限克劳德代码）

内存挂钩在每条用户消息上运行，并自动注入相关上下文——不需要代理协作。

添加 ~/.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变量（在 env 阻止您的设置，或将其导出到您的shell配置文件中）。

AI_API_BASE 默认为Groq的端点，但接受任何与OpenAI兼容的API URL。

运作原理

实体和意见

实体代表任何值得记住的东西——人、项目、决定、事实。每个实体都有：

  • A. 名字 和 类型
  • 间隔重复字段: verifiedAt, reviewInterval, nextReviewAt
  • A. 信任标签 根据新鲜度计算： 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)

新鲜度生命周期

  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 创建具有可选观察值和reviewInterval的实体
update_entities 更新现有实体
delete_entities 删除实体（可选级联）
add_observations 将观察结果添加为具有自身新鲜度的独立实体
verify_entity 确认实体仍然准确，延长审核间隔
search_nodes 使用渐进式新鲜度过滤进行搜索
open_nodes 使用新鲜度元数据按名称获取特定实体
get_recent 获取最近访问的实体
create_relations 在实体之间创建关系
delete_relations 删除关系
inspect_knowledge_graph 基于人工智能的实体检索，带有初步答案
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密钥
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

许可证

麻省理工学院

相关 MCP