BlueOcean Vector

共有・永続的なメモリを提供するコーディングエージェント向けツール。

Claude CodeからCodex、Cursorへとプロジェクトの途中で切り替えても、あるいはそのうちの一つのツールでトークンを使い果たしても、メモリは生き続けます。

コンテキストウィンドウを使い切り、別のツールを開き、自分が何をしていたかを再度説明するために10分を費やした経験があるなら、このツールはその問題を解決します。BlueOcean Vectorは、あなたのマシン上で1つの小さなサーバーを実行します。MCPに対応したエージェントなら誰でも、そのサーバーに対して読み書きできます。次に開くツールは「このプロジェクトについて何を知っている？」と尋ね、前回の続きから作業を再開します。

[!TIP] Claude Codeで決定を保存 → 翌日Codexを開く → すでに「なぜPostgresをDynamoDBではなく選んだのか」、その理由だけでなく、そう決めた経緯も理解している。

目次

• なぜ存在するのか

• 比較

• 全体の構成

• はじめに

  • エージェントに実際に使わせるには

  • 代替方法：stdio

• エージェントが利用できるツール

• 設定

• 管理CLI

• テストの実行

• セキュリティ

• localhostを超えたデプロイ

• 注意点

• ライセンス

Related MCP server: AIVectorMemory

なぜ存在するのか

どのエージェントセッションもゼロから始まります。プロジェクト、制約、「それはもう試したがうまくいかなかった」という事実を説明し、そしてセッションが終了するとすべてが消えます。使用するツールごとにそれが繰り返され、1時間前にすでに存在していたコンテキストを再構築するためだけに、実際のトークンを浪費していることになります。

BlueOcean Vectorは、小さくて地味な修正策です。1つの共有メモリストア、1つのURL、そしてどのMCPクライアントでも呼び出せる共通のツールセット（memory_store、memory_search、memory_summarize_sessionなど）を提供します。何を記憶するべきかを賢く判断しようとはしません。単にエージェントが情報を置き、後で取り出せる場所を提供するだけです。プロジェクトごとにスコープが設定されているため、あるコードベースの検索が別のコードベースのノイズを拾い上げることはありません。

比較

「AIエージェント向けメモリ」プロジェクトの分野はすでに豊富です。このプロジェクトが実際にどの位置にあるのかを正直に示す価値があります。

2つの正直な結論：

• 「MCPネイティブで、どのクライアントでも動作する」というニッチは空いていない — Memorixがすでにそこに存在し、より多くの組み込みツールを備えています。ここでの違いは、ベクトル検索がフォールバックや有料層の背後に隠れるのではなく、主要な検索経路であること、デフォルトの埋め込みモデルが真に多言語対応（タイ語+英語でテスト済み）であること、そして1つの共有・永続的なサーバーとして動作するように設計されていることです。ベアラートークン認証、ECSへのドキュメント化されたパス、Kubernetes対応のヘルスプローブ、そして共有サーバーが実際に直面する同時実行性の問題に対する真の修正が含まれています。

• 自動抽出や統合は行わない — mem0、Graphiti、Letta、cognee、LangMemとは異なり、会話を読み取って何を記憶する価値があるかを判断する機能はありません。これは意図的なシンプルさのトレードオフであり、欠落している機能ではありません。エージェントは明示的にmemory_storeを呼び出す必要があります。もしあなたの代わりに何を保持すべきかを判断するシステムが必要なら、上記のプロジェクトの方が適しています。

メモリが100万行を保持しようとすべきではない

あるプロジェクトは100万行のコードです。そして、BlueOcean Vectorを含め、どのメモリシステムもそのすべてを保存しようとすべきではありません。コードを保存するのはコード検索ツールの仕事であり、メモリサーバーの仕事ではありません。

BlueOceanの役割はもっと狭く、より有用です。重要なことと、それがどこにあるかを記憶すること。 決定事項、アーキテクチャ、「試したがうまくいかなかった」という情報 — エージェントが100万行から再発見しなければならない凝縮された知識 — そして、詳細が必要なときにエージェントを実際のコードに戻すための十分なコンテキストを保持します。

その結果、メモリはコードベースのサイズではなく、実際に記憶する価値があるものに応じて増加します。100万行のプロジェクトでも、数千のメモリエントリで済みます。そのため、プロジェクトがどれだけ大きくても、検索は低コストに保たれます。

