BlueOcean Vector

Gemeinsamer, beständiger Speicher für Codierungsagenten.

Die Art von Speicher, die überlebt, wenn man mitten im Projekt von Claude Code zu Codex zu Cursor wechselt — und überlebt, wenn einem in einem davon die Tokens ausgehen.

Wenn du jemals einen Kontextfenster durchgebrannt hast, ein anderes Tool geöffnet hast und dann zehn Minuten damit verbracht hast, noch einmal zu erklären, was du getan hast, dann ist das hier für dieses Problem. BlueOcean Vector betreibt einen kleinen Server auf deinem Rechner. Jeder MCP-fähige Agent kann daraus lesen und hineinschreiben. Egal, welches Tool du als nächstes öffnest, es fragt einfach: "Was wissen wir über dieses Projekt?" und macht dort weiter, wo das letzte aufgehört hat.

[!TIP] Speichere eine Entscheidung in Claude Code → öffne morgen Codex → es weiß bereits, warum du Postgres DynamoDB vorgezogen hast, nicht nur, dass du es getan hast.

Inhaltsverzeichnis

• Warum es existiert

• Wie es sich vergleicht

• Wie es zusammenhängt

• Erste Schritte

  • Agenten beibringen, es tatsächlich zu nutzen

  • Alternative: stdio

• Die Tools, die ein Agent erhält

• Konfiguration

• Admin-CLI

• Ausführen der Tests

• Sicherheit

• Bereitstellung über localhost hinaus

• Fallstricke

• Lizenz

Related MCP server: AIVectorMemory

Warum es existiert

Jede Agentensitzung beginnt bei Null. Du erklärst das Projekt, die Einschränkungen, das "das haben wir schon versucht, es hat nicht funktioniert" — und dann endet die Sitzung und alles ist weg. Multipliziere das mit jedem Tool, das du verwendest, und du gibst echte Tokens nur dafür aus, Kontext wiederherzustellen, der vor einer Stunde noch existiert hat.

BlueOcean Vector ist eine kleine, langweilige Lösung: ein gemeinsamer Speicher, eine URL und ein gemeinsamer Satz von Tools (memory_store, memory_search, memory_summarize_session und ein paar mehr), die jeder MCP-Client aufrufen kann. Es versucht nicht, klug zu entscheiden, was erinnert werden soll — es gibt Agenten einfach einen Ort, an dem sie Dinge ablegen und wieder abholen können, begrenzt auf das jeweilige Projekt, damit eine Suche in einer Codebasis kein Rauschen aus einer anderen an die Oberfläche bringt.

Wie es sich vergleicht

Es gibt bereits ein gut besiedeltes Feld von "Speicher für KI-Agenten"-Projekten. Es ist fair, klar zu sagen, wo dieses hier tatsächlich steht, anstatt so zu tun, als wäre der Bereich leer.

Zwei ehrliche Erkenntnisse:

• Die Nische "MCP-nativ, funktioniert mit jedem Client" ist nicht leer — Memorix ist bereits dort, mit mehr integrierten Tools. Was hier anders ist: Die Vektorsuche ist der primäre Abrufpfad und kein Fallback oder etwas, das hinter einer Bezahlschranke steckt; das Standard-Embedding-Modell ist wirklich mehrsprachig (Thailändisch+Englisch getestet); und es ist als ein gemeinsamer, beständiger Server gebaut und nicht als ein Tool ohne Installation pro Agent — Bearer-Token-Authentifizierung, ein dokumentierter Pfad zu ECS, Kubernetes-fähige Health-Probes und echte Lösungen für die Nebenläufigkeitsprobleme, auf die ein gemeinsamer Server tatsächlich stößt.

• Keine automatische Extraktion oder Konsolidierung — im Gegensatz zu mem0, Graphiti, Letta, cognee oder LangMem liest hier nichts deine Unterhaltung und entscheidet, was es wert ist, erinnert zu werden. Das ist ein bewusster Einfachheits-Kompromiss, kein fehlendes Feature: Ein Agent muss explizit memory_store aufrufen. Wenn du ein System möchtest, das selbstständig darüber nachdenkt, was für dich behalten werden soll, wird eines der oben genannten Projekte das besser können als dieses hier.

Speicher sollte nicht versuchen, eine Million Zeilen zu speichern

Einige Projekte sind eine Million Zeilen Code. Und kein Speichersystem — BlueOcean Vector eingeschlossen — sollte versuchen, sie alle zu speichern. Code zu speichern ist die Aufgabe eines Code-Such-Tools, nicht die eines Speicher-Servers.

