BlueOcean Vector

供编码代理使用的共享持久记忆。

一种能在从 Claude Code 切换到 Codex 再切换到 Cursor 的整个项目周期中存续的记忆——并且能在你用完其中某个工具的 token 时依然存活。

如果你曾经耗尽过上下文窗口，打开另一个工具，然后花十分钟重新解释你正在做什么，这个项目就是为解决这个问题而生的。BlueOcean Vector 在你的机器上运行一个小型服务器。任何支持 MCP 的代理都可以从中读取和写入。无论你接下来打开哪个工具，它只需询问“关于这个项目我们知道什么？”，然后就能从上一个工具停下的地方继续。

[!TIP] 在 Claude Code 中存储一个决策 → 明天打开 Codex → 它已经知道你为什么选择 Postgres 而不是 DynamoDB，而不仅仅是知道你选择了它。

目录

• 为什么存在

• 对比

• 架构

• 快速开始

  • 教会代理实际使用它

  • 备选方案：stdio

• 代理可用的工具

• 配置

• 管理 CLI

• 运行测试

• 安全

• 部署到 localhost 之外

• 注意事项

• 许可证

Related MCP server: AIVectorMemory

为什么存在

每个代理会话都从零开始。你解释项目、约束条件、“那个我们试过了，行不通”——然后会话结束，一切消失。乘以你使用的每个工具，你实际上是在花费真正的 token 来重新建立一小时前就已经存在的上下文。

BlueOcean Vector 是一个小而朴素的修复方案：一个共享的记忆存储，一个 URL，以及一组通用工具（memory_store、memory_search、memory_summarize_session 等），任何 MCP 客户端都可以调用。它不会自作聪明地决定该记住什么——它只是给代理一个地方来存放和取回信息，按项目划分作用域，这样在一个代码库中搜索不会带出另一个代码库的无关信息。

对比

“AI 代理的记忆”这个领域已经有不少项目了。值得坦诚地说明这个项目实际所处的位置，而不是假装这个领域是空白的。

两个坦诚的结论：

• “MCP 原生，适用于任何客户端”这个领域并非空白——Memorix 已经在那里了，并且内置了更多工具。这里的不同之处在于，向量搜索是主要的检索路径，而不是后备方案或付费墙后的功能；默认的嵌入模型真正支持多语言（泰语+英语已测试）；并且它被设计为作为一个共享的持久服务器运行，而不是一个零安装的每代理工具——支持 Bearer Token 认证、有文档记录的 ECS 部署路径、Kubernetes 就绪探针，以及针对共享服务器实际遇到的并发问题的真正修复。

• 没有自动提取或整合——与 mem0、Graphiti、Letta、cognee 或 LangMem 不同，这里没有任何东西会读取你的对话并决定哪些值得记住。这是一个刻意的简化权衡，而不是缺失的功能：代理必须显式调用 memory_store。如果你想要一个能替你判断该保留什么的系统，上面提到的那些项目会比这个做得更好。

记忆不应该试图容纳一百万行代码

有些项目有一百万行代码。没有任何记忆系统——包括 BlueOcean Vector——应该试图存储所有这些代码。存储代码是代码搜索工具的工作，而不是记忆服务器的工作。

BlueOcean 的工作更狭窄也更有用：记住什么重要，以及在哪里找到它。 它保存决策、架构、“那个我们试过了，行不通”——这些是代理本需要从一百万行代码中重新发现的浓缩知识——再加上刚好足够的上下文，以便在需要细节时引导代理回到真正的代码。

结果是，记忆的增长与实际值得记住的内容成正比，而不是与代码库的大小成正比。一个百万行代码的项目可能只有几千条记忆条目。无论项目变得多大，检索成本都保持低廉。

Token 计算

读取记忆正是这种区别带来回报的地方。最便宜的替代方案——一个将项目笔记转储到代理读取的 .remember 文件中的技能或插件——在文件超出上下文窗口之前工作得很好，然后它就悄无声息地变得无用了。