トークンの計算

メモリを読み戻す際に、その違いが顕著になります。最も安価な代替手段 — プロジェクトメモをエージェントが読み戻す.rememberファイルにダンプするスキルやプラグイン — は、ファイルがコンテキストウィンドウを超えるまではうまく機能しますが、それを超えると静かに役に立たなくなります。

BlueOceanは、すべての検索にトークンバジェット（デフォルト2000トークン、BLUEOCEAN_MAX_TOKENSで設定可能）を設定します。セマンティック検索は関連するエントリのみを引き出し、バジェットを分割します：約60%を凝縮された要約に、約40%をトップヒットの完全な内容に割り当てます。バジェットを超えるエントリは切り詰められ、丸ごとダンプされることはありません。

実際の小規模デモプロジェクトに対する検索では、1つの要約と1つの完全なエントリに対して121トークンが返されました。これは2000トークンのバジェットの数パーセントに過ぎず、そのバジェットはプロジェクトがメモリを蓄積しても決して増加しません。プレーンファイルの場合、同じ読み取りには毎回ファイル全体のコストがかかるため、5,000エントリのプロジェクト（数十万トークン）は一度に読み取れません。

全体の構成

┌────────────┐ ┌──────┐ ┌────────┐ ┌───────────────┐ ┌──────┐
│Claude Code │ │Cursor│ │ Codex  │ │Gemini/Antigrav│ │ Kiro │  ...any MCP-http tool
└─────┬──────┘ └──┬───┘ └───┬────┘ └───────┬───────┘ └──┬───┘
      └───────────┴─────────┴──────────────┴────────────┘
                            │  http://localhost:8765/mcp
                 ┌───────────────────────────┐
                 │  blueocean-mcp             │   Python MCP server
                 │  (one shared, persistent   │   (docker compose)
                 │  server, not per-agent)    │
                 └─────────────┬─────────────┘
                               │
                 ┌───────────────────────────┐
                 │  Qdrant (vector DB)        │   Docker locally → ECS Fargate in the cloud
                 └───────────────────────────┘

知っておく価値のあるいくつかの設計上の選択：

stdioトランスポートも利用可能で、各ツールが共有サーバーと通信する代わりに、独自のローカルプロセスを起動することもできます。詳細は下記の代替方法：stdioを参照してください。共有HTTPサーバーが推奨される方法です。stdioはエージェントごとに別々の埋め込みモデルのコピーを起動します。

はじめに

# 1. Bring up Qdrant + the MCP server (both run in the background via docker compose)
./scripts/setup_local.sh

# 2. Register the URL with whichever agents you use
./scripts/register_mcp.sh

以上です。setup_local.shは両方のコンテナを起動し、Qdrantが実際に応答するまで待機し（「プロセスが起動した」だけではありません）、初回実行時に.env.exampleを.envにコピーし、Pythonパッケージを同期します。次にregister_mcp.shが各ツールの独自のmcp addCLIを呼び出すか（Cursorの場合は、CursorのCLIはアプリが開いている間しか動作しないため、~/.cursor/mcp.jsonを直接編集します）、http://localhost:8765/mcpを指すように設定します。

その他のMCP-http対応ツール（私たちが聞いたことのないものも含む）については、そのツールの「リモートMCPサーバーを追加」機能を使って同じURLを指定してください：

http://localhost:8765/mcp

エージェントに実際に使わせるには

サーバーを登録するとツールが利用可能になりますが、エージェントが自らそれを使うわけではありません。scripts/install_skill.shは、小さなスキルをインストールします — 「セッション開始時にメモリを確認し、コンテキストが不足する前に書き込む」 — これを使用するエージェントにインストールすることで、毎回プロンプトで指示しなくても習慣が身につきます：

./scripts/install_skill.sh          # interactive picker
./scripts/install_skill.sh all      # install into every supported tool found
./scripts/install_skill.sh --list   # see what's installed where

これは1つの正規のSKILL.mdであり、各ツールのスキルディレクトリにシンボリックリンクされます。一度編集すれば、すべてのツールに変更が反映されます。

代替方法：stdio（エージェントごとのローカルプロセス）

Dockerが利用できない、または共有サーバーを実行したくない場合は、次のコマンドを実行します：

