mcp-brain-tools

AIエージェントに、組み込みの鮮度追跡と分散学習（spaced repetition）を備えた永続的なメモリを提供するMCPサーバーです。Elasticsearchをバックエンドとして使用します。

単純なキーバリューストアとは異なり、mcp-brain-toolsは各知識がどれくらい古いかを追跡し、レビューが必要なものにフラグを立て、エージェントが情報を検証して鮮度を保てるようにします。これは、人間が知識を定着させるために分散学習を活用する仕組みから着想を得ています。

特徴

分散学習による鮮度管理 — 各エンティティにはレビュー間隔があり、検証するたびに倍増します（最大365日）。信頼度ラベル（fresh/normal/aging/stale/archival）により、エージェントは何を信頼すべきかを判断できます。
プログレッシブ検索 — クエリはまず鮮度の高い結果を返し、必要な場合にのみ自動的に古いデータを含めるように範囲を広げます。
エンティティとしての観測 — 各観測には独自の鮮度ライフサイクルがあるため、「ビルドが壊れている」（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ブロックで設定するか、シェルプロファイルでエクスポートしてください）。

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経由) — 間隔が倍になり、信頼度がfreshにリセットされる
長期未レビュー — confidence: "stale"、その後"archival"となり、デフォルト検索から除外される

プログレッシブ検索

検索時、サーバーは3段階のパスを使用します：

freshness >= 0 — freshおよびnormalなエンティティ
freshness >= -2 — agingおよびstaleを追加
フィルタなし — archivalを追加

これにより、結果をクリーンに保ちつつ、情報が永久に失われないようにします。

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`	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