BlueOcean Vector

Общая, постоянная память для агентов, пишущих код.

Память, которая сохраняется при переключении с Claude Code на Codex и Cursor в середине проекта — и переживает исчерпание токенов в одном из них.

Если вы когда-нибудь сжигали контекстное окно, открывали другой инструмент, а затем тратили десять минут на повторное объяснение того, что делали, — это решение для этой проблемы. BlueOcean Vector запускает один небольшой сервер на вашей машине. Любой агент, поддерживающий MCP, может читать из него и записывать в него. Какой бы инструмент вы ни открыли следующим, он просто спросит: «что мы знаем об этом проекте?» и продолжит с того места, где остановился предыдущий.

[!TIP] Сохраните решение в Claude Code → откройте Codex завтра → он уже будет знать, почему вы выбрали Postgres, а не DynamoDB, а не просто то, что вы это сделали.

Содержание

• Зачем это нужно

• Сравнение с аналогами

• Как это устроено

• Начало работы

  • Обучение агентов реальному использованию

  • Альтернатива: stdio

• Инструменты, доступные агенту

• Конфигурация

• CLI для администрирования

• Запуск тестов

• Безопасность

• Развертывание за пределами localhost

• Подводные камни

• Лицензия

Related MCP server: AIVectorMemory

Зачем это нужно

Каждый сеанс агента начинается с нуля. Вы объясняете проект, ограничения, «мы уже пробовали это, не сработало» — а затем сеанс заканчивается, и все исчезает. Умножьте это на каждый используемый вами инструмент, и вы тратите реальные токены просто на восстановление контекста, который уже существовал час назад.

BlueOcean Vector — это небольшое, скучное исправление: одно общее хранилище памяти, один URL и общий набор инструментов (memory_store, memory_search, memory_summarize_session и еще несколько), которые может вызывать любой MCP-клиент. Он не пытается быть умным в том, что запоминать — он просто дает агентам место, куда можно положить информацию и забрать ее обратно, с областью действия в рамках проекта, чтобы поиск в одной кодовой базе не выдавал шум из другой.

Сравнение с аналогами

Уже существует множество проектов, посвященных «памяти для AI-агентов». Стоит честно рассказать, где находится этот проект, вместо того чтобы притворяться, что пространство пусто.

Два честных вывода:

• Ниша «нативный MCP, работает с любым клиентом» не пуста — Memorix уже там, с большим количеством встроенных инструментов. Отличие здесь в том, что векторный поиск является основным путем извлечения, а не запасным вариантом или чем-то, скрытым за платным уровнем, модель эмбеддингов по умолчанию действительно многоязычна (проверено на тайском+английском), и он создан для работы в качестве одного общего, постоянного сервера, а не инструмента с нулевой установкой для каждого агента — аутентификация по токену-носителю, документированный путь к ECS, готовые к Kubernetes проверки работоспособности и реальные исправления проблем параллелизма, с которыми сталкивается общий сервер.

• Нет автоматического извлечения или консолидации — в отличие от mem0, Graphiti, Letta, cognee или LangMem, здесь ничто не читает ваш разговор и не решает, что стоит запомнить. Это осознанный компромисс в пользу простоты, а не отсутствующая функция: агент должен явно вызывать memory_store. Если вам нужна система, которая сама решает, что сохранить, один из проектов выше справится с этим лучше.

Память не должна пытаться хранить миллион строк

Некоторые проекты насчитывают миллион строк кода. И ни одна система памяти — включая BlueOcean Vector — не должна пытаться хранить все это. Хранение кода — это задача инструмента для поиска кода, а не сервера памяти.

Задача BlueOcean уже и полезнее: запоминать, что было важно, и где это найти. Он хранит решения, архитектуру, «мы пробовали это, не сработало» — сжатые знания, которые агенту пришлось бы заново извлекать из миллиона строк — плюс достаточно контекста, чтобы указать агенту на реальный код, когда нужны детали.

В результате память растет вместе с тем, что действительно стоит запомнить, а не с размером кодовой базы. У проекта на миллион строк может быть несколько тысяч записей в памяти. Это сохраняет извлечение дешевым, независимо от того, насколько большим станет проект.

Математика токенов

Чтение памяти — вот где это различие окупается. Самый дешевый альтернативный вариант — навык или плагин, который сбрасывает заметки о проекте в файл .remember, который агент читает обратно — отлично работает, пока файл не превысит контекстное окно, после чего он перестает быть полезным.

BlueOcean ограничивает каждый поиск бюджетом токенов (по умолчанию 2000 токенов, настраивается через BLUEOCEAN_MAX_TOKENS). Семантический поиск извлекает только релевантные записи, а затем распределяет бюджет: ~60% на сжатые сводки, ~40% на полное содержание лучших результатов. Записи, выходящие за пределы бюджета, обрезаются, а не сбрасываются целиком.

Реальный поиск по небольшому демо-проекту вернул 121 токен для одной сводки + одной полной записи — несколько процентов от бюджета в 2000 токенов, и этот бюджет никогда не растет по мере накопления памяти в проекте. С обычным файлом то же чтение стоит полного размера файла каждый раз, поэтому проект с 5000 записей (сотни тысяч токенов) невозможно прочитать за один раз.

Как это устроено

┌────────────┐ ┌──────┐ ┌────────┐ ┌───────────────┐ ┌──────┐
│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 вызывает CLI mcp add каждого инструмента (или, для Cursor, редактирует ~/.cursor/mcp.json напрямую, так как CLI Cursor работает только при открытом приложении), чтобы указать ему на http://localhost:8765/mcp.

Для любого другого инструмента, поддерживающего MCP через HTTP, включая те, о которых мы никогда не слышали, просто укажите ему тот же URL через функцию «добавить удаленный MCP-сервер» этого инструмента:

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 vs stdio) — это флаг командной строки, а не переменная окружения: это выбор «как запустить», сделанный при старте, а не постоянная настройка.

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 действительно доступен, а не только то, что процесс жив. Именно этот эндпоинт опрашивает healthcheck в docker-compose.yml. Он также сообщает активного провайдера/модель встраивания, а для openai/bedrock (не 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), а не через флаг CLI --auth-token — значение, переданное как аргумент командной строки, видно любому другому локальному пользователю через 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 не читает healthcheck: из docker-compose.yml — ему нужны собственные пробы в спецификации Pod, но они могут указывать на тот же путь:

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

Несколько подводных камней, о которых стоит знать, прежде чем трогать это

• qdrant-client привязан к точной версии сервера Qdrant (см. тег образа в docker-compose.yml). Qdrant версионирует клиент и сервер синхронно, и API менялся между релизами — .search() был удалён в пользу .query_points() в версии 1.19. Если вы обновляете образ сервера, обновите qdrant-client до соответствующей версии и перезапустите набор тестов; не перескакивайте через несколько версий на реальных данных без предварительного снимка.

• mcp зафиксирован >=2.0.0,<3.0.0, жёстче, чем большинство зависимостей здесь. Его API (mcp.server.mcpserver.MCPServer и друзья) значительно менялся между релизами, и свободное ограничение рискует тем, что Docker-сборка молча разрешит несовместимую версию — Docker-сборки не используют uv.lock.

• Провайдер и модель встраивания — это согласованная пара. Если изменить что-то одно, старые векторы станут бесполезным мусором для новых. Зафиксируйте модель в .env, а не полагайтесь на значение библиотеки по умолчанию, которое может измениться без вашего ведома.

Лицензия

MIT — см. LICENSE.