Vector Storage and Embedding Provider

1. Status

This decision is Accepted. It settles where knowledge embeddings are stored and which provider generates them; chunking strategy, embedding refresh/versioning, hybrid search, reranking, RAG orchestration, and agent architecture are explicitly out of scope (see Section 6).

2. Context

Ocean-Atlas is being prepared for AI-assisted knowledge retrieval and future Ocean agents (the “Prepare Ocean-Atlas for AI and RAG Integration” epic). That work requires converting canonical Ocean-Atlas knowledge into embeddings, storing those embeddings, and performing semantic/vector search over the knowledge base.

atlas.knowledge-architecture §20.7 and §22.2 already establish the applicable constraint: indexes, embeddings, and vector databases are derived artifacts and must never become the authoritative source of Ocean knowledge. This decision operates inside that constraint, not around it — it picks a concrete storage and embedding technology, not a new source of truth.

Ocean already operates PostgreSQL infrastructure on Fly.io, shared across Ocean services. Introducing a separate vector database at this stage would add a new infrastructure category and vendor relationship the corpus’s current scale (roughly a hundred documents) does not justify — the same reasoning adr.search-today-structured-retrieval-tomorrow already applied when it deferred building dedicated search/retrieval infrastructure until a concrete need existed.

The embedding implementation must also avoid coupling Ocean-Atlas to one provider, so the provider or model can change later without touching the knowledge architecture or the retrieval API built on top of it (adr.knowledge-api-service).

3. Decision

3.1 Vector storage

Ocean-Atlas uses the existing Fly Postgres infrastructure with the pgvector extension, in a dedicated database, logically isolated from other Ocean services’ data:

Fly Postgres (shared cluster)
└── ocean_atlas (dedicated database)
    ├── knowledge metadata (denormalized copy, for self-contained results)
    └── vector embeddings (pgvector)

A dedicated vector database (Pinecone, Weaviate, Qdrant, or similar) is not introduced at this stage.

Everything stored here is a rebuildable cache, never hand-edited and never treated as authoritative: it must be fully reconstructable from canonical Markdown (via builders/core’s AtlasModel) at any time, the same rule adr.atlas-builder-boundary already applies to generated presentation output. Canonical Markdown remains the only source of truth for knowledge content; this database is a derived projection of it, scoped for retrieval.

Only services/knowledge-api connects to this database, over Fly’s private network — the same network boundary adr.knowledge-api-service already established for the service itself. Connection credentials arrive as a Fly secret; the exact secret name and connection convention will follow whatever pattern other Ocean services already use against this shared cluster.

3.2 Embedding provider

Voyage AI is the initial embedding provider, using:

model:      voyage-4
dimensions: 1024 (default)

The embedding layer stays provider-independent behind an interface:

Ocean-Atlas (services/knowledge-api)
    ↓
Embedding Provider Interface
    ↓
Voyage AI

The interface must allow alternatives — OpenAI, Cohere, voyage-code-4 for DSL/code-oriented retrieval, or a local model — to be introduced later without changing the ingestion pipeline or the retrieval API’s contract.

4. Alternatives Considered

4.1 A dedicated vector database (Pinecone, Weaviate, Qdrant)

Rejected for this stage. Purpose-built for large-scale vector workloads, but adds a new vendor, its own credentials and billing, and an infrastructure category this repository has never used — disproportionate for a corpus this size. Revisit if scale or retrieval requirements outgrow pgvector (see Section 5).

4.2 An embedding provider other than Voyage AI (OpenAI, Cohere)

Considered. Both are viable and the provider interface makes either a low-cost future swap. Voyage AI is chosen first for its retrieval-specific optimization, document/query-asymmetric embedding support, and its voyage-code-4 sibling model if DSL/code retrieval becomes a priority later.

4.3 A local/open-source embedding model

Rejected for now. No per-call cost and no external dependency, but no mature “just call a function” local embedding option exists in this repository’s Node-only toolchain — it would mean bundling a model file and an inference runtime, a meaningfully heavier footprint than anything shipped so far. Worth reconsidering only if a concrete requirement (cost, offline operation, data residency) demands it.

5. Consequences

Benefits

• Minimal new infrastructure: reuses a cluster and technology Ocean already operates.
• Relational metadata and vector data live together, so retrieval queries can join similarity search with structured filters (type, area, status, authority) in one place.
• Provider-independent embedding design keeps the door open to a different model or vendor without a retrieval-layer rewrite.
• Clear, incremental path toward semantic search, RAG, and future Ocean agents, without committing to agent or orchestration architecture now.

Trade-offs

• Embedding requests (chunk text at index time, query text at retrieval time) are sent to Voyage AI’s API — this corpus is already fully public on the website, so this is an operational dependency, not a new confidentiality exposure.
• Voyage AI credentials and usage need ongoing management, same as any external API dependency.
• pgvector may eventually become insufficient if Ocean-Atlas reaches substantially larger scale or needs retrieval capabilities pgvector doesn’t provide (e.g. specialized ANN algorithms at very large scale). Acceptable for the current stage; §4.1 remains the fallback if that changes.

6. Implementation Implications

The following are intentionally not decided by this ADR and remain open for follow-up work:

• chunking strategy;
• embedding refresh/versioning strategy (how re-indexing after a content change is triggered and staged);
• hybrid lexical + vector search (how this combines with services/knowledge-api’s existing keyword /v1/search);
• reranking;
• RAG orchestration and prompt construction;
• agent architecture;
• the exact retrieval API shape (routes, request/response contract) built on top of this storage.

7. Validation and Compliance Rules

• Data in the ocean_atlas Postgres database must remain fully reconstructable from canonical Markdown via builders/core’s AtlasModel; nothing stored there may be hand-edited or treated as a second source of truth.
• Only services/knowledge-api may hold credentials for this database; it must be reachable exclusively over Fly’s private network, never a public endpoint.
• A future change introducing a second embedding provider must go through the provider interface established here, not a parallel, ad hoc integration.
• Replacing pgvector with a dedicated vector database requires a new ADR, not a silent migration.

8. Related Knowledge

• adr.knowledge-api-service — the service that will own the connection to this database and expose retrieval over HTTP.
• adr.atlas-builder-boundary — the one-directional dependency and “generated output is disposable” principle this decision extends to a new kind of derived artifact.
• adr.search-today-structured-retrieval-tomorrow — the same “don’t build infrastructure before a concrete need exists” reasoning this decision applies to vector storage.
• atlas.knowledge-architecture — §20 (“Search and Retrieval Readiness”) and §22 (“Knowledge-Graph Readiness”), which require embeddings and vector databases to remain derived artifacts, never the authoritative knowledge source.

These semantic relationships are declared in the document metadata.