MCP Neo4j Agent Memory

🚀 Neo4j Agent Memory MCP Server

Neo4j Agent Memory MCP Serverは、Neo4jグラフデータベースとAIエージェントを橋渡しする専用のMCPサーバーです。知識グラフ内で情報を保存、検索、関連付けるためのメモリー機能を提供します。

🚀 クイックスタート

このMCPサーバーは、npxを使用して直接実行できます。

npx @knowall-ai/mcp-neo4j-agent-memory

または、Claude Desktopの設定に追加することもできます。

{
  "mcpServers": {
    "neo4j-memory": {
      "command": "npx",
      "args": ["@knowall-ai/mcp-neo4j-agent-memory"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

✨ 主な機能

• 🧠 永続的なメモリー保存 - 会話をまたいでメモリーを保存および取得できます。
• 🔗 意味的な関係性 - メモリー間に意味のある関係（KNOWS、WORKS_AT、CREATEDなど）を作成します。
• 🔍 インテリジェントな検索 - すべてのメモリーのプロパティと関係を自然言語で検索できます。
• 🏷️ 柔軟なラベリング - メモリーに任意のラベル（person、place、project、ideaなど）を使用できます。
• ⏰ 時間的追跡 - 自動的なタイムスタンプと日付ベースのクエリが可能です。
• 🌐 グラフ探索 - 関係をたどって関連する情報を発見できます。
• 🎯 コンテキスト認識 - 深さを指定して関連するメモリーを含めた検索が可能です。
• 🔧 LLM最適化 - AIが複雑さを処理できるようなシンプルなツールが用意されています。
• 🏢 エンタープライズ対応 - 複数のNeo4jデータベースをサポートします。
• 📚 組み込みガイダンス - ベストプラクティスと使用パターンに関するヘルプが得られます。

哲学: LLM駆動のインテリジェンス

従来のアプローチではツールに複雑なロジックを埋め込んでいましたが、このサーバーはシンプルな原子操作を提供し、すべてのインテリジェンスをLLMに任せます。

• 隠れたロジックなし - ツールは宣言通りに動作し、自動的な曖昧性解消やスマートマッチングは行いません。
• LLMがすべてを決定 - エンティティ認識、関係推論、競合解決をLLMが行います。
• 透明な操作 - すべてのアクションは明示的で予測可能です。
• 最大限の柔軟性 - LLMはツールの制限なく任意の戦略を実装できます。

検索動作

search_memoriesツールは単語トークン化を使用します。

• クエリ「John Smith」は、「John」または「Smith」を含むメモリーを検索します。
• これにより、より多くの結果が返され、LLMが最も関連性の高いものを選択できます。
• 名前や複数単語のクエリに対して、正確な部分文字列マッチングよりも優れています。

このアプローチにより、システムはより強力で適応性が高くなり、LLMの能力向上が直接的にメモリー管理の改善につながります。

Neo4jエンタープライズ版のサポート

このサーバーは、Neo4jエンタープライズ版の特定のデータベースへの接続をサポートしています。デフォルトでは「neo4j」データベースに接続しますが、NEO4J_DATABASE環境変数を使用して別のデータベースを指定できます。

メモリーツール

• search_memories: 知識グラフからメモリーを検索および取得します。

  • 単語ベースの検索 - クエリ内の任意の単語を検索します（例: 「Ben Weeks」は「Ben」または「Weeks」を含むメモリーを検索します）。
  • すべてのメモリーのプロパティを自然言語で検索できます（空の場合はすべてのメモリーを取得します）。
  • メモリーのタイプ（person、place、projectなど）でフィルタリングできます。
  • since_dateパラメーター（ISO形式）で日付でフィルタリングできます。
  • 関係の深さと結果の制限を制御できます。
  • 任意のフィールド（created_at、nameなど）でソートできます。

• create_memory: 知識グラフに新しいメモリーを作成します。

  • 柔軟なタイプシステム - 任意のラベル（小文字）を使用できます（person、place、project、skillなど）。
  • 任意のプロパティをキーバリューペアとして保存できます。
  • 自動的なタイムスタンプで時間的追跡が可能です。

• create_connection: メモリー間に関係を作成します。

  • 意味的な関係タイプ（KNOWS、WORKS_AT、LIVES_INなど）を使用してメモリーをリンクします。
  • 関係にプロパティ（since、role、statusなど）を追加できます。
  • 複雑な知識ネットワークを構築できます。

• update_memory: 既存のメモリーのプロパティを更新します。

  • 任意のプロパティを追加または変更できます。
  • プロパティをnullに設定すると削除できます。

• update_connection: 関係のプロパティを更新します。

  • 関係のメタデータを変更できます。
  • 時間の経過に伴う変更を追跡できます。

• delete_memory: メモリーとそのすべての関係を削除します。

  • 注意して使用してください - 削除は永久的です。
  • すべての関係が自動的に削除されます。

• delete_connection: 特定の関係を削除します。

  • 正確な関係の削除が可能です。
  • メモリー自体は保持されます。

• list_memory_labels: 使用されているすべての一意のメモリーラベルをリストします。

  • すべてのラベルとそのカウントを表示します。
  • 一貫性を維持するのに役立ちます。
  • 重複するラベルのバリエーションを防止します。

• get_guidance: メモリーツールの効果的な使用方法に関するヘルプを取得します。

  • トピック: ラベル、関係、ベストプラクティス、使用例
  • LLM用の包括的なガイダンスを返します。
  • ラベル/関係の命名に不確かなときに使用します。

📦 インストール

Smitheryを介したインストール

Smitheryを介してClaude Desktop用のNeo4j Agent Memory MCP Serverを自動的にインストールするには、次のコマンドを実行します。

npx -y @smithery/cli install @knowall-ai/mcp-neo4j-agent-memory --client claude

開発用のインストール

1. リポジトリをクローンします。

git clone https://github.com/KnowAll-AI/mcp-neo4j-agent-memory.git
cd mcp-neo4j-agent-memory

2. 依存関係をインストールします。

npm install

3. プロジェクトをビルドします。

npm run build

設定

環境変数

サーバーは、次の環境変数が必要です。

• NEO4J_URI: Neo4jデータベースのURI（必須、例: bolt://localhost:7687）
• NEO4J_USERNAME: Neo4jのユーザー名（必須）
• NEO4J_PASSWORD: Neo4jのパスワード（必須）
• NEO4J_DATABASE: Neo4jのデータベース名（オプション） - 複数のデータベースを持つNeo4jエンタープライズ版用

環境変数の設定

開発用

.env.exampleを.envにコピーし、自分の資格情報を更新します。

cp .env.example .env
# .envを自分のNeo4j資格情報で編集します

Claude Desktop用

Claude Desktopの設定に環境変数を追加します（上記のクイックスタートを参照）。

💻 使用例

LLMは、何を保存するか、どのようにメモリーを関連付けるかの複雑さをすべて処理します。

基本的な使用法

情報の保存

User: "Remember that John works at Google as a software engineer"

Assistant: I'll remember that John works at Google as a software engineer.

[Behind the scenes, the LLM does:
1. search_memories({"query": "John"}) - Check if John exists
2. search_memories({"query": "Google"}) - Check if Google exists
3. create_memory({"label": "Person", "properties": {"name": "John", "occupation": "software engineer"}})
4. create_memory({"label": "Organization", "properties": {"name": "Google"}})
5. create_connection({"fromMemoryId": 123, "toMemoryId": 456, "type": "WORKS_AT"})]

User: "Remember that Sarah is John's manager and she started in 2019"

Assistant: I'll add that information about Sarah.

[The LLM searches for John, creates Sarah, and connects them with a MANAGES relationship including the start date]

情報の取得

User: "Who works at Google?"

Assistant: Let me search for people who work at Google.

[LLM uses: search_memories({"query": "Google", "depth": 2})]

Based on my memory:
- John - Software Engineer at Google
- Sarah - Manager at Google (manages John, started 2019)

User: "What do you remember about John?"

Assistant: Here's what I know about John:

[LLM uses: search_memories({"query": "John", "depth": 2})]

- Works at Google as a Software Engineer
- Sarah is his manager
- [Any other connected memories found in the search]

関係の構築

User: "John and Sarah are working on Project Atlas together"

Assistant: I'll connect John and Sarah to Project Atlas.

[The LLM:
1. Searches for John and Sarah to get their IDs
2. Creates Project Atlas: create_memory({"label": "Project", "properties": {"name": "Project Atlas"}})
3. Connects them: create_connection({"fromMemoryId": johnId, "toMemoryId": projectId, "type": "WORKS_ON"})
4. create_connection({"fromMemoryId": sarahId, "toMemoryId": projectId, "type": "WORKS_ON"})]

高度な使用法

特定のデータベースへの接続

複数のデータベースを持つNeo4jエンタープライズ版のユーザーは、接続するデータベースを指定できます。

{
  "env": {
    "NEO4J_URI": "bolt://localhost:7687",
    "NEO4J_USERNAME": "neo4j",
    "NEO4J_PASSWORD": "your-password",
    "NEO4J_DATABASE": "myCustomDatabase"
  }
}

これにより、デフォルトの「neo4j」データベースではなく、「myCustomDatabase」に接続されます。

より複雑な例

関連情報の検索

User: "Show me all employees in the Sales department"

Assistant: Let me search for employees in the Sales department.

[LLM uses: search_memories({"query": "Sales department", "depth": 2})]

I found these employees in the Sales department:
- John Smith (Sales Manager)
- Sarah Johnson (Sales Representative)  
- Mike Brown (Account Executive)

ドメイン固有のメモリーの作成

User: "Create a product called 'Premium Coffee' with price $24.99"

Assistant: I'll create that product for you.

[LLM uses: create_memory({"label": "Product", "properties": {"name": "Premium Coffee", "price": 24.99}})]

Created Premium Coffee product with ID: 456

関係の管理

User: "The Premium Coffee uses beans from our Colombian Supplier"

Assistant: I'll connect Premium Coffee to the Colombian Supplier.

[LLM:
1. search_memories({"query": "Premium Coffee"})
2. search_memories({"query": "Colombian Supplier"})
3. create_connection({"fromMemoryId": 456, "toMemoryId": 789, "type": "SUPPLIED_BY"})]

Connected Premium Coffee to Colombian Supplier

高度なクエリ

LLMは、検索ツールを賢く使用することで複雑なクエリを処理できます。

単語ベースの検索

User: "Find Ben Weeks"

Assistant: I'll search for memories containing "Ben" or "Weeks".

[LLM uses: search_memories({"query": "Ben Weeks"})]

I found several people matching your search:
- Ben Weeks - Software Engineer at TechCorp (exact match)
- Sarah Ben - Data Scientist at DataCo (contains "Ben")
- John Weeks - Project Manager (contains "Weeks")

The most likely match appears to be Ben Weeks, the Software Engineer.

最近のメモリー（過去7日間）

User: "What new people have I met in the last week?"

Assistant: I'll search for people added to your memory in the last 7 days.

[LLM calculates the date 7 days ago and uses: 
search_memories({
  "query": "", 
  "label": "person", 
  "since_date": "2024-01-20T00:00:00Z",
  "order_by": "created_at DESC"
})]

Here are the new people you've met in the last week:
- Sarah Chen - Met at tech conference on Monday
- Dr. Michael Roberts - New physician, first appointment Tuesday  
- Emma Wilson - Joined your project team on Wednesday
- James Park - Coffee meeting about potential collaboration Thursday

曖昧性解消

User: "What does John do?"

Assistant: I found multiple people named John. Let me show you what I know:

[LLM uses: search_memories({"query": "John", "type": "Person", "depth": 1})]

1. John Doe - Software Engineer at Google
2. John Smith - Sales Manager in Sales Department
3. John Brown - Project Manager on Project Atlas

Which John were you asking about?

時間的クエリ

User: "What events did I attend last month?"

Assistant: I'll search for event memories and check their dates.

[LLM uses: search_memories({"query": "", "label": "event", "sort_by": "created_at", "sort_order": "desc"})]

[Filters results to last month based on created_at or date properties]

Here are the events you attended last month:
- Tech Innovation Summit (March 5-6) - Keynote speaker
- Team Building Workshop (March 12) - With engineering team
- Client Dinner Meeting (March 18) - Project kickoff with ABC Corp
- WebDev Conference (March 25-27) - Attended 5 sessions on React

柔軟なメモリータイプ

システムは厳格なタイプを強制しません。意味のある任意のタイプのメモリーを作成できます。

一般的なタイプ（小文字）: person、place、organization、project、event、topic、object、animal、plant、food、activity、media、skill、document、meeting、task、habit、health、vehicle、tool、idea、goal

ただし、任意のタイプ（小文字）を使用できます: recipe、dream、memory、quote、book、movie、emotion、relationship、appointment、medication、exercise、symptom、payment、contractなど。

LLMは、適切な場合に既存のタイプを賢く再利用して一貫性を維持します。

関係の力

このメモリーシステムの真の価値は、個々のメモリーを保存するだけでなく、それらの間に関係を作成することにあります。知識グラフは、関係を構築するにつれて指数関数的に有用になります。

関係が重要な理由

• コンテキストの発見 - 関連付けられたメモリーは、孤立した事実では得られない豊富なコンテキストを提供します。
• 関係パターン - 関係分析を通じて隠れたパターンと洞察を明らかにします。
• 時間的理解 - 関係が時間の経過とともにどのように進化するかを追跡できます。
• ネットワーク効果 - 新しい関係が追加されるたびに、既存のメモリーの価値が増加します。

関係構築のベストプラクティス

1. 新しい情報を保存するときは、常に関係を探します。

   Bad: Just store "John is a developer"
   Good: Store John AND connect him to his company, projects, skills, and colleagues
   

2. 意味を捉える意味的な関係タイプを使用します。

   WORKS_AT, MANAGES, KNOWS, LIVES_IN, CREATED, USES, LEARNED_FROM
   

3. より豊富なコンテキストのために関係のプロパティを追加します。

   create_connection({
     "fromMemoryId": 123,
     "toMemoryId": 456, 
     "type": "WORKS_ON",
     "properties": {"role": "Lead", "since": "2023-01", "hours_per_week": 20}
   })
   

4. グラフを意識して考えます。情報を検索するときは、深さを1より大きく設定してネットワークを探索します。

   search_memories({"query": "John", "depth": 3})  // Explores connections up to 3 hops away
   

覚えておいてください: 関係がないメモリーは、カタログのない図書館の本のようなものです。存在はしますが、その有用性は限られています。メモリー間の関係を構築するほど、知識グラフはよりインテリジェントで有用になります。

テスト

テストスイートを実行します。

npm test

MCPインスペクターを使用した対話型テスト

対話型テストとデバッグには、MCPインスペクターを使用します。

# Quick start with environment variables from .env
./run-inspector.sh

# Or manually with specific environment variables
NEO4J_URI=bolt://localhost:7687 \
NEO4J_USERNAME=neo4j \
NEO4J_PASSWORD=your-password \
npx @modelcontextprotocol/inspector build/index.js

インスペクターは、次のことができるウェブUIを提供します。

• すべての利用可能なツールを対話的にテストする。
• リアルタイムのリクエスト/レスポンスデータを表示する。
• Neo4jの接続を検証する。
• ツールのパラメーターとレスポンスをデバッグする。

📄 ライセンス

MIT