MemoryMesh

MemoryMesh

MemoryMesh は、テキストベースの RPG とインタラクティブなストーリーテリングに重点を置いた、AI モデル向けのナレッジグラフサーバーです。会話をまたいで一貫性のある構造化された記憶を AI が維持できるようにし、より豊かで動的なやり取りを実現します。

このプロジェクトは、MCP servers リポジトリの Knowledge Graph Memory Server を基にしており、その中核機能を引き継いでいます。

重要

v0.3.0 の更新： MCP SDK が v1.0.4 から v1.25.2 に更新され、現行の Model Context Protocol 仕様（2025-11-25） に準拠しました。このメジャーアップデートにより、Claude Desktop、ChatGPT、Cursor、Gemini、VS Code など、最新の MCP クライアントとの互換性が実現します。更新後、npm install を実行して新しい依存関係を取得してください。

v0.2.7 以降、スキーマのデフォルトの保存場所が dist/data/schemas に変更されました。 今後この保存場所が変更される予定はありませんが、以前のバージョンから更新する場合は、スキーマファイルを新しい保存場所に移動してください。

クイックリンク

• インストール
• 例
• SchemaManager ガイドのディスカッション
• MemoryViewer ガイドのディスカッション

概要

MemoryMesh は、AI モデル向けの構造化された情報を構築・管理できる、ローカルのナレッジグラフサーバーです。特にテキストベースの RPG に適していますが、柔軟な設計により、ソーシャルネットワークのシミュレーションや組織計画など、構造化データを扱うさまざまなシナリオで活用できます。

主な機能

• 動的なスキーマベースのツール： スキーマでデータ構造を定義すると、MemoryMesh がデータの追加、更新、削除を行うツールを自動的に生成します。
• 直感的なスキーマ設計： 必須フィールド、列挙型、関係の定義を使って、AI がノードを生成し、相互に接続するための指針となるスキーマを作成できます。
• AI をガイドするメタデータ： メタデータを使ってコンテキストと構造を与え、AI がデータの意味や関係を理解できるようにします。
• 関係の処理： スキーマ内で関係を定義し、関連するデータポイント（ノード）間に AI が接続（エッジ）を作成するよう促します。
• 有益なフィードバック： AI にエラー情報を返すことで、AI が誤りから学び、ナレッジグラフとのやり取りを改善できるようにします。
• イベントのサポート： イベントシステムが操作を追跡し、ナレッジグラフがどのように変更されているかを把握できます。

ノード

ノードはナレッジグラフ内のエンティティや概念を表します。各ノードには次の項目があります。

• name：一意の識別子です。
• nodeType：ノードのタイプです（例：npc、artifact、location）。スキーマによって定義されます。
• metadata：ノードの詳細を記述する文字列の配列です。
• weight：（任意）関係の強さを表す 0 から 1 までの数値で、デフォルトは 1 です。

ノードの例：

    {
      "name": "Aragorn",
      "nodeType": "player_character",
      "metadata": [
        "Race: Human",
        "Class: Ranger",
        "Skills: Tracking, Swordsmanship",
        "Affiliation: Fellowship of the Ring"
      ]
    }

エッジ

エッジは、ノード間の関係を表します。各エッジには次の要素があります。

• from：ソースノードの名前です。
• to：ターゲットノードの名前です。
• edgeType：関係の種類です（例：owns、located_in）。

{
  "from": "Aragorn",
  "to": "Andúril",
  "edgeType": "owns"
}

スキーマ

スキーマはMemoryMeshの中核です。データの構造を定義し、ツールの自動生成を促します。

スキーマファイルの配置場所

ビルド済みのMemoryMeshプロジェクトのdist/data/schemasディレクトリに、スキーマファイル（.schema.json）を配置してください。MemoryMeshは起動時にこれらのファイルを自動的に検出して処理します。

スキーマの構造

ファイル名：[name].schema.json。たとえば、「npc」を定義するスキーマの場合、ファイル名はadd_npc.schema.jsonになります。