uv run blueocean-mcp --transport stdio --qdrant-url http://localhost:6333

そして、ツールのMCP設定でurlの代わりにcommand（.venv/bin/blueocean-mcpを参照）を指定します。

エージェントが利用できるツール

合理的なエージェントのワークフロー：セッション開始時に memory_manifest を呼び出し、次に memory_search でコンテキストを安価に読み込む。作業中に実際の判断を memory_store に保存する（重要度5：「XよりYを選んだ理由」、重要度3：定常的なステータス）。ツールを切り替える前や予算が少なくなったら memory_summarize_session を呼び出す。

設定

すべて .env に記述します（.env.example をコピーして開始）。デフォルトはローカル、単一マシンでの使用に適しています。主な調整項目は以下の通りです：

• BLUEOCEAN_EMBEDDING — fastembed（デフォルト、ローカルで無料）、openai、または bedrock。BLUEOCEAN_EMBED_MODEL も固定してください。あるモデルで書き込まれたベクトルは別のモデルでは意味のある検索ができないため、ローカルとクラウドでモデルを一致させる必要があります。

• BLUEOCEAN_QDRANT_URL — Qdrant の場所。

• BLUEOCEAN_MAX_TOKENS / BLUEOCEAN_TOP_K — デフォルトの検索予算。

• BLUEOCEAN_AUTH_TOKEN — デフォルトでは未設定（127.0.0.1 のみの使用では問題ありません）。このサーバーを自分のマシン以外に公開する場合は、セキュリティ を参照してください。

トランスポート（streamable-http と stdio）は環境変数ではなく CLI フラグです。これは「どう実行するか」という起動時の選択であり、永続的な設定ではありません。

管理 CLI

uv run blueocean-admin stats <project>
uv run blueocean-admin manifest <project>
uv run blueocean-admin list
uv run blueocean-admin export <project>
uv run blueocean-admin prune <project> --older-days 90 --max-importance 2 [--dry-run]
uv run blueocean-admin snapshot <project> [--out ./backups]
uv run blueocean-admin restore <project> <snapshot-file> --yes
uv run blueocean-admin generate-token --write-env

[!WARNING] 複数のエージェントセッションが同じプロジェクトを共有している場合、prune はそれを認識しません。フィルタに一致するエントリを、別のセッションが5分前に書き込んだものでも削除します。最初に --dry-run を実行し、広範なリセットよりも狭いフィルタを優先してください。

export はペイロードのみを JSON としてダンプします（with_vectors=False）。そこから復元するにはすべてを最初から再埋め込みする必要があり、真のポイントインタイムリストアではありません。snapshot/restore は代わりに Qdrant のネイティブスナップショットメカニズムを使用します。ベクトル、ペイロード、インデックス状態をアトミックにキャプチャします。snapshot はファイルをローカルディスクにダウンロードし、ダウンロードが完全であることが確認されたらサーバー側のコピーを削除します（バックアップ元の Qdrant ボリューム内にのみバックアップが存在するのはバックアップとは言えません）。restore はプロジェクトの現在のデータを上書きするため、--yes が必要です。

プロジェクト名は厳密に検証されます（^[a-z0-9][a-z0-9_-]*$、このプロジェクトが推奨するディレクトリ名の規則に一致）。警告なしに正規化されることはありません。2つのエージェントが同じプロジェクトの綴りをわずかに異なる形で推測した場合（"Team A" と "team-a"）、以前は警告なしに1つのコレクションにマージされていましたが、現在は不一致のものが拒否されます。

テストの実行

tests/ 以下のテストファイルはスタンドアロンスクリプトです（if __name__ == "__main__":）。pytest で検出されるファイルではありません。モジュールとして実行してください：

uv run python -m tests.smoke
uv run python -m tests.auth
uv run python -m tests.mcp_e2e
uv run python -m tests.backup   # real snapshot -> delete collection -> restore cycle
uv run python -m tests.health   # /health diagnostics + the cloud-provider self-test TTL cache

tests/auth.py は特に、認証なしおよび間違ったトークンのリクエストが拒否されること（401）、正しいトークンがヘッダーと ?token= クエリパラメータの両方で機能することを確認します。

セキュリティ

デフォルトでは認証なし。127.0.0.1 のみのローカル使用では問題ありませんが、他の場所から到達可能になった瞬間に問題になります。

