Qdrant Memory

Qdrant Memory MCP

共有本番環境へのデプロイについては、デプロイのセキュリティガイドをお読みください。MCP の権限付与とは別に、所有者専用のデータベース書き込み認証情報が必要です。Runtime 0.5.0 には宛先保護と共有 doctor が含まれますが、これらの制御はオペレーターが設定する必要があります。サポート範囲については、Owner support recordを参照してください。

1 つのメモリを複数のエージェントで共有 — オプトインの共有所有者

この配布物には、オプトイン方式の単一所有者サービスと stdio ブリッジが追加されています。利用するには Runtime 0.5.0 をインストールしてください。共有統合ガイドを参照してください。プライベートのデフォルト設定に変更はありません。ネイティブ Provider による自動共有抽出は延期されています。

WorkBuddy コネクターと DeepSeek Harness バンドルは、この stdio MCP、管理対象ランチャー、標準 Skill を再利用します。

简体中文

AI エージェント向けの、スコープが明確な永続メモリを 4 つの明示的な stdio MCP ツールで提供します。 このリポジトリは、既存の Python Runtimeを配布します。 メタデータのみを含む wheel に、Python のビジネス実装は含まれません。コンソール スクリプトは qdrant_memory.standalone:main を直接参照し、 hermes-plugin-qdrant-memory[mcp]==0.5.0 に依存します。

ソースの整合性、WorkBuddy アセット、互換性の境界については、0.2.4 リリースノートを参照してください。

バージョンを固定したインストールコマンドを使用する前に、そのバージョンが PyPI リリースページに掲載されていることを確認してください。

バージョン： MCP 配布物 0.2.4 は Runtime 0.5.0 を指定します。この Runtime は MCP Python SDK 1.x と 2.x（mcp>=1.30,<3）に対応しています。4 つのスコープ付きツールと stdio 起動引数は、どちらの SDK メジャーバージョンでも同じです。LLM を使用せずに、類似度が高い異なるテキストを明示的に 書き込む際の修正も保持されています。以下のコマンドでは、これらの正確なバージョンを使用します。リリース 成果物は、配布物の PyPI ページ および Runtime の PyPI ページから入手できます。 公開手順については、リリースチェックリストを参照してください。

Runtime、オプションの Agent Skill、 MCP 配布物のバージョンはそれぞれ独立しています。Skill は使用方法のガイドであり、 Runtime の依存関係ではありません。Hermes は、ネイティブの MemoryProvider、自動抽出、 プリフェッチを引き続き使用します。通常の MCP では、明示的に要求されたメモリ操作のみが行われます。 会話のすべてのターンが自動的に抽出されることはありません。

インストールと初期化

現在サポートされている最短のローカルセットアップについては、 Ollama クイックスタート（中文）に従ってください。 既存モデルの利用、不足しているモデルのインストール、WorkBuddy 専用 プロファイル、接続設定、最初の保存・検索チェックについて説明しています。ローカルでのこの方法では、Qdrant サーバー、 Docker、クラウドアカウント、埋め込み API キーは不要です。 この方法を直接利用する場合も、Python/uv と初回のプロファイル設定が必要です。WorkBuddy のマネージドコネクターと DSH バンドルでは、これらの依存関係を Node.js から準備できます。

Python 3.11 以降と、uv または Python 仮想環境が必要です。ストレージと埋め込みサービスを設定する必要があります。 以下の例では、Ollama を起動し、qwen3-embedding:4b を自分でインストールしてください。

オペレーターが管理するプロファイルディレクトリを作成し、その中に qdrant-memory.json を保存します。

{
  "schema_version": 1,
  "scope": {"user_id": "my-user", "agent_id": "my-agent"},
  "qdrant": {"mode": "embedded", "collection": "qdrant_memory"},
  "embedding": {
    "mode": "plugin", "provider": "ollama", "model": "qwen3-embedding:4b",
    "base_url": "http://127.0.0.1:11434", "dimensions": 2560, "distance": "Cosine"
  }
}

初期化してから起動します（/path/to/profile を絶対パスに置き換えてください）。

uvx --from qdrant-memory-mcp==0.2.4 qdrant-memory-mcp --home /path/to/profile init
uvx --from qdrant-memory-mcp==0.2.4 qdrant-memory-mcp --home /path/to/profile mcp

--home を指定しないコマンドは、Hermes とは別に ~/.qdrant-memory を使用します。 Registry クライアントから uvx --from qdrant-memory-mcp==0.2.4 qdrant-memory-mcp mcp を起動させる前に、 そのディレクトリを設定して初期化してください。 実行ファイル名はパッケージ名と一致します。 Registry の位置引数 mcp はプロトコルモードを選択します。クライアントがカスタムプロファイルを指定する場合、 任意の名前付き引数 --home は mcp より前に置きます。

または、次のようにします。

python3 -m venv .venv
.venv/bin/python -m pip install qdrant-memory-mcp==0.2.4
.venv/bin/qdrant-memory-mcp --home /path/to/profile init
.venv/bin/qdrant-memory-mcp --home /path/to/profile mcp

Windows では .venv\Scripts\python.exe と .venv\Scripts\qdrant-memory-mcp.exe を使用してください。

