BlueOcean Vector

Shared, persistent memory for coding agents.

The kind of memory that survives switching from Claude Code to Codex to Cursor mid-project — and survives you running out of tokens in one of them.

If you've ever burned through a context window, opened a different tool, and then spent ten minutes re-explaining what you were doing, this is for that problem. BlueOcean Vector runs one small server on your machine. Any MCP-capable agent can read from it and write to it. Whichever tool you open next just asks "what do we know about this project?" and picks up where the last one left off.

Contents

• Why it exists

• How this compares

• How it fits together

• Getting started

  • Teaching agents to actually use it

  • Alternative: stdio

• The tools an agent gets

• Configuration

• Admin CLI

• Running the tests

• Security

• Deploying beyond localhost

• Gotchas

• License

Related MCP server: AIVectorMemory

Why it exists

Every agent session starts from zero. You explain the project, the constraints, the "we tried that already, it didn't work" — and then the session ends and it's gone. Multiply that by every tool you use, and you're spending real tokens just re-establishing context that already existed an hour ago.

BlueOcean Vector is a small, boring fix: one shared memory store, one URL, and a common set of tools (memory_store, memory_search, memory_summarize_session, and a few more) that any MCP client can call. It doesn't try to be clever about what to remember — it just gives agents a place to put things down and pick them back up, scoped per project so a search in one codebase doesn't surface noise from another.

How this compares

There's already a well-populated field of "memory for AI agents" projects. Worth being upfront about where this one actually sits, instead of pretending the space is empty.

Two honest takeaways:

• The "MCP-native, works with any client" niche isn't empty — Memorix already lives there, with more built-in tools. What's different here is that vector search is the primary retrieval path rather than a fallback or something gated behind a paid tier, the default embedding model is genuinely multilingual (Thai+English tested), and it's built to run as one shared, persistent server rather than a zero-install per-agent tool — bearer-token auth, a documented path to ECS, Kubernetes-ready health probes, and real fixes for the concurrency problems a shared server actually hits.

• No automatic extraction or consolidation — unlike mem0, Graphiti, Letta, cognee, or LangMem, nothing here reads your conversation and decides what's worth remembering. That's a deliberate simplicity trade-off, not a missing feature: an agent has to explicitly call memory_store. If you want a system that reasons about what to keep on your behalf, one of the projects above will do that better than this will.

Memory shouldn't try to hold a million lines

Some projects are a million lines of code. And no memory system — BlueOcean Vector included — should try to store all of it. Storing code is a code-search tool's job, not a memory server's.

BlueOcean's job is narrower and more useful: remember what mattered, and where to find it. It holds the decisions, the architecture, the "we tried that, it didn't work" — the condensed knowledge an agent would otherwise have to rediscover from a million lines — plus just enough context to point the agent back at the real code when it needs details.

The result is that memory grows with what's actually worth remembering, not with the size of the codebase. A million-line project can have a few thousand memory entries. That keeps retrieval cheap no matter how big the project gets.

The token math

Reading memory back is where that distinction pays off. The cheapest alternative — a skill or plugin that dumps project notes into a .remember file an agent reads back — works great until the file outgrows the context window, then it silently stops being useful.

BlueOcean caps every search at a token budget (default 2000 tokens, configurable via BLUEOCEAN_MAX_TOKENS). Semantic search pulls only the relevant entries, then splits the budget: ~60% for condensed summaries, ~40% for the full content of the top hits. Entries beyond the budget are truncated, never dumped wholesale.

A real search against a small demo project returned 121 tokens for one summary + one full entry — a few percent of the 2000-token budget, and that budget never grows as the project accumulates memory. With a plain file, the same read costs the entire file every time, so a 5k-entry project (hundreds of thousands of tokens) is unreadable in one shot.

How it fits together

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

A few design choices worth knowing about:

stdio transport also works if you'd rather each tool spawn its own local process instead of talking to the shared server — see Alternative: stdio below. The shared HTTP server is still the recommended path; stdio spins up a separate copy of the embedding model per agent.

Getting started

# 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