BlueOceans Aufgabe ist enger und nützlicher: Merke, was wichtig war, und wo du es findest. Es speichert die Entscheidungen, die Architektur, das "das haben wir versucht, es hat nicht funktioniert" — das kondensierte Wissen, das ein Agent sonst aus einer Million Zeilen wiederentdecken müsste — plus gerade genug Kontext, um den Agenten bei Bedarf wieder auf den eigentlichen Code zu verweisen.

Das Ergebnis ist, dass der Speicher mit dem wächst, was es tatsächlich wert ist, erinnert zu werden, nicht mit der Größe der Codebasis. Ein Projekt mit einer Million Zeilen kann ein paar tausend Speichereinträge haben. Das hält den Abruf kostengünstig, egal wie groß das Projekt wird.

Die Token-Rechnung

Das Zurücklesen des Speichers ist der Punkt, an dem sich diese Unterscheidung auszahlt. Die billigste Alternative — ein Skill oder Plugin, das Projekthnotizen in eine .remember-Datei schreibt, die ein Agent zurückliest — funktioniert hervorragend, bis die Datei größer als das Kontextfenster wird; dann hört sie leise auf, nützlich zu sein.

BlueOcean begrenzt jede Suche auf ein Token-Budget (Standard 2000 Tokens, konfigurierbar über BLUEOCEAN_MAX_TOKENS). Die semantische Suche zieht nur die relevanten Einträge und teilt dann das Budget auf: ~60 % für kondensierte Zusammenfassungen, ~40 % für den vollständigen Inhalt der besten Treffer. Einträge, die über das Budget hinausgehen, werden abgeschnitten, niemals vollständig ausgegeben.

Eine echte Suche gegen ein kleines Demoprojekt ergab 121 Tokens für eine Zusammenfassung + einen vollständigen Eintrag — ein paar Prozent des 2000-Token-Budgets, und dieses Budget wächst nie, während das Projekt Speicher ansammelt. Bei einer einfachen Datei kostet derselbe Lesevorgang jedes Mal die gesamte Datei, sodass ein Projekt mit 5k Einträgen (Hunderttausende von Tokens) auf einen Schlag nicht lesbar ist.

Wie es zusammenhängt

┌────────────┐ ┌──────┐ ┌────────┐ ┌───────────────┐ ┌──────┐
│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
                 └───────────────────────────┘

Ein paar Designentscheidungen, die es wert sind, bekannt zu sein:

Der stdio-Transport funktioniert auch, wenn du bevorzugst, dass jedes Tool seinen eigenen lokalen Prozess startet, anstatt mit dem gemeinsamen Server zu kommunizieren — siehe Alternative: stdio unten. Der gemeinsame HTTP-Server ist weiterhin der empfohlene Pfad; stdio startet eine separate Kopie des Embedding-Modells pro Agent.

Erste Schritte

# 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

Das war's. setup_local.sh startet beide Container, wartet darauf, dass Qdrant tatsächlich antwortet (nicht nur "der Prozess wurde gestartet"), kopiert .env.example beim ersten Start nach .env und synchronisiert das Python-Paket. register_mcp.sh ruft dann die mcp add-CLI jedes Tools auf (oder bearbeitet für Cursor direkt ~/.cursor/mcp.json, da Curoris CLI nur bei geöffneter App funktioniert), um es auf http://localhost:8765/mcp zu verweisen.

Für jedes andere MCP-http-fähige Tool, auch für uns unbekannte, gib einfach dieselbe URL über die eigene Funktion "Remote-MCP-Server hinzufügen" des Tools an:

http://localhost:8765/mcp

Agenten beibringen, es tatsächlich zu nutzen

Die Registrierung des Servers macht die Tools verfügbar; es bringt einen Agenten nicht dazu, sie von selbst zu verwenden. scripts/install_skill.sh installiert einen kleinen Skill — "Überprüfe den Speicher zu Beginn einer Sitzung, schreibe hinein, bevor der Kontext knapp wird" — in die von dir verwendeten Agenten, sodass die Gewohnheit da ist, ohne dass du sie in jeder Eingabeaufforderung wiederholen musst:

./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

Es ist eine einzige kanonische SKILL.md, die in das eigene Skills-Verzeichnis jedes Tools symbolisch verlinkt wird — bearbeite sie einmal, jedes Tool übernimmt die Änderung.

