Memento

Memento MCP：LLM 向けナレッジグラフメモリシステム

セマンティック検索、文脈に応じた想起、時間的な認識機能を備えた、スケーラブルで高性能なナレッジグラフメモリシステムです。モデルコンテキストプロトコルに対応するあらゆる LLM クライアント（Claude Desktop、Cursor、Github Copilot など）に、堅牢で適応性があり、永続的な長期オントロジーメモリを提供します。

主な概念

エンティティ

エンティティはナレッジグラフの主要なノードです。各エンティティには、次の情報があります。

• 一意の名前（識別子）
• エンティティの種類（例：「person」、「organization」、「event」）
• 観察事項のリスト
• ベクトル埋め込み（セマンティック検索用）
• 完全なバージョン履歴

例：

{
  "name": "John_Smith",
  "entityType": "person",
  "observations": ["Speaks fluent Spanish"]
}

リレーション

リレーションは、拡張されたプロパティを備えた、エンティティ間の有向接続を定義します。

• 強度の指標（0.0～1.0）
• 信頼度（0.0～1.0）
• 豊富なメタデータ（ソース、タイムスタンプ、タグ）
• バージョン履歴による時間的な認識
• 時間経過に伴う信頼度の減衰

例：

{
  "from": "John_Smith",
  "to": "Anthropic",
  "relationType": "works_at",
  "strength": 0.9,
  "confidence": 0.95,
  "metadata": {
    "source": "linkedin_profile",
    "last_verified": "2025-03-21"
  }
}

ストレージバックエンド

Memento MCP はストレージバックエンドに Neo4j を使用し、グラフストレージとベクトル検索機能の両方を統合したソリューションを提供します。

Neo4j を選ぶ理由

• 統合ストレージ：グラフとベクトルの両方のストレージを単一のデータベースに集約します
• ネイティブなグラフ操作：グラフの走査とクエリ用に特化して構築されています
• 統合ベクトル検索：埋め込みのベクトル類似性検索が Neo4j に直接組み込まれています
• スケーラビリティ：大規模なナレッジグラフでも優れたパフォーマンスを発揮します
• シンプルなアーキテクチャ：すべての操作に単一のデータベースを使用する、すっきりとした設計です

前提条件

• Neo4j 5.13 以降（ベクトル検索機能に必要）

Neo4j Desktop のセットアップ（推奨）

Neo4j を使い始める最も簡単な方法は、Neo4j Desktop を使用することです。

1. https://neo4j.com/download/ から Neo4j Desktop をダウンロードしてインストールします
2. 新しいプロジェクトを作成します
3. 新しいデータベースを追加します
4. パスワードを memento_password（または任意のパスワード）に設定します
5. データベースを起動します

Neo4j データベースには次のアドレスで接続できます。

• Bolt URI：bolt://127.0.0.1:7687（ドライバー接続用）
• HTTP：http://127.0.0.1:7474（Neo4j Browser UI 用）
• デフォルトの認証情報：ユーザー名：neo4j、パスワード：memento_password（または設定したパスワード）

Docker を使った Neo4j のセットアップ（代替方法）

代わりに、Docker Compose を使って Neo4j を実行することもできます。

# Start Neo4j container
docker-compose up -d neo4j

# Stop Neo4j container
docker-compose stop neo4j

# Remove Neo4j container (preserves data)
docker-compose rm neo4j

Docker を使用する場合、Neo4j データベースには次のアドレスで接続できます。

• Bolt URI：bolt://127.0.0.1:7687（ドライバー接続用）
• HTTP：http://127.0.0.1:7474（Neo4j Browser UI 用）
• デフォルトの認証情報：ユーザー名：neo4j、パスワード：memento_password

データの永続化と管理

docker-compose.yml ファイルの Docker ボリューム設定により、Neo4j のデータはコンテナの再起動後やバージョンのアップグレード後も保持されます。

