BlueOcean Vector

코딩 에이전트를 위한 공유형 영구 메모리.

Claude Code에서 Codex, Cursor로 프로젝트 중간에 바꿔도 유지되는 메모리 — 그리고 그중 하나에서 토큰이 부족해져도 살아남는 메모리.

컨텍스트 윈도우를 다 써버리고, 다른 도구를 열고, 다시 10분 동안 무슨 작업을 하고 있었는지 설명한 적이 있다면, 이 문제를 위한 것입니다. BlueOcean Vector는 사용자 머신에서 하나의 작은 서버를 실행합니다. MCP를 지원하는 모든 에이전트가 읽고 쓸 수 있습니다. 어떤 도구를 열든 "이 프로젝트에 대해 무엇을 알고 있나?"라고 묻기만 하면 이전 도구가 멈춘 지점부터 이어받습니다.

[!TIP] Claude Code에서 결정을 저장 → 내일 Codex를 열면 — 단순히 Postgres를 선택했다는 사실뿐만 아니라 왜 DynamoDB 대신 Postgres를 선택했는지를 이미 알고 있습니다.

목차

• 존재 이유

• 비교

• 구성 방식

• 시작하기

  • 에이전트가 실제로 사용하도록 가르치기

  • 대안: stdio

• 에이전트가 얻는 도구들

• 설정

• 관리 CLI

• 테스트 실행

• 보안

• 로컬호스트 이상으로 배포

• 주의사항

• 라이선스

Related MCP server: AIVectorMemory

존재 이유

모든 에이전트 세션은 빈 상태로 시작합니다. 프로젝트, 제약사항, "이미 시도해봤는데 안 됐어"를 설명하고 — 세션이 끝나면 모두 사라집니다. 사용하는 모든 도구에 대해 이 과정을 반복하면, 한 시간 전에 이미 존재했던 컨텍스트를 재구축하는 데 실제로 많은 토큰을 낭비하게 됩니다.

BlueOcean Vector는 간단하고 지루한 해결책입니다: 하나의 공유 메모리 저장소, 하나의 URL, 그리고 모든 MCP 클라이언트가 호출할 수 있는 공통 도구 집합(memory_store, memory_search, memory_summarize_session 등)입니다. 무엇을 기억할지 영리하게 결정하려고 하지 않습니다 — 에이전트가 항목을 저장하고 다시 가져올 수 있는 장소를 제공할 뿐이며, 프로젝트별로 범위가 지정되어 한 코드베이스에서 검색해도 다른 코드베이스의 잡음이 나타나지 않습니다.

비교

이미 "AI 에이전트용 메모리" 프로젝트 분야는 꽤 활성화되어 있습니다. 이 프로젝트가 실제로 어디에 위치하는지 솔직히 말하는 것이 중요합니다.

두 가지 솔직한 결론:

• "MCP 네이티브, 모든 클라이언트와 호환" 니치는 비어 있지 않음 — Memorix가 이미 그 자리에 있으며 더 많은 내장 도구를 제공합니다. 여기서 다른 점은 벡터 검색이 폴백이나 유료 티어 뒤에 있는 것이 아닌 주요 검색 경로이며, 기본 임베딩 모델이 진정 다국어(태국어+영어 테스트 완료)이고, 에이전트별 설치 제로 도구가 아닌 하나의 공유된 영구 서버로 실행되도록 설계되었다는 점입니다 — 베어러 토큰 인증, ECS로의 문서화된 경로, 쿠버네티스 준비 상태 프로브, 그리고 공유 서버가 실제로 직면하는 동시성 문제에 대한 실제 수정 사항이 포함되어 있습니다.

• 자동 추출 또는 통합 없음 — 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

이게 전부입니다. setupp_local.sh는 두 컨테이너를 시작하고, Qdrant가 실제로 응답할 때까지 기다린 후(단순히 "프로세스 시작" 아님), 첫 실행 시 .envi.example을 .envi에 복사하고 Python 패키지를 동기화합니다. regisster_mcp.sh는 각 도구의 자체 mcp add CLI를 호출하거나(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

각 도구의 자체 스킬 디렉터리에 심볼릭 링크된 하나의 정식 SKILL.md입니다 — 한 번 편집하면 모든 도구가 변경 사항을 적용합니다.

대안: stdio (에이전트별 로컬 프로세스)

Docer 사용 불가, 또는 공유 서버를 실행하지 않으려면? 다음 실행:

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 vs 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_-]*$, 이 프로젝트가 이미 권장하는 디렉토리 이름 규칙과 일치). 더 이상 조용히 정규화되지 않습니다. 두 에이전트가 동일한 프로젝트의 약간 다른 표기를 추측하는 경우 ("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 전송은 이 과정을 완전히 건너뜁니다: 로컬에서 생성된 하위 프로세스이며 네트워크에 있지 않고 OS 프로세스 생성 권한에 의해 이미 제한됩니다.

GET /health는 의도적으로 인증되지 않으며 프로세스가 살아있는지뿐만 아니라 Qdrant가 실제로 연결 가능한지 확인합니다. 이것이 docker-compose.yml의 healthcheck가 폴링하는 대상입니다. 또한 활성 임베딩 제공자/모델을 보고하며, openai/bedrock의 경우 (fastembed의 모델 로드는 이미 프로세스 시작을 제어하므로 해당되지 않음) 과금되는 임베드 엔드포인트 대신 무료 제어 평면 호출을 통해 자격 증명을 검증하고, 결과를 BLUEOCEAN_HEALTH_EMBED_TTL 초 (기본값 60) 동안 캐싱하여 10초 프로브 간격이 매번 공급자 API 호출로 이어지지 않도록 합니다:

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

토큰은 --auth-token CLI 플래그가 아닌 BLUEOCEAN_AUTH_TOKEN (환경 변수 / .env)을 통해 설정하세요. 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가 릴리스 간에 변경되었습니다. .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를 참조하세요.