That's it. setup_local.sh starts both containers, waits for Qdrant to actually respond (not just "the process started"), copies .env.example to .env on first run, and syncs the Python package. register_mcp.sh then calls each tool's own mcp add CLI (or, for Cursor, edits ~/.cursor/mcp.json directly, since Cursor's CLI only works while the app is open) to point it at http://localhost:8765/mcp.

For any other MCP-http-capable tool, including ones we've never heard of, just give it the same URL through that tool's own "add remote MCP server" feature:

http://localhost:8765/mcp

Teaching agents to actually use it

Registering the server gets the tools available; it doesn't make an agent reach for them on its own. scripts/install_skill.sh installs a small skill — "check memory at the start of a session, write to it before you run low on context" — into whichever agents you use, so the habit is there without you repeating it in every prompt:

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

It's one canonical SKILL.md, symlinked into each tool's own skills directory — edit it once, every tool picks up the change.

Alternative: stdio (per-agent local process)

No Docker available, or you'd rather not run a shared server? Run:

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

and point the tool's MCP config at the command (see .venv/bin/blueocean-mcp) instead of a url.

The tools an agent gets

A reasonable agent workflow: call memory_manifest then memory_search at the start of a session to load context cheaply; memory_store real decisions as you go (importance 5 for "why we chose X over Y", importance 3 for routine status); call memory_summarize_session before switching tools or running low on budget.

Configuration

Everything lives in .env (copy .env.example to start). The defaults work for local, single-machine use; the interesting knobs are:

• BLUEOCEAN_EMBEDDING — fastembed (default, local and free), openai, or bedrock. Pin BLUEOCEAN_EMBED_MODEL too: vectors written with one model can't be meaningfully searched with another, so local and cloud need to agree on it.

• BLUEOCEAN_QDRANT_URL — where Qdrant lives.

• BLUEOCEAN_MAX_TOKENS / BLUEOCEAN_TOP_K — the default search budget.

• BLUEOCEAN_AUTH_TOKEN — unset by default (fine for 127.0.0.1-only use). See Security if you're exposing this beyond your own machine.

Transport (streamable-http vs stdio) is a CLI flag, not an env var — it's a "how do I run this" choice made at startup, not a persistent setting.

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

export only dumps payload as JSON (with_vectors=False) — restoring from it means re-embedding everything from scratch, not a real point-in-time restore. snapshot/restore use Qdrant's own native snapshot mechanism instead: vectors, payload, and index state, captured atomically. snapshot downloads the file to local disk and deletes the server-side copy once the download is confirmed intact (backups living only inside the same Qdrant volume they're backing up out of aren't backups). restore overwrites the project's current data, so it requires --yes.

Project names are validated strictly (^[a-z0-9][a-z0-9_-]*$, matching the directory-name convention this project already recommends) rather than silently normalized — two agents guessing slightly different spellings of the same project ("Team A" vs "team-a") used to merge into one collection with no warning; now the mismatched one is rejected instead.

Running the tests

Test files under tests/ are standalone scripts (if __name__ == "__main__":), not pytest-discovered files — run them as modules:

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 specifically checks that unauthenticated and wrong-token requests get rejected (401) and that a correct token works via both the header and the ?token= query-param path.

Security

No auth by default — reasonable for 127.0.0.1-only local use, not reasonable the moment this is reachable from anywhere else.

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

Not every tool can set a custom header when registering a remote server by URL, so the server accepts the token two ways and each client uses whichever it supports:

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

• ?token=<token> on the URL — Codex, Kiro, Cursor

stdio transport skips this entirely: it's a locally spawned subprocess, already gated by OS process-spawn permissions rather than sitting on the network.

GET /health is deliberately unauthenticated and checks that Qdrant is actually reachable, not just that the process is alive. It's what docker-compose.yml's healthcheck polls. It also reports the active embedding provider/model, and for openai/bedrock (not fastembed, whose model load already gates process startup) validates credentials via a free control-plane call rather than the billed embed endpoint, caching the result for BLUEOCEAN_HEALTH_EMBED_TTL seconds (default 60) so a 10s probe interval doesn't turn into a provider API call on every hit:

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

Set the token via BLUEOCEAN_AUTH_TOKEN (env var / .env), not the --auth-token CLI flag — a value passed as a CLI argument is visible to any other local user via ps. Request access logging is also off by default (access_log=False), since three of the five supported clients send the token as ?token=... and a plain access log would put it in plaintext in your logs on every single request.

Deploying beyond localhost

docker compose up -d runs two long-lived services: qdrant (port 6333) and blueocean-mcp (port 8765). For the cloud, the same two services move to ECS Fargate (or Qdrant Cloud plus a small Fargate/App Runner service for blueocean-mcp) — register the public URL with each tool exactly the way you would locally. The Dockerfile pins the embedding model so vectors produced in the cloud are compatible with ones produced on your laptop.

Kubernetes doesn't read docker-compose.yml's healthcheck: — it needs its own probes in the Pod spec, but they can point at the same path:

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

A few gotchas worth knowing before you touch this

• qdrant-client is pinned to the Qdrant server's exact version (see the image tag in docker-compose.yml). Qdrant versions its client and server in lockstep, and the API has changed between releases — .search() was removed in favor of .query_points() in 1.19. If you bump the server image, bump qdrant-client to match and re-run the test suite; don't jump several versions on real data without a snapshot first.

• mcp is pinned >=2.0.0,<3.0.0, tighter than most dependencies here. Its API (mcp.server.mcpserver.MCPServer and friends) has changed shape significantly between releases, and a loose constraint risks a Docker build silently resolving something incompatible — Docker builds don't use uv.lock.

• Embedding provider and model are a matched pair. Switch either one and old vectors become unsearchable garbage against new ones. Pin the model in .env rather than trusting a library default that might change out from under you.

License

MIT — see LICENSE.