garnet-mcp

Garnet Vector Memory MCP Server

M C P（Model Context Protocol） サーバーです。Garnet Vector Sets を基盤とする 検索拡張（RAG）メモリを LLM エージェントに提供します。エージェントはテキストを埋め込みとして保存し、後から意味に基づいて意味的に最も関連性の高いスニペットを取得し、応答の根拠として使用できます。単一の会話内だけでなく、セッションをまたいで永続化されます。これはアプリケーション層での意味的想起（RAG）であり、取得したコンテキストでモデルのプロンプトを拡張するものです。推論層での KV キャッシュ再利用（LMCache など）とは異なります。ローカルまたはセルフホストの OSS Garnet（あるいは Vector Sets に対応する Redis 互換エンドポイント）に接続して動作し、埋め込みは独自に用意できます。

ツール

サーバーは MCP の stdio トランスポート経由で 5 つのツールを公開します（HTTP もサポートされています）。

ツール	説明
store_memory	事実やテキストを長期メモリに保存します。メモリ ID を返します。
recall_memory	保存されたメモリを意味検索し、スコア付きで最も近い一致を返します。
forget_memory	ID を指定して、保存されたメモリを削除します。
list_indexes	現在存在するベクトルセットのメモリインデックスを一覧表示します。
index_info	メモリインデックスキーのメタデータ（メトリック、次元数、サイズ）を表示します。

前提条件

• .NET 10 SDK — クライアントが dnx コマンドでサーバーを起動するために必要です（.NET 10 SDK に同梱されています）。パッケージ自体のターゲットは net9.0 です。
• Vector Sets を有効にして起動した Garnet サーバー。 Vector Sets は現在 Garnet のプレビュー機能であり、--enable-vector-set-preview で明示的に有効にする必要があります。V* ベクトルコマンドを公開する Redis 互換エンドポイントも使用できます。
• 埋め込み（任意ですが推奨）。 Embeddings__Provider=AzureOpenAI を設定し、Azure OpenAI の埋め込みデプロイメントを指定してください（DefaultAzureCredential / az login によるキー不要の認証）。設定しない場合、サーバーは外部呼び出しが不要な決定論的な Fake プロバイダーにフォールバックします。ローカルでのデモやテストには便利ですが、意味のある意味検索には適しません。

インストール（NuGet から）

このサーバーは、MCP クライアントが dnx 経由で実行する .NET ツールパッケージとして公開されています。クライアントの MCP 設定に追加してください。たとえば、VS Code / GitHub Copilot の場合は .vscode/mcp.json に追加します。

{
  "servers": {
    "garnet-mcp": {
      "type": "stdio",
      "command": "dnx",
      "args": ["[email protected]", "--yes"],
      "env": {
        "Garnet__Host": "127.0.0.1",
        "Garnet__Port": "6379",
        "Embeddings__Provider": "AzureOpenAI",
        "Embeddings__Endpoint": "https://YOUR-RESOURCE.openai.azure.com/",
        "Embeddings__DeploymentName": "text-embedding-3-small",
        "Embeddings__Dimensions": "1536"
      }
    }
  }
}

完全オフラインのデモを実行するには、Embeddings__* の項目を削除するか、Embeddings__Provider=Fake を設定してください。

推奨されるエージェント向け指示

サーバーは接続時に、すべての MCP クライアントに使用方法のガイダンスをすでに送信します（サーバーの ServerInstructions 経由）。そのため、ほとんどのエージェントは指示がなくても適切にツールを使用します。エージェントにメモリを積極的に使わせたい場合は、そのエージェントのカスタム指示に次のような内容を追加してください（たとえば、あなたのプロジェクトの .github/copilot-instructions.md、Claude/Cursor のルールファイルなど）。

ユーザーについての質問（好み、事実、決定、過去の発言など）に答える前に、たとえ答えが現在のチャットに含まれているように見えても、まず必ず recall_memory を呼び出してください（メモリはセッションをまたいで保持されます）。ユーザーが自分について長期的に有効な事実を述べたり、何かを覚えておくよう依頼したりした場合は、store_memory を呼び出して保存し、保存した内容を簡潔に伝えてください。

設定

すべての設定は、構成または環境変数から読み込まれます。環境変数の形式では、セクション区切り文字として __（アンダースコア2つ）を使用します。