volumes:
  - ./neo4j-data:/data
  - ./neo4j-logs:/logs
  - ./neo4j-import:/import

これらのマッピングにより、次のことが保証されます。

• /data ディレクトリ（すべてのデータベースファイルを含む）は、ホスト上の ./neo4j-data に保持されます
• /logs ディレクトリは、ホスト上の ./neo4j-logs に保持されます
• /import ディレクトリ（データファイルのインポート用）は、./neo4j-import に保持されます

必要に応じて、docker-compose.yml ファイルでこれらのパスを変更し、別の場所にデータを保存できます。

Neo4j のバージョンアップグレード

データを失わずに Neo4j のエディションやバージョンを変更できます。

1. docker-compose.yml の Neo4j イメージのバージョンを更新します
2. docker-compose down && docker-compose up -d neo4j でコンテナを再起動します
3. npm run neo4j:init でスキーマを再初期化します

ボリュームのマッピングを同じままにしておけば、この手順を通じてデータは保持されます。

データベースの完全リセット

Neo4j データベースを完全にリセットする必要がある場合は、次の操作を行います。

# Stop the container
docker-compose stop neo4j

# Remove the container
docker-compose rm -f neo4j

# Delete the data directory contents
rm -rf ./neo4j-data/*

# Restart the container
docker-compose up -d neo4j

# Reinitialize the schema
npm run neo4j:init

データのバックアップ

Neo4j のデータをバックアップするには、データディレクトリをコピーするだけです。

# Make a backup of the Neo4j data
cp -r ./neo4j-data ./neo4j-data-backup-$(date +%Y%m%d)

Neo4j CLI ユーティリティ

Memento MCP には、Neo4j の操作を管理するためのコマンドラインユーティリティが含まれています。

接続のテスト

Neo4j データベースへの接続をテストします。

# Test with default settings
npm run neo4j:test

# Test with custom settings
npm run neo4j:test -- --uri bolt://127.0.0.1:7687 --username myuser --password mypass --database neo4j

スキーマの初期化

通常の操作では、Memento MCP がデータベースに接続すると、Neo4j のスキーマは自動的に初期化されます。通常の使用時に手動でコマンドを実行する必要はありません。

次のコマンドが必要なのは、開発、テスト、または高度なカスタマイズを行う場合のみです。

# Initialize with default settings (only needed for development or troubleshooting)
npm run neo4j:init

# Initialize with custom vector dimensions
npm run neo4j:init -- --dimensions 768 --similarity euclidean

# Force recreation of all constraints and indexes
npm run neo4j:init -- --recreate

# Combine multiple options
npm run neo4j:init -- --vector-index custom_index --dimensions 384 --recreate

高度な機能

セマンティック検索

キーワードだけでなく意味に基づいて、意味的に関連するエンティティを検索します。

• ベクトル埋め込み：OpenAI の埋め込みモデルを使用して、エンティティを高次元のベクトル空間に自動的にエンコードします
• コサイン類似度：異なる用語が使われていても、関連する概念を見つけます
• しきい値の設定：最小類似度スコアを設定して、結果の関連性を調整します
• クロスモーダル検索：テキストでクエリを実行し、どのような表現で記述されているかにかかわらず、関連するエンティティを検索します
• 複数モデルのサポート：複数の埋め込みモデル（OpenAI text-embedding-3-small/large）と互換性があります
• コンテキストに基づく検索：完全一致するキーワードではなく、意味に基づいて情報を取得します
• 最適化されたデフォルト設定：適合率と再現率のバランスを取るためにパラメーターを調整しています（類似度しきい値は 0.6、ハイブリッド検索は有効）
• ハイブリッド検索：セマンティック検索とキーワード検索を組み合わせ、より包括的な結果を提供します
• 適応型検索：クエリの特性と利用可能なデータに基づいて、ベクトルのみ、キーワードのみ、またはハイブリッド検索をシステムが自動的に選択します
• パフォーマンスの最適化：セマンティックな理解にはベクトル検索を優先しつつ、堅牢性を保つためのフォールバック機構も維持します
• クエリを考慮した処理：クエリの複雑さと利用可能なエンティティの埋め込みに基づいて、検索戦略を調整します

時系列の認識

時点を指定したグラフの取得により、エンティティと関係の完全な履歴を追跡します。

• 完全なバージョン履歴：エンティティや関係に対するすべての変更を、タイムスタンプ付きで保存します
• 特定時点のクエリ：過去の任意の時点におけるナレッジグラフの正確な状態を取得します
• 変更の追跡：createdAt、updatedAt、validFrom、validTo のタイムスタンプを自動的に記録します
• 時系列の一貫性：知識がどのように変化したかを、歴史的に正確な状態で維持します
• 非破壊的な更新：既存のデータを上書きせず、新しいバージョンを作成します
• 時間に基づくフィルタリング：時系列の条件に基づいてグラフ要素を絞り込みます
• 履歴の調査：特定の情報が時間とともにどのように変化したかを調べます

確信度の減衰

設定可能な半減期に基づき、関係の確信度は時間とともに自動的に減衰します。

• 時間に基づく減衰：新たに補強されない場合、関係に対する確信度は時間とともに自然に低下します
• 半減期の設定：情報の確実性がどれだけの速さで低下するかを定義します（デフォルト：30 日）
• 確信度の下限：重要な情報が過度に減衰しないよう、しきい値を設定します
• 減衰メタデータ：各関係に、減衰計算の詳細情報が含まれます
• 非破壊的な処理：減衰後の値とともに、元の確信度も保持されます
• 強化学習：新たな観測によって補強されると、関係の確信度は回復します
• 基準時刻の柔軟な設定：履歴分析のために、任意の基準時刻に基づいて減衰を計算します

高度なメタデータ

エンティティとリレーションの両方で、カスタムフィールドを含む豊富なメタデータをサポートします。

• ソースの追跡：情報の出所（ユーザー入力、分析、外部ソース）を記録します
• 信頼度：確実性に基づいて、リレーションに信頼度スコア（0.0-1.0）を割り当てます
• リレーションの強度：関係の重要度や強さ（0.0-1.0）を示します
• 時間的メタデータ：情報の追加、変更、確認がいつ行われたかを追跡します
• カスタムタグ：分類やフィルタリングに使用する任意のタグを追加します
• 構造化データ：メタデータフィールド内に複雑な構造化データを保存します
• クエリのサポート：メタデータのプロパティに基づいて検索、フィルタリングします
• 拡張可能なスキーマ：コアデータモデルを変更せずに、必要に応じてカスタムフィールドを追加できます

MCP API ツール

以下のツールを、Model Context Protocol を通じて LLM クライアントホストから利用できます。

エンティティ管理

• create_entities

  • ナレッジグラフに複数の新しいエンティティを作成します
  • 入力：entities（オブジェクトの配列）
    • 各オブジェクトには以下が含まれます。
      • name（string）：エンティティ識別子
      • entityType（string）：タイプ分類
      • observations（string[]）：関連する観察事項

• add_observations

  • 既存のエンティティに新しい観察事項を追加します
  • 入力：observations（オブジェクトの配列）
    • 各オブジェクトには以下が含まれます。
      • entityName（string）：対象エンティティ
      • contents（string[]）：追加する新しい観察事項

• delete_entities

  • エンティティとそのリレーションを削除します
  • 入力：entityNames（string[]）

• delete_observations

  • エンティティから特定の観察事項を削除します
  • 入力：deletions（オブジェクトの配列）
    • 各オブジェクトには以下が含まれます。
      • entityName（string）：対象エンティティ
      • observations（string[]）：削除する観察事項

リレーション管理

• create_relations

  • 拡張プロパティを指定して、エンティティ間に複数の新しいリレーションを作成します
  • 入力：relations（オブジェクトの配列）
    • 各オブジェクトには以下が含まれます。
      • from（string）：ソースエンティティ名
      • to（string）：ターゲットエンティティ名
      • relationType（string）：関係のタイプ
      • strength（number、任意）：リレーションの強度（0.0-1.0）
      • confidence（number、任意）：信頼度（0.0-1.0）
      • metadata（object、任意）：カスタムメタデータフィールド

• get_relation

  • 拡張プロパティを含む特定のリレーションを取得します
  • 入力：
    • from（string）：ソースエンティティ名
    • to（string）：ターゲットエンティティ名
    • relationType（string）：関係のタイプ

• update_relation

  • 拡張プロパティを指定して、既存のリレーションを更新します
  • 入力：relation（object）：
    • 以下が含まれます。
      • from（string）：ソースエンティティ名
      • to（string）：ターゲットエンティティ名
      • relationType（string）：関係のタイプ
      • strength（number、任意）：リレーションの強度（0.0-1.0）
      • confidence（number、任意）：信頼度（0.0-1.0）
      • metadata（object、任意）：カスタムメタデータフィールド

• delete_relations

  • グラフから特定のリレーションを削除します
  • 入力：relations（オブジェクトの配列）
    • 各オブジェクトには以下が含まれます。
      • from（string）：ソースエンティティ名
      • to（string）：ターゲットエンティティ名
      • relationType（string）：関係のタイプ

グラフ操作

• read_graph

  • ナレッジグラフ全体を読み取ります
  • 入力は不要です

• search_nodes

  • クエリに基づいてノードを検索します
  • 入力：query（string）

• open_nodes

  • 名前を指定して特定のノードを取得します
  • 入力：names（string[]）

セマンティック検索

• semantic_search

  • ベクトル埋め込みと類似度を使用して、エンティティを意味的に検索します
  • 入力：
    • query（string）：意味的に検索するテキストクエリ
    • limit（number、任意）：返す結果の最大数（デフォルト：10）
    • min_similarity（number、任意）：類似度の最小しきい値（0.0～1.0、デフォルト：0.6）
    • entity_types（string[]、任意）：エンティティの種類で結果を絞り込みます
    • hybrid_search（boolean、任意）：キーワード検索とセマンティック検索を組み合わせます（デフォルト：true）
    • semantic_weight（number、任意）：ハイブリッド検索におけるセマンティック検索結果の重み（0.0～1.0、デフォルト：0.6）
  • 機能：
    • クエリのコンテキストに基づいて、最適な検索方法（ベクトル、キーワード、ハイブリッド）をインテリジェントに選択します
    • フォールバック機能により、セマンティック検索で一致する結果がないクエリも適切に処理します
    • 自動最適化の判断により、高いパフォーマンスを維持します

• get_entity_embedding

  • 特定のエンティティのベクトル埋め込みを取得します
  • 入力：
    • entity_name（string）：埋め込みを取得するエンティティの名前

時系列機能

• get_entity_history

  • エンティティの完全なバージョン履歴を取得します
  • 入力：entityName（string）

• get_relation_history

  • 関係の完全なバージョン履歴を取得します
  • 入力：
    • from（string）：ソースエンティティ名
    • to（string）：ターゲットエンティティ名
    • relationType（string）：関係の種類

• get_graph_at_time

  • 指定したタイムスタンプにおけるグラフの状態を取得します
  • 入力：timestamp（number）：Unix タイムスタンプ（エポックからの経過時間、ミリ秒）

• get_decayed_graph

  • 時間経過に応じて信頼度が減衰したグラフを取得します
  • 入力：options（object、任意）：
    • reference_time（number）：減衰計算の基準となるタイムスタンプ（エポックからの経過時間、ミリ秒）
    • decay_factor（number）：任意の減衰係数の上書き値

設定

環境変数

以下の環境変数で Memento MCP を設定します：

# Neo4j Connection Settings
NEO4J_URI=bolt://127.0.0.1:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=memento_password
NEO4J_DATABASE=neo4j

# Vector Search Configuration
NEO4J_VECTOR_INDEX=entity_embeddings
NEO4J_VECTOR_DIMENSIONS=1536
NEO4J_SIMILARITY_FUNCTION=cosine

# Embedding Service Configuration
MEMORY_STORAGE_TYPE=neo4j
OPENAI_API_KEY=your-openai-api-key
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Debug Settings
DEBUG=true

コマンドラインオプション

Neo4j CLI ツールでは、次のオプションを使用できます：

--uri <uri>              Neo4j server URI (default: bolt://127.0.0.1:7687)
--username <username>    Neo4j username (default: neo4j)
--password <password>    Neo4j password (default: memento_password)
--database <n>           Neo4j database name (default: neo4j)
--vector-index <n>       Vector index name (default: entity_embeddings)
--dimensions <number>    Vector dimensions (default: 1536)
--similarity <function>  Similarity function (cosine|euclidean) (default: cosine)
--recreate               Force recreation of constraints and indexes
--no-debug               Disable detailed output (debug is ON by default)

埋め込みモデル

利用可能な OpenAI 埋め込みモデル：

• text-embedding-3-small：効率的でコスト効率に優れています（1536 次元）
• text-embedding-3-large：精度が高く、より高価です（3072 次元）
• text-embedding-ada-002：レガシーモデル（1536 次元）

OpenAI API の設定

セマンティック検索を使用するには、OpenAI API の認証情報を設定する必要があります：

1. OpenAI から API キーを取得します
2. 次のように環境を設定します：

# OpenAI API Key for embeddings
OPENAI_API_KEY=your-openai-api-key
# Default embedding model
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

注：テスト環境では、API キーが指定されていない場合、システムは埋め込みの生成をモックします。ただし、統合テストには実際の埋め込みを使用することをおすすめします。

Claude Desktop との統合

設定

次の内容を claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "memento": {
      "command": "npx",
      "args": ["-y", "@gannonh/memento-mcp"],
      "env": {
        "MEMORY_STORAGE_TYPE": "neo4j",
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "memento_password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_VECTOR_INDEX": "entity_embeddings",
        "NEO4J_VECTOR_DIMENSIONS": "1536",
        "NEO4J_SIMILARITY_FUNCTION": "cosine",
        "OPENAI_API_KEY": "your-openai-api-key",
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
        "DEBUG": "true"
      }
    }
  }
}

または、ローカル開発では次を使用できます：

{
  "mcpServers": {
    "memento": {
      "command": "/path/to/node",
      "args": ["/path/to/memento-mcp/dist/index.js"],
      "env": {
        "MEMORY_STORAGE_TYPE": "neo4j",
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "memento_password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_VECTOR_INDEX": "entity_embeddings",
        "NEO4J_VECTOR_DIMENSIONS": "1536",
        "NEO4J_SIMILARITY_FUNCTION": "cosine",
        "OPENAI_API_KEY": "your-openai-api-key",
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
        "DEBUG": "true"
      }
    }
  }
}

重要：一貫した動作を確保するため、Claude Desktop の設定では常に埋め込みモデルを明示的に指定してください。

推奨システムプロンプト

Claude との統合を最適化するには、次の文をシステムプロンプトに追加します：

You have access to the Memento MCP knowledge graph memory system, which provides you with persistent memory capabilities.
Your memory tools are provided by Memento MCP, a sophisticated knowledge graph implementation.
When asked about past conversations or user information, always check the Memento MCP knowledge graph first.
You should use semantic_search to find relevant information in your memory when answering questions.

セマンティック検索のテスト

設定が完了すると、Claude は自然言語を通じてセマンティック検索機能にアクセスできます：

1. セマンティック埋め込みを使用してエンティティを作成するには：

   User: "Remember that Python is a high-level programming language known for its readability and JavaScript is primarily used for web development."
   

2. 意味的に検索するには：

   User: "What programming languages do you know about that are good for web development?"
   

3. 特定の情報を取得するには：

   User: "Tell me everything you know about Python."
   

この方法の利点は、ユーザーが自然にやり取りできる一方で、LLM が適切なメモリツールの選択と使用に伴う複雑さを処理できることです。

実用例

Memento の適応型検索機能は、実用的なメリットをもたらします。

1. クエリの柔軟性：ユーザーは質問の表現方法を気にする必要がありません。システムがさまざまな種類のクエリに自動的に適応します。

2. 障害への耐性：セマンティック検索で一致する結果が見つからない場合も、ユーザーが操作しなくても、システムは代替手段に切り替えられます。

3. パフォーマンスの効率性：最適な検索方法をインテリジェントに選択することで、システムは各クエリに応じてパフォーマンスと関連性のバランスを取ります。

4. コンテキスト検索の改善：複雑なナレッジグラフ全体から関連情報を見つけられるため、LLM との会話で、より適切なコンテキストを取得できます。

たとえば、ユーザーが「機械学習について何を知っていますか？」と尋ねると、システムは「機械学習」という語を明示的に含んでいなくても、概念的に関連するエンティティを取得できます。たとえば、ニューラルネットワーク、データサイエンス、特定のアルゴリズムに関するエンティティなどです。ただし、セマンティック検索で十分な結果が得られない場合、システムは自動的に検索方法を調整し、引き続き有用な情報を返します。

トラブルシューティング

ベクトル検索の診断

Memento MCP には、ベクトル検索の問題をトラブルシューティングするための診断機能が組み込まれています。

• 埋め込みの検証：システムはエンティティに有効な埋め込みがあるか確認し、ない場合は自動的に生成します。
• ベクトルインデックスのステータス：ベクトルインデックスが存在し、ONLINE 状態であることを確認します。
• フォールバック検索：ベクトル検索に失敗すると、システムはテキストベースの検索に切り替えます。
• 詳細なログ記録：トラブルシューティングに役立つ、ベクトル検索操作の包括的なログを記録します。

デバッグツール（DEBUG=true の場合）

デバッグモードを有効にすると、追加の診断ツールを利用できます。

• diagnose_vector_search：Neo4j のベクトルインデックス、埋め込みの数、検索機能に関する情報を表示します。
• force_generate_embedding：特定のエンティティの埋め込みを強制的に生成します。
• debug_embedding_config：現在の埋め込みサービス設定に関する情報を表示します。

開発環境のリセット

開発中に Neo4j データベースを完全にリセットするには、次のようにします。

# Stop the container (if using Docker)
docker-compose stop neo4j

# Remove the container (if using Docker)
docker-compose rm -f neo4j

# Delete the data directory (if using Docker)
rm -rf ./neo4j-data/*

# For Neo4j Desktop, right-click your database and select "Drop database"

# Restart the database
# For Docker:
docker-compose up -d neo4j

# For Neo4j Desktop:
# Click the "Start" button for your database

# Reinitialize the schema
npm run neo4j:init

ビルドと開発

# Clone the repository
git clone https://github.com/gannonh/memento-mcp.git
cd memento-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Check test coverage
npm run test:coverage

インストール

Smithery 経由でのインストール

Smithery を使って、Claude Desktop 用の memento-mcp を自動的にインストールするには、次のようにします。

npx -y @smithery/cli install @gannonh/memento-mcp --client claude

npx を使ったグローバルインストール

グローバルにインストールせずに、npx を使って Memento MCP を直接実行できます。

npx -y @gannonh/memento-mcp

この方法は、Claude Desktop やその他の MCP 対応クライアントでの使用におすすめです。

ローカルインストール

開発やプロジェクトへの貢献を行う場合は、次のようにします。

# Install locally
npm install @gannonh/memento-mcp

# Or clone the repository
git clone https://github.com/gannonh/memento-mcp.git
cd memento-mcp
npm install

ライセンス

MIT