vectorsearch

vectorsearch

vectorsearch はエージェント向けの小さなメモリーです。情報を保存しておき、後から自然言語のクエリで呼び出せます。操作は保存と検索の2つだけで、REST API 経由で Qdrant ベクトルデータベースを利用します。

デフォルト以外のサービスに接続するには、QDRANT_URL を設定します（デフォルトは http://localhost:6333 です）。呼び出しでコレクションが指定されていない場合に使われるコレクションは、COLLECTION_NAME から取得し、デフォルトは documents です。 まだ存在しないコレクションに保存すると、このツールの埋め込み次元数とコサイン距離を使って、まずコレクションが作成されます。

インストール

npx @reneturcios/vectorsearch find "how do we deploy the staging app"

または、コンテナーイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/vectorsearch

コンテナーはデフォルトで MCP サーバーを起動します（下記を参照）。CLI として使うには、CLI 引数を渡してください。

CLI

# Store something (optionally into a named collection)
vectorsearch store "the staging deploy runs from the release branch" --collection notes

# Ask for it back
vectorsearch find "staging deploy" --collection notes

# Start the MCP server
vectorsearch mcp

vectorsearch --version

終了コード：成功時は 0、サービス呼び出し失敗時（エラーには HTTP ステータスが含まれます）は 1、使用方法に関するエラー時は 2 です。

MCP サーバー

1つのバイナリで両方の用途に対応します。mcp サブコマンドは stdio MCP サーバーを起動します。

npx -y @reneturcios/vectorsearch mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "vectorsearch": {
      "command": "npx",
      "args": ["-y", "@reneturcios/vectorsearch", "mcp"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "COLLECTION_NAME": "documents"
      }
    }
  }
}

ツール

ツール	必須	任意	目的
qdrant-store	information (string)	metadata (object), collection_name (string)	Qdrant データベースに情報を保存します。テキストとメタデータはすべてポイントのペイロードになります。
qdrant-find	query (string)	collection_name (string)	Qdrant データベースから関連情報を取得します。保存されたエントリーのうち、最も近いものをペイロードとスコアとともに返します。

埋め込みについて

リファレンス設計では、Qdrant と外部の埋め込みモデルを組み合わせています。 この再構築版では、外部の埋め込みサービスを一切呼び出しません。 代わりに、決定論的なハッシュベースの関数を使ってテキストをローカルで埋め込みます。同じテキストからは常に同じ単位ベクトルが生成され、トークンを共有するテキストは互いに近い位置になるため、保存と検索の一貫性が保たれ、完全にオフラインで動作します。このトレードオフには留意してください。これはトークンの重なりに基づく類似度を使うローカルのフォールバックであり、モデル品質のセマンティック埋め込みではありません。後から実際の埋め込みプロバイダーに切り替える場合も、変更するのはエグゼキューターのベクトル関数だけです。ツール、スキーマ、ストレージの形式はそのままです。

ポイント ID も同様に決定論的で、テキスト（および存在する場合はメタデータ）のハッシュから導出されます。そのため、同じ情報を再保存すると重複が積み重なるのではなく、同じポイントが更新されます。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fakes only, no live service
npm run dev     # run the CLI from source via tsx

ディスパッチ、デフォルトコレクションの解決、エラーの伝播は、フェイクエグゼキューターを使ってテストします。Qdrant REST エグゼキューターは、リクエストを記録するフェイクの fetch を使ってテストします（コレクションの確認／未作成時の作成、ポイントのアップサート形式、検索結果のマッピング）。

ライセンス

MIT — LICENSE を参照してください。