Qdrant の組み込み型、セルフホスト型サーバー、Cloud、および Ollama と OpenAI 互換の 埋め込みは、Runtime の設定リファレンスで設定します。 認証情報はオペレーターの環境変数（QDRANT_API_KEY、 EMBEDDING_API_KEY、または設定した名前）に保持してください。値をコミットしないでください。 既存のコレクションを対象に初期化するには、オペレーターによる明示的な選択が必要です。 最初のテストには本番環境の接続先を使用しないでください。

クライアントを接続する

Codex の config.toml の例：

[mcp_servers.qdrant_memory]
command = "uvx"
args = ["--from", "qdrant-memory-mcp==0.2.4", "qdrant-memory-mcp", "--home", "/path/to/profile", "mcp"]

OpenCode の opencode.json の例：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "qdrant_memory": {
      "type": "local",
      "command": ["uvx", "--from", "qdrant-memory-mcp==0.2.4", "qdrant-memory-mcp", "--home", "/path/to/profile", "mcp"],
      "enabled": true
    }
  }
}

Pi では、別途インストールした MCP クライアント／拡張機能が必要です。その拡張機能では、 command: uvx と同じ引数リストを使用してください。Pi に組み込みの MCP サポートがあることや、共通の 拡張機能設定形式があることは保証していません。これらは設定例です。この 配布物の受け入れテストでは、実際のエージェントアプリケーションではなく、公式の Python MCP SDK を使用しています。Runtime のクライアントに関する根拠と制限を参照してください。

ツールと境界

ツール	入力	結果
qdrant_memory_search	query、任意の category	ID、スコア、来歴情報を含むスコープ内のメモリー
qdrant_memory_add	text	永続メモリー ID
qdrant_memory_update	正確な id、置換後の text	スコープ内での置換
qdrant_memory_delete	正確な id	スコープ内での削除

スコープはオペレーターのプロファイル（user_id、agent_id）によって固定されます。モデル入力や MCP クライアントの ID でこれを上書きすることはできません。ID を知っていてもアクセス権は得られません。 移行、エクスポート、リセット、一括削除は、引き続き信頼されたオペレーターの CLI コマンドで行います。 スタンドアロンでのメンテナンスを参照してください。 リソースやプロンプトは公開されません。これはローカルのサブプロセスであり、 公開 HTTP/SSE リスナーやリモート認証サービスはありません。標準出力はプロトコルメッセージ用に確保され、 サニタイズされた診断情報は標準エラー出力に送られます。

データはクライアント → Runtime → 埋め込みプロバイダー → Qdrant およびローカルの SQLite 台帳へと流れます。ローカルの Ollama と組み込み Qdrant を使用する場合、メモリー処理はローカルに留まります。 クラウドの埋め込みプロバイダーにはメモリー／クエリのテキストが送られ、クラウドの Qdrant には ベクトルと保存済みペイロードが送られます。クライアント／モデルにも、呼び出されたテキストが送られる場合があります。 オペレーターは保持とアクセスを許可し、プロファイルファイルを保護する必要があります。

1 つのライターロックがプロファイル／保存先を調整します。書き込みを行う MCP、CLI、 Hermes プロセスを同時に実行しないでください。プロファイルやマシンを分けても、分散ロックにはなりません。 このパッケージは、調整されていないマルチプロセス書き込み、自動抽出、HTTP トランスポート、 Hermes からの暗黙的な認証情報の検出には対応していません。Runtime の台帳、ID、復旧セマンティクスを 維持します。

検証と開発

CI は wheel/sdist をビルドし、メタデータと所有権マーカーを確認します。Linux/macOS/Windows、 Python 3.11 と 3.14 で、一時プロファイル、組み込み Qdrant、決定論的なループバック埋め込みフィクスチャを 使用した、インストール済みプロトコルのテストを実行します。個人用の Qdrant、Hermes プロファイル、 メモリーデータに接続するテストはありません。これらのテストでは、初期化、検出、4 つのツール、 永続化、復旧、スコープ分離、エラーの秘匿、プロトコルの標準出力を検証します。プロバイダー／クラウドとの互換性を示す証拠は Runtimeに属します。

CI は不変の Runtime PyPI リリースを優先します。Runtime のリリースが PyPI に公開される前は、 CI は runtime-source.json に記録された不変のリビジョンから wheel をビルドします。これは準備用フィクスチャにすぎません。 公開される依存関係メタデータには、常に正確な PyPI バージョンが指定されます。リリースワークフローの承認には PyPI からのインストールが必須であり、このフォールバックは使用されません。

CI と依存関係のメンテナンス、公開、アーキテクチャ、および 任意の Skillを参照してください。

WorkBuddy と DeepSeek Harness

明示的な永続メモリーを使用するには、WorkBuddy コネクターまたは DSH インストールガイドを使用してください。 どちらも Python Runtime、4 つの MCP ツール、正式な Skill を再利用します。公開されている管理型ランチャーは、Node.js を使用してプライベートな Python と CPU モデルの依存関係を準備します。そのため、管理型の方法ではシステムの Python、uvx、Ollama のインストールは必要ありません。 DSH Bundle は @cnkang/qdrant-memory-dsh-bundle として配布されます。既存の Hermes プロファイルと デフォルト設定は変更されません。アーキテクチャとバージョンマトリックス および検証の制限を参照してください。