Alternative: stdio (pro Agent lokaler Prozess)

Kein Docker verfügbar, oder du möchtest lieber keinen gemeinsamen Server betreiben? Führe aus:

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

und verweise die MCP-Konfiguration des Tools auf den command (siehe .venv/bin/blueocean-mcp) anstelle einer url.

Die Tools, die ein Agent erhält

Ein sinnvoller Agenten-Workflow: Rufe zu Beginn einer Sitzung memory_manifest und dann memory_search auf, um Kontext günstig zu laden; speichere echte Entscheidungen während der Arbeit (Wichtigkeit 5 für „Warum wir X statt Y gewählt haben“, Wichtigkeit 3 für Routine-Status); rufe memory_summarize_session auf, bevor du das Werkzeug wechselst oder das Budget knapp wird.

Konfiguration

Alles befindet sich in .env (kopiere .env.example als Startpunkt). Die Standardeinstellungen funktionieren für die lokale Nutzung auf einem einzelnen Rechner; die interessanten Stellschrauben sind:

• BLUEOCEAN_EMBEDDING – fastembed (Standard, lokal und kostenlos), openai oder bedrock. Lege auch BLUEOCEAN_EMBED_MODEL fest: Vektoren, die mit einem Modell geschrieben wurden, können mit einem anderen nicht sinnvoll durchsucht werden, daher müssen lokal und in der Cloud dasselbe Modell verwenden.

• BLUEOCEAN_QDRANT_URL – wo Qdrant läuft.

• BLUEOCEAN_MAX_TOKENS / BLUEOCEAN_TOP_K – das standardmäßige Suchbudget.

• BLUEOCEAN_AUTH_TOKEN – standardmäßig nicht gesetzt (in Ordnung für reine 127.0.0.1-Nutzung). Siehe Sicherheit, wenn du dies über deinen eigenen Rechner hinaus verfügbar machst.

Transport (streamable-http vs stdio) ist ein CLI-Flag, keine Umgebungsvariable – es ist eine Entscheidung „Wie führe ich das aus?“, die beim Start getroffen wird, keine dauerhafte Einstellung.

Admin-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] Wenn mehr als eine Agentensitzung ein Projekt gemeinsam nutzt, weiß prune das nicht. Es löscht alles, was deinen Filtern entspricht, auch Einträge, die eine andere Sitzung vor fünf Minuten geschrieben hat. Führe zuerst --dry-run aus und bevorzuge enge Filter gegenüber einem breiten Zurücksetzen.

export gibt nur die Nutzdaten als JSON aus (with_vectors=False) – die Wiederherstellung daraus bedeutet, alles von Grund auf neu einzubetten, keine echte Point-in-Time-Wiederherstellung. snapshot/restore verwenden stattdessen Qdrants eigenen nativen Snapshot-Mechanismus: Vektoren, Nutzdaten und Indexzustand, atomar erfasst. snapshot lädt die Datei auf die lokale Festplatte herunter und löscht die serverseitige Kopie, sobald der Download als intakt bestätigt wurde (Backups, die nur innerhalb desselben Qdrant-Volumes leben, das sie sichern, sind keine Backups). restore überschreibt die aktuellen Daten des Projekts, daher ist --yes erforderlich.

Projektnamen werden streng validiert (^[a-z0-9][a-z0-9_-]*$, entsprechend der von diesem Projekt bereits empfohlenen Verzeichnisnamen-Konvention) anstatt stillschweigend normalisiert – zwei Agenten, die leicht unterschiedliche Schreibweisen desselben Projekts erraten ("Team A" vs "team-a"), führten früher ohne Warnung zu einer Zusammenführung in eine Sammlung; jetzt wird der abweichende Name stattdessen abgelehnt.

Tests ausführen

Testdateien unter tests/ sind eigenständige Skripte (if __name__ == "__main__":), keine von pytest erkannten Dateien – führe sie als Module aus:

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 prüft speziell, dass nicht authentifizierte und Anfragen mit falschem Token abgelehnt werden (401) und dass ein korrekter Token sowohl über den Header als auch über den ?token=-Query-Param-Pfad funktioniert.

Sicherheit

Standardmäßig keine Authentifizierung – sinnvoll für reine 127.0.0.1-Nutzung, nicht sinnvoll, sobald dies von irgendwo anders erreichbar ist.