BlueOcean 将每次搜索限制在一个 token 预算内（默认 2000 tokens，可通过 BLUEOCEAN_MAX_TOKENS 配置）。语义搜索只拉取相关的条目，然后分配预算：约 60% 用于浓缩摘要，约 40% 用于最匹配条目的完整内容。超出预算的条目会被截断，绝不会被整体转储。

对一个小型演示项目的实际搜索返回了 121 tokens，用于一个摘要加一个完整条目——只占 2000 token 预算的百分之几，而且这个预算永远不会随着项目积累记忆而增长。使用纯文本文件，同样的读取每次都要花费整个文件的大小，所以一个 5000 条目的项目（数十万 token）一次读取就不可行了。

架构

┌────────────┐ ┌──────┐ ┌────────┐ ┌───────────────┐ ┌──────┐
│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 add CLI（或者，对于 Cursor，直接编辑 ~/.cursor/mcp.json，因为 Cursor 的 CLI 只在应用打开时工作）将其指向 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

这是一个规范的 SKILL.md，通过符号链接到每个工具自己的技能目录中——只需编辑一次，所有工具都会收到更改。

备选方案：stdio（每个代理的本地进程）

没有 Docker，或者你不想运行共享服务器？运行：

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

并将工具的 MCP 配置指向 command（参见 .venv/bin/blueocean-mcp）而不是 url。

代理可用的工具

一个合理的代理工作流：在会话开始时先调用 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 无法识别这一点。它会删除所有符合过滤条件的条目，即使这些条目是五分钟前由其他会话写入的。请先运行 --dry-run，并优先使用窄范围过滤而非宽泛的重置。

export 仅以 JSON 格式导出负载（with_vectors=False）——从中恢复意味着需要从头重新嵌入所有内容，而非真正的时间点恢复。snapshot/restore 则使用 Qdrant 自身的原生快照机制：原子化地捕获向量、负载和索引状态。snapshot 将文件下载到本地磁盘，并在确认下载完整后删除服务端副本（备份仅存放在要备份的同一 Qdrant 卷中不算真正的备份）。restore 会覆盖项目的当前数据，因此需要 --yes 确认。

项目名称经过严格验证（^[a-z0-9][a-z0-9_-]*$，与此项目已推荐的目录命名惯例一致），而非静默规范化——两个代理对同一项目拼写稍有差异（"Team A" vs "team-a"）时，会合并到一个集合中且无警告；现在不一致的名称将被拒绝。

运行测试

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 注册远程服务器时设置自定义请求头，因此服务端接受两种令牌方式，每个客户端使用其支持的方式：

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

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

stdio 传输完全跳过此项：它是一个本地生成的子进程，已受操作系统进程生成权限的限制，而非位于网络上。

GET /health 故意不设置认证，仅检查 Qdrant 是否实际可访问，而非进程是否存活。这是 docker-compose.yml 中健康检查所轮询的端点。它还会报告活动的嵌入提供者/模型，对于 openai/bedrock（而非 fastembed，其模型加载已在进程启动时进行了检查）通过免费的 control-plane 调用而不是计费的嵌入端点来验证凭据，并将结果缓存 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），因为五个支持的客户端中有三个将令牌作为 ?token=... 发送，而纯文本的访问日志会在每次请求中将其明文记录。

部署到 localhost 之外

docker compose up -d 运行两个长期服务：qdrant（端口 6333）和 blueocean-mcp（端口 8765）。对于云端，同样的两个服务迁移到 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 在不同版本间有变化——1.19 版本移除了 .search() 改为 .query_points()。如果升级服务端镜像，请同步升级 qdrant-client 并重新运行测试套件；不要在未先创建快照的情况下对真实数据跳跃多个版本。

• mcp 固定为 >=2.0.0,<3.0.0，比这里的大多数依赖项更严格。其 API（mcp.server.mcpserver.MCPServer 等）在不同版本间形状有显著变化，宽松的约束可能导致 Docker 构建静默解析出不兼容的版本——Docker 构建不使用 uv.lock。

• 嵌入提供者与模型是配对使用的。 切换其中任何一个，旧向量相对于新向量将变成无法搜索的垃圾。在 .env 中固定模型，不要依赖可能变化的库默认值。

许可证

MIT——参见 LICENSE。