• name - メモリ内のスキーマとノードタイプを識別する名前です。重要：認識されるには、スキーマ名が必ずadd_で始まる必要があります。
• description - add_<name>ツールの説明として使用され、AIにコンテキストを提供します。（deleteツールとupdateツールには汎用の説明が使用されます）
• properties - 各プロパティには、型、説明、その他の制約が含まれます。
  • property
    • type - サポートされる値はstringまたはarrayです。
    • description - エンティティの目的をAIに伝えるのに役立ちます。
    • required - ブール値です。trueの場合、ノードの作成時にこのプロパティを指定するようAIに強制します。
    • enum - 文字列の配列です。指定されている場合、AIは指定された選択肢から選ぶ必要があります。
    • relationship - 別のノードへの接続を定義します。プロパティが必須で、リレーションシップが設定されている場合、AIはノードと対応するエッジの両方を必ず作成します。
      • edgeType - 作成するリレーションシップの種類です。
      • description - リレーションシップの目的をAIに伝えるのに役立ちます。
• additionalProperties - ブール値です。trueの場合、必須または任意として定義されたもの以外の属性をAIが追加できるようになります。

スキーマの例（add_npc.schema.json）：

{
  "name": "add_npc",
  "description": "Schema for adding an NPC to the memory" ,
  "properties": {
    "name": {
      "type": "string",
      "description": "A unique identifier for the NPC",
      "required": true
    },
    "race": {
      "type": "string",
      "description": "The species or race of the NPC",
      "required": true,
      "enum": [
        "Human",
        "Elf",
        "Dwarf",
        "Orc",
        "Goblin"
      ]
    },
    "currentLocation": {
      "type": "string",
      "description": "The current location of the NPC",
      "required": true,
      "relationship": {
        "edgeType": "located_in",
        "description": "The current location of the NPC"
      }
    }
  },
  "additionalProperties": true
}

このスキーマに基づき、MemoryMeshは次のツールを自動的に作成します。

• add_npc：新しいNPCノードを追加します。
• update_npc：既存のNPCノードを変更します。
• delete_npc：NPCノードを削除します。

MemoryMeshには、テキストベースのRPG向けに設計された11個の組み込みスキーマが含まれており、ゲーム開発にすぐに使える基盤を提供します。

SchemaManagerツール

MemoryMeshには、スキーマの作成と編集を簡単にするSchemaManagerツールが含まれています。視覚的なインターフェースを備えており、JSONを直接記述せずにデータ構造を簡単に定義できます。

動的ツール

MemoryMeshでは、動的ツールを通じてナレッジグラフとのやり取りを簡単に行えます。これらのツールは手動でコードを書くのではなく、スキーマ定義から直接自動生成されます。つまり、スキーマを使ってデータの構造を定義すると、MemoryMeshはその特定のデータ構造に対応するツールセットを自動的に作成します。

**次のように考えてください。**設計図（スキーマ）を用意すると、MemoryMeshがその設計図に基づいて、要素の作成、変更、削除に必要なツールを自動的に構築します。

裏側ではどのように動作しますか？

MemoryMesh には、スキーマ定義を読み取るインテリジェントなシステムがあります。定義した構造を分析し、エンティティのプロパティやその関係を確認します。この分析に基づいて、各エンティティタイプに対応する一連のツールを自動的に作成します。

• add_<entity>: エンティティの新しいインスタンスを作成するツールです。
• update_<entity>: 既存のエンティティを変更するツールです。
• delete_<entity>: エンティティを削除するツールです。

これらのツールは MemoryMesh 内の中央ハブを通じて利用できるようになり、接続されたすべてのクライアントや AI から簡単にアクセスして使用できます。

つまり、MemoryMesh の動的なツールシステムを使えば、ナレッジグラフを強力かつ効率的に管理できます。データ操作の基盤となる仕組みではなく、アプリケーションのコンテンツやロジックに集中できます。

メモリファイル

デフォルトでは、データは dist/data/memory.json の JSON ファイルに保存されます。

メモリビューア

メモリビューアは、MemoryMesh が管理するナレッジグラフの内容を視覚化して確認するための独立したツールです。ノード、エッジ、およびそれらのプロパティを使いやすいインターフェースで探索できます。