[!IMPORTANT] Wenn du diesen Server über localhost hinaus verfügbar machst (ein gemeinsam genutzter Rechner, die Cloud), setze BLUEOCEAN_AUTH_TOKEN, bevor du irgendetwas anderes tust.

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

Nicht jedes Werkzeug kann einen benutzerdefinierten Header setzen, wenn es einen entfernten Server per URL registriert, daher akzeptiert der Server den Token auf zwei Arten und jeder Client verwendet die, die er unterstützt:

• Authorization: Bearer <token> – Claude Code, Gemini/Antigravity

• ?token=<token> in der URL – Codex, Kiro, Cursor

Der stdio-Transport überspringt dies vollständig: Es handelt sich um einen lokal gestarteten Unterprozess, der bereits durch die Betriebssystem-Berechtigungen zum Starten von Prozessen geschützt ist, anstatt im Netzwerk zu sitzen.

GET /health ist bewusst nicht authentifiziert und prüft, ob Qdrant tatsächlich erreichbar ist, nicht nur, ob der Prozess läuft. Es ist das, was der Healthcheck von docker-compose.yml abfragt. Es meldet auch den aktiven Embedding-Anbieter/das aktive Modell und validiert für openai/bedrock (nicht fastembed, dessen Modell-Laden bereits den Prozessstart blockiert) die Anmeldeinformationen über einen kostenlosen Kontrollebenen-Aufruf anstelle des abgerechneten Embed-Endpunkts, wobei das Ergebnis für BLUEOCEAN_HEALTH_EMBED_TTL Sekunden (Standard 60) zwischengespeichert wird, sodass ein 10-Sekunden-Abfrageintervall nicht bei jedem Treffer zu einem Anbieter-API-Aufruf wird:

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

Setze den Token über BLUEOCEAN_AUTH_TOKEN (Umgebungsvariable / .env), nicht über das CLI-Flag --auth-token – ein als CLI-Argument übergebener Wert ist für jeden anderen lokalen Benutzer über ps sichtbar. Die Zugriffsprotokollierung ist ebenfalls standardmäßig deaktiviert (access_log=False), da drei der fünf unterstützten Clients den Token als ?token=... senden und ein einfaches Zugriffsprotokoll ihn bei jeder einzelnen Anfrage im Klartext in deinen Protokollen ablegen würde.

Über localhost hinaus bereitstellen

docker compose up -d startet zwei langlebige Dienste: qdrant (Port 6333) und blueocean-mcp (Port 8765). Für die Cloud wandern dieselben beiden Dienste zu ECS Fargate (oder Qdrant Cloud plus einem kleinen Fargate/App Runner-Dienst für blueocean-mcp) – registriere die öffentliche URL bei jedem Werkzeug genau so, wie du es lokal tun würdest. Die Dockerfile fixiert das Embedding-Modell, sodass in der Cloud erstellte Vektoren mit denen kompatibel sind, die auf deinem Laptop erstellt wurden.

Kubernetes liest den healthcheck: von docker-compose.yml nicht – es benötigt eigene Probes im Pod-Spezifikation, aber sie können auf denselben Pfad verweisen:

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

Ein paar Fallstricke, die du kennen solltest, bevor du hier Hand anlegst

• qdrant-client ist auf die exakte Version des Qdrant-Servers festgelegt (siehe das Image-Tag in docker-compose.yml). Qdrant versioniert seinen Client und Server im Gleichschritt, und die API hat sich zwischen den Versionen geändert – .search() wurde zugunsten von .query_points() in 1.19 entfernt. Wenn du das Server-Image erhöhst, erhöhe auch qdrant-client entsprechend und führe die Testsuite erneut aus; springe nicht mehrere Versionen auf echten Daten ohne vorherigen Snapshot.

• mcp ist auf >=2.0.0,<3.0.0 festgelegt, enger als die meisten Abhängigkeiten hier. Seine API (mcp.server.mcpserver.MCPServer und Verwandte) hat sich zwischen den Versionen erheblich verändert, und eine lockere Einschränkung riskiert, dass ein Docker-Build stillschweigend etwas Inkompatibles auflöst – Docker-Builds verwenden uv.lock nicht.

• Embedding-Anbieter und -Modell sind ein Paar. Wechsle eines von beiden und alte Vektoren werden zu unauffindbarem Müll gegenüber neuen. Fixiere das Modell in .env, anstatt einer Bibliotheksvoreinstellung zu vertrauen, die sich unter dir ändern könnte.

Lizenz

MIT – siehe LICENSE.