[!IMPORTANT] このサーバーを localhost 以外（共有マシン、クラウド）に公開する場合は、他のことをする前に BLUEOCEAN_AUTH_TOKEN を設定してください。

uv run blueocean-admin generate-token --write-env
docker compose up -d --force-recreate blueocean-mcp
./scripts/register_mcp.sh   # reads the token from .env, re-sends it to every tool

すべてのツールがリモートサーバーを URL で登録する際にカスタムヘッダーを設定できるわけではないため、サーバーは2つの方法でトークンを受け入れ、各クライアントはサポートする方を使用します：

• Authorization: Bearer <token> — Claude Code、Gemini/Antigravity

• URL に ?token=<token> — Codex、Kiro、Cursor

stdio トランスポートはこれを完全にスキップします。ローカルで生成されたサブプロセスであり、ネットワーク上に存在するのではなく、OS のプロセス生成権限によってすでにゲートされています。

GET /health は意図的に認証なしで、Qdrant が実際に到達可能かどうかを確認します（プロセスが生きているかどうかだけではありません）。docker-compose.yml のヘルスチェックがポーリングするものです。また、アクティブな埋め込みプロバイダー/モデルを報告し、openai/bedrock（fastembed ではありません。fastembed のモデルロードはプロセス起動時にすでにゲートされています）の場合は、課金される埋め込みエンドポイントではなく、無料のコントロールプレーン呼び出しで資格情報を検証し、結果を BLUEOCEAN_HEALTH_EMBED_TTL 秒（デフォルト60）キャッシュします。これにより、10秒間隔のプローブがヒットごとにプロバイダーAPI呼び出しになるのを防ぎます：

{"status": "ok", "qdrant": "reachable", "embedding": {"provider": "fastembed", "model": "intfloat/multilingual-e5-large", "ok": true}}

トークンは BLUEOCEAN_AUTH_TOKEN（環境変数 / .env）で設定し、--auth-token CLI フラグでは設定しないでください。CLI 引数として渡された値は、ps を介して他のローカルユーザーから見える可能性があります。リクエストアクセスログもデフォルトでオフです（access_log=False）。サポートされている5つのクライアントのうち3つは ?token=... としてトークンを送信するため、プレーンなアクセスログはすべてのリクエストでトークンを平文でログに記録することになります。

localhost を超えたデプロイ

docker compose up -d は2つの長期稼働サービスを起動します：qdrant（ポート6333）と blueocean-mcp（ポート8765）。クラウドの場合、同じ2つのサービスを ECS Fargate（または Qdrant Cloud と小さな Fargate/App Runner サービス blueocean-mcp）に移行します。パブリック URL を各ツールにローカルと同じ方法で登録します。Dockerfile は埋め込みモデルを固定するため、クラウドで生成されたベクトルはラップトップで生成されたものと互換性があります。

Kubernetes は docker-compose.yml の healthcheck: を読み取りません。Pod 仕様に独自のプローブが必要ですが、同じパスを指すことができます：

readinessProbe:
  httpGet: { path: /health, port: 8765 }
livenessProbe:
  httpGet: { path: /health, port: 8765 }

触る前に知っておくべきいくつかの注意点

• qdrant-client は Qdrant サーバーの正確なバージョンに固定されています（docker-compose.yml のイメージタグを参照）。Qdrant はクライアントとサーバーを連動してバージョン管理しており、API はリリース間で変更されています。.search() は 1.19 で .query_points() に置き換えられました。サーバーイメージをバンプする場合は、qdrant-client も一致するようにバンプし、テストスイートを再実行してください。実際のデータで複数バージョンを飛ばさないでください。最初にスナップショットを取ってください。

• mcp は >=2.0.0,<3.0.0 に固定されています。これはほとんどの依存関係よりも厳しい制約です。その API（mcp.server.mcpserver.MCPServer など）はリリース間で大幅に形状が変わっており、緩い制約では Docker ビルドが互換性のないものを静的に解決するリスクがあります。Docker ビルドは uv.lock を使用しません。

• 埋め込みプロバイダーとモデルはペアです。 どちらかを変更すると、古いベクトルは新しいベクトルに対して検索不可能なゴミになります。ライブラリのデフォルトに頼るのではなく、.env でモデルを固定してください。デフォルトはあなたの知らないうちに変更される可能性があります。

ライセンス

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