主な機能：

• グラフの視覚化：ナレッジグラフを、ノードとリンクからなるインタラクティブな図として表示します。
• ノードの確認：ノードを選択すると、nodeType、メタデータ、接続されているエッジを確認できます。
• エッジの探索：edgeType や方向など、ノード間の関係を確認できます。
• 検索とフィルタリング：特定のノードをすばやく検索したり、タイプで絞り込んだりできます。
• テーブル表示：特定のノードやエッジ、またはすべてのノードとエッジを簡単に見つけて確認できます。
• 生の JSON 表示：メモリファイルの生の JSON データを表示できます。
• 統計パネル：ナレッジグラフの主要な指標と情報を表示します。ノードの総数、エッジの総数、ノードのタイプ、エッジのタイプを確認できます。
• 検索とフィルター：ノードタイプまたはエッジタイプで絞り込んだり、ノード、エッジ、または両方を表示するかを選択したりできます。

メモリビューアへのアクセス

メモリビューアはスタンドアロンのウェブアプリケーションです。メモリビューアに関するディスカッション

メモリビューアの使用方法

• メモリファイルを選択：メモリビューアで「Select Memory File」ボタンをクリックします。
• ファイルを選択：MemoryMesh のプロジェクトディレクトリに移動し、memory.json ファイルを選択します（デフォルトの場所は dist/data/memory.json です）。
• 探索：メモリビューアがナレッジグラフの内容を読み込み、表示します。

メモリフロー

プロンプト

最適な結果を得るには、カスタム指示を設定した Claude の「Projects」機能を使用してください。以下は、最初に使えるプロンプトの例です。

You are a helpful AI assistant managing a knowledge graph for a text-based RPG. You have access to the following tools: add_npc, update_npc, delete_npc, add_location, update_location, delete_location, and other tools for managing the game world.

When the user provides input, first process it using your available tools to update the knowledge graph. Then, respond in a way that is appropriate for a text-based RPG.

チャットで直接、特定のアクションを実行するよう AI に指示することもできます。

さまざまなプロンプトを試して、用途に最適なものを見つけてください。

例

1. カスタム指示を使ったシンプルな例です。
2. 視覚化を含む、例のための例です (機能の一部ではありません)

いくつかの都市と NPC を追加し、街の周辺に探索できる場所をいくつか作り、遺物を 1 つか 2 つどこかに隠してください

インストール

前提条件

• Node.js： バージョン 18 以降。 nodejs.org からダウンロードできます。
• npm： 通常は Node.js に含まれています。
• Claude for Desktop： claude.ai/download から最新バージョンをインストールしてください。

インストール手順

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

   git clone https://github.com/CheMiguel23/memorymesh.git
   cd memorymesh
   

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

   npm install
   

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

   npm run build
   

   このコマンドは、TypeScript コードを dist ディレクトリ内の JavaScript にコンパイルし、サンプルのスキーマファイルとデータファイルもそこにコピーします。

4. ファイルのコピーを確認します（任意）：

   • ビルドプロセスによって、data フォルダーが dist に自動的にコピーされます。
   • dist/data が存在し、.json ファイルが含まれていることを確認します。また、dist/data/schemas が存在し、.schema.json ファイルが含まれていることも確認します。

5. Claude Desktop を設定します：

   Claude Desktop の設定ファイルを開きます。

   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows： %APPDATA%\Claude\claude_desktop_config.json
   • mcpServers セクションに memorymesh のエントリを追加します。次の設定オプションから1 つ選択できます。

   "mcpServers": {
     "memorymesh": {
       "command": "node", 
       "args": ["/ABSOLUTE/PATH/TO/YOUR/PROJECT/memorymesh/dist/index.js"]
     }
   }
   

   • /ABSOLUTE/PATH/TO/YOUR/PROJECT/ を、memorymesh プロジェクトディレクトリの実際の絶対パスに置き換えます。
   • 例（macOS）：

     "command": "node",
     "args": ["/Users/yourusername/Projects/memorymesh/dist/index.js"]
     

   • 例（Windows）：

     "command": "node",
     "args": ["C:\\Projects\\memorymesh\\dist\\index.js"]
     