設定	環境変数	デフォルト	備考
Garnet ホスト	Garnet__Host	127.0.0.1	空欄の場合はデフォルト値として扱われます。
Garnet ポート	Garnet__Port	6379
キープレフィックス	Garnet__KeyPrefix	mem	メモリーインデックスキーのプレフィックスです。
Redis コマンドをログに記録	Garnet__LogRedisCommands	false	トラブルシューティングのため、true に設定すると同等の redis-cli コマンドを Debug レベルで記録します。
ログレベル	Logging__LogLevel__Default	Information	デフォルトでは、起動時の簡潔なメッセージと警告・エラーのみが記録されます。呼び出しごとのツールのトレースを有効にするには、Debug に設定してください。stdio トランスポートでは、ログは stderr に出力されます。
埋め込みプロバイダー	Embeddings__Provider	Fake	AzureOpenAI または Fake です。
Azure OpenAI エンドポイント	Embeddings__Endpoint	—	プロバイダーが AzureOpenAI の場合に必須です。
デプロイ名	Embeddings__DeploymentName	text-embedding-3-small
次元数	Embeddings__Dimensions	1536（AOAI）／8（Fake）	埋め込みモデルと一致している必要があります。
API キー	Embeddings__ApiKey	—	任意です。キーを使用しない DefaultAzureCredential を推奨します。
メモリーの所有者	Memory__User	default	メモリーの所有者を固定し、保存と想起が常に一致するようにします。
トランスポート	Transport	Stdio	Stdio（ローカル）または Http（ホスト型）です。

埋め込みプロバイダー

すぐに利用できるプロバイダーが2つあります。

• AzureOpenAI — 実際の埋め込みを生成します。本番環境で品質を確保できる唯一の選択肢です。DefaultAzureCredential（または API キー）を使用して、キーなしで利用できます。
• Fake — 決定論的でオフライン動作する、ハッシュをシードにしたベクトルを生成します。ローカル実行やテストに便利ですが、意味的な情報はありません。実際の想起には使用しないでください。

埋め込み生成は IEmbeddingProvider 抽象化（EmbedAsync／EmbedBatchAsync、および ModelName と Dimensions）の背後にあります。システムの残りの部分である GarnetMemoryStore、ベクタークライアント、ツールは、このインターフェースのみに依存しているため、コードに手を加えずに追加のバックエンド（たとえば OpenAI、Ollama を介して提供するローカルモデル、Hugging Face）を導入できます。追加するには、IEmbeddingProvider を実装し、Program.cs の ConfigureDomain で、対応する Embeddings__Provider の値に登録してください。

メモリーの所有権（設計上のシングルテナント）

メモリーの所有者は、サーバープロセスの実行中、構成（Memory__User、デフォルトは default）によって固定されます。モデルが呼び出しごとに所有者を選ぶことはできません。store_memory と recall_memory はどちらもその所有者にスコープされるため（想起では保存された user 属性で絞り込みます）、チャットやセッションをまたいでも、保存と想起の対象は常に一致します。

これは、同梱モデルの用途に適しています。つまり、自分のクライアントが stdio 経由で起動する、個人向けの単一所有者サーバーです。この場合、プロセス自体がユーザーです。モデルに呼び出しごとのユーザー指定を許すと、保存と想起の対象が食い違い（モデルは一貫しないため）、別の呼び出し元のメモリーを読み取ったり上書きしたりできるようになるため、意図的に避けています。

ホスト型のマルチテナントデプロイ（Http トランスポートで多数のユーザーにサービスを提供する構成）では、所有者の正しい情報源は 認証済みの呼び出し元の ID（認証トークン／ヘッダーから取得）です。モデルが選択した値を使うことは決して避けてください。これは今後意図的に追加する機能であり、ツールの引数を通じて渡すものではありません。

ソースからビルドして実行する

# Build + test the solution (integration tests self-skip when Garnet/AOAI are unreachable).
dotnet test src/GarnetMcp.slnx

# Run the server directly over stdio.
dotnet run --project src/GarnetMcp.Server

# Optional: interactive console to try store/recall/forget by hand (dev only; not part of the package).
dotnet run --project src/GarnetMcp.Demo

メモリーツールを使用する前に、Vector Sets を有効にして、ローカルの Garnet を起動してください。

garnet --enable-vector-set-preview true

注意事項

• プレビュー版の MCP SDK。 このプロジェクトでは ModelContextProtocol 2.0.0-preview.2 に固定しています。SDK の API サーフェスはプレビューリリース間で変更される可能性があります。
• Garnet Vector Sets はプレビュー版です。 Garnet を --enable-vector-set-preview を指定して起動してください。指定しない場合、メモリツールは「Vector Sets are not enabled」という明確なエラーを返します。
• マルチノードクラスターでの list_indexes。 インデックスの列挙には接続先ノードで SCAN を使用するため、セルフホストのマルチノード Garnet クラスターでは、そのノードのキーのみが返されます（結果は部分的です）。シングルノード構成やセルフホストのセットアップには影響ありません。また、store_memory／recall_memory／forget_memory は特定のキーを操作するため、どちらの構成でも影響を受けません。

ライセンス

MIT © Tara Zou