MCP Neuralmemory

🚀 🧠 MCP-KG-Memory

AIコーディングエージェント用の長期記憶レイヤーです。コンテキストを持続させ、過去の失敗から学習し、プロジェクトの目標を理解するAIアシスタントを実現します。

🚀 クイックスタート

MCP-KG-Memoryは、AIコーディングアシスタント（Cursor、Windsurf、VS Code、Antigravityなど）における「コンテキスト健忘症」の問題を解決するために設計された本番グレードのモデルコンテキストプロトコル（MCP）サーバーです。

インストール

kg-mcp は pipx（推奨）を使用してグローバルにインストールするか、ローカルの仮想環境にインストールできます。

前提条件

• Python 3.11+
• Docker（Neo4jをローカルで実行するため）
• Gemini APIキー（Google AI Studioからキーを取得）

オプション1: ワンラインインストール（推奨）

# パッケージをインストール
pipx install kg-mcp

# インタラクティブなセットアップウィザードを実行
kg-mcp-setup

ウィザードは以下のことを行います。

1. DockerとNeo4jの存在を確認します。
2. Gemini APIキーを要求します。
3. LLMモード（Direct vs LiteLLM）を構成します。
4. 安全な .env ファイルを生成します。

brew install pipx
pipx ensurepath

winget install pipx
pipx ensurepath

sudo apt install pipx
pipx ensurepath

代替手段: 標準のPip

pipxを使用しない場合は、以下のコマンドを実行します。

pip install kg-mcp
kg-mcp-setup

オプション2: 手動開発セットアップ

# リポジトリをクローン
git clone https://github.com/Hexecu/mcp-neuralmemory.git
cd mcp-neuralmemory

# 環境を設定
cp .env.example .env
# (.envをあなたの資格情報で編集)

# 依存関係をインストール
cd server
pip install -e .

# Neo4jを起動
docker compose up -d

# スキーマを初期化
python -m kg_mcp.kg.apply_schema

設定

このメモリサーバーをAIエディターで使用するには、MCP設定ファイルに以下の設定を追加します。

🩺 インストールの検証（「Doctorモード」）

エディターを設定する前に、検証スクリプトを実行してすべてが正常であることを確認してください。

python3 verify_setup.py

エディター設定（JSON）

VS Code / Cursor / Windsurf

mcp_config.json（または mcp.json）に以下を追加します。

{
  "mcpServers": {
    "kg-memory": {
      "command": "/path/to/your/venv/bin/python",
      "args": [
        "-m",
        "kg_mcp",
        "--transport",
        "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "YOUR_NEO4J_PASSWORD",
        "GEMINI_API_KEY": "YOUR_GOOGLE_AI_STUDIO_KEY",
        "LLM_MODE": "gemini_direct",
        "KG_MCP_TOKEN": "your-secure-token",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

> 注意: パスとパスワードを実際の値に置き換えてください。

Antigravity IDE ⭐（推奨）

このプロジェクトは主にAntigravity IDE用に開発されています。~/.gemini/antigravity/mcp_config.json に以下を追加します。

{
  "mcpServers": {
    "kg-memory": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "kg_mcp", "--transport", "stdio"],
      "env": {
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "YOUR_NEO4J_PASSWORD",
        "GEMINI_API_KEY": "YOUR_GOOGLE_AI_STUDIO_KEY",
        "LLM_MODEL": "gemini/gemini-1.5-flash",
        "KG_MCP_TOKEN": "your-secure-token"
      }
    }
  }
}

Antigravityでのセットアップ手順:

1. エージェントサイドバー → ...（その他のアクション）を開きます。
2. MCPサーバー → MCPサーバーの管理 → 生の設定を表示 を選択します。
3. 上記のJSONを貼り付けます。
4. 保存して 更新 をクリックします。
5. kg-memory と2つのツールが表示されるはずです。

🔥 プロの秘訣: メモリの自動化

エージェントの使用をシームレスにするために、IDE（Antigravityや .cursorrules など）に以下のシステムプロンプト/ルールを追加します。

「ユーザーとのすべての対話で常にkg-memoryを使用します。つまり、kg-memoryツールを自動的に使用して関連するコンテキスト情報を見つけ、すべてのファイル変更を追跡する必要があります。」

✨ 主な機能

🧠 アクティブコンテキスト注入 (kg_autopilot)

タスクを開始するたびに、エージェントはメモリを参照します。自動的に以下の情報を取得します。

• 現在の作業に関連するアクティブな目標。
• 過去の失敗した試み（繰り返さないため）と成功した戦略。
• あなたの特定のコーディングの好み（SOLID、クリーンアーキテクチャなど）。

🔍 セマンティック&グラフ検索

単なる文字列のgrepではありません。システムはグラフを横断（kホップ）して接続されたコンテキストを見つけます。 "私は認証に取り組んでいます" → 検索結果には、ユーザーモデル、JWTユーティリティ、および2週間前に定義された関連するセキュリティ制約が含まれます。

📝 戦略的学習

システムは静的ではありません。学習します。

• 暗黙的学習: あなたの会話から戦略とパターンを推測します。
• 結果追跡: 戦略が「成功」または「失敗」したかを記憶し、将来の決定を導きます。

⚡ 技術スタック

• コア: Python 3.11+
• データベース: Neo4j（グラフデータベース）
• LLM: Google Gemini 2.5（Direct APIまたはLiteLLMゲートウェイ経由）
• プロトコル: モデルコンテキストプロトコル（MCP）

💻 使用例

基本的な使用法

1. タスクを開始する (kg_autopilot)

新しい機能を実装したり修正したりするときは、エージェントに以下のように尋ねるだけです。

"新しいログインフローを実装したい。メモリからコンテキストを確認してください。" エージェントは kg_autopilot を呼び出し、すべての関連する制約、過去の決定、およびアクティブな目標を取得します。

2. 変更を追跡する (kg_track_changes)

(エージェントが構成されている場合は自動) ファイルが変更されると、システムはコードの変更をアクティブな目標にリンクし、実装の詳細で知識グラフを更新します。

📚 ドキュメント

📖 概要

MCP-KG-Memoryは、AIコーディングアシスタント（Cursor、Windsurf、VS Code、Antigravityなど）における「コンテキスト健忘症」の問題を解決するために設計された本番グレードのモデルコンテキストプロトコル（MCP）サーバーです。

各セッションをゼロから始めるのではなく、このシステムはプロジェクトの永続的な知識グラフを維持します。これは、以下を追跡するアクティブなメモリレイヤーとして機能します。

• 🎯 目標とステータス: 何を構築しているのか？何が完了したのか？
• 🛑 制約とルール: アーキテクチャ上の決定、禁止されたパターン。
• 💡 戦略と結果: 何がうまくいったのか？何が失敗したのか？（自動学習）
• ❤️ ユーザーの好み: あなたはコードをどのように書くのが好きか？
• 🔗 コードの関係: 目標と特定のファイル間の意味的なリンク。

📸 可視化

知識グラフのメモリ構造のリアルタイム可視化です。

📄 ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細については LICENSE ファイルを参照してください。