6. Claude Desktop を再起動します： 変更を反映するには、Claude Desktop を完全に再起動してください。

インストールの確認

1. Claude Desktop を起動します。
2. 新しいチャットを開きます。
3. 右上隅に MCP プラグインのアイコン があることを確認します。表示されていれば、設定は正しい可能性が高いです。
4. アイコンをクリックします。接続済みサーバーの一覧に「memorymesh」が表示されます。
5. アイコンをクリックします。ツール（例：add_npc、update_npc など）が表示されていれば、サーバーは動作しており、ツールが正しく公開されています。

更新

更新する前に、メモリデータが失われないよう、dist/data ディレクトリを必ずバックアップしてください。

トラブルシューティング

• Claude にサーバーが表示されない場合：

  • claude_desktop_config.json 内のパスを再確認します。絶対パスであり、正しいことを確認してください。
  • dist ディレクトリが存在し、index.js を含むコンパイル済み JavaScript ファイルが含まれていることを確認します。
  • Claude Desktop のログにエラーがないか確認します。
    • macOS： ~/Library/Logs/Claude/mcp-server-memorymesh.log（および mcp.log）
    • Windows： （おそらく %AppData%\Claude 内の Logs フォルダー）

• ツールが表示されない場合：

  • npm run build コマンドがエラーなく完了したことを確認します。
  • スキーマファイルが dist/data/schemas に正しく配置され、正しい命名規則（add_[entity].schema.json）に従っていることを確認します。
  • 初期化中にエラーが発生していないか、サーバーのコンソール出力またはログを確認します。

詳細設定

MemoryMesh では、基本設定に加えて、動作をカスタマイズする方法がいくつか用意されています。

変数

/config/config.ts を使用して、デフォルト設定を上書きできます。

• MEMORY_FILE：ナレッジグラフデータの保存に使用する JSON ファイルのパスを指定します。（デフォルト：dist/data/memory.json）
• SCHEMAS_DIR：スキーマファイルのディレクトリパスです。（デフォルト：dist/data/schemas/memory.json）

制限事項

1. ノードの削除： AI はナレッジグラフからノードを削除することに慎重になる場合があります。必要に応じて、プロンプトで促してください。

2. 競合する情報： MemoryMesh は現在、データの処理に「後勝ち」の方式を使用しています。同じエンティティについて競合する情報が提供された場合、最新の更新内容が以前の値を上書きします。競合する情報を管理するための方法を以下に示します。

   現在の方法：

   • メタデータで情報源を記録する： "Source: Character testimony" や "Source: Official records" などのメタデータ項目を追加して、情報の出所を記録します。
   • 時間的なメタデータを使用する： 情報が有効だった時期を記録するため、メタデータにタイムスタンプや物語上の時間を示す目印（例："As of Chapter 3"）を含めます。
   • 視点ごとに別のノードを作成する： 主観的または議論のある情報については、異なる視点を表す別々のノード（例：rumor_about_villain と truth_about_villain）を作成します。
   • エッジの重みを使用する： エッジのオプションの weight プロパティ（範囲：0～1）を利用して、関係の確信度や信頼性を示します。

   例 - 不確かな情報の記録：

   {
     "name": "VillainOrigin_Rumor",
     "nodeType": "information",
     "metadata": [
       "Source: Tavern gossip",
       "Reliability: Low",
       "Claims: Villain came from the northern mountains"
     ]
   }
   

   今後の検討事項： 高度な競合解決が必要なアプリケーションでは、次の機能を備えたカスタムレイヤーの実装を検討してください。

   • ノードの変更履歴を保持する
   • 各情報の来歴（情報源）を記録する
   • 主張に対する確信度スコアを実装する
   • 事実の時間的な有効期間をサポートする

貢献

貢献、フィードバック、アイデアを歓迎します！ このプロジェクトは、構造化データと AI の推論能力を統合する個人的な探求です。さらなる発展や新しいプロジェクトのひらめきにつながる貢献、フィードバック、アイデアを歓迎します。