Vector Database Integrations

Relevant source files

The following files were used as context for generating this wiki page:

• packages/core/src/vectordb/milvus-vectordb.ts
• packages/chrome-extension/src/milvus/chromeMilvusAdapter.ts
• packages/chrome-extension/src/stubs/milvus-vectordb-stub.ts
• packages/core/src/context.ts
• packages/chrome-extension/src/background.ts
• examples/basic-usage/index.ts

The Vector Database Integration layer provides the storage and retrieval backbone for the Claude Context project. Its primary purpose is to manage high-dimensional vector embeddings generated from code snippets, enabling semantic and hybrid search capabilities across codebases. The system is designed to be pluggable, supporting both gRPC-based connections for high-performance Node.js environments and RESTful API adapters for restricted environments like browser extensions.

Sources: packages/core/README.md, packages/core/src/context.ts:89-105

Architecture Overview

The architecture centers around the VectorDatabase interface, which defines the contract for operations such as collection management, document insertion, and multi-modal searching. The project primarily utilizes Milvus and Zilliz Cloud as the underlying vector database engines.

This diagram illustrates the abstraction layer between the core context logic and the specific database communication protocols used across different platforms.
Sources: packages/core/src/context.ts:98, packages/chrome-extension/src/milvus/chromeMilvusAdapter.ts:37-45, examples/basic-usage/index.ts:30-45

Data Models and Schemas

Claude Context utilizes two primary collection types: Standard Vector collections for basic semantic search and Hybrid collections for combined dense and sparse (BM25) search.

Collection Schema Fields

Field Name	Data Type	Description
id	VarChar (Primary)	Unique identifier (hash-based) for the code chunk.
vector	FloatVector	Dense embedding vector representing the code's semantics.
sparse_vector	SparseFloatVector	Sparse vector used for BM25 hybrid search (Hybrid only).
content	VarChar	The raw text content of the code chunk.
relativePath	VarChar	File path relative to the codebase root.
startLine	Int64	Starting line number in the source file.
endLine	Int64	Ending line number in the source file.
fileExtension	VarChar	Extension of the source file (e.g., .ts, .py).
metadata	VarChar (JSON)	Stringified JSON containing additional context like language.

Sources: packages/core/src/vectordb/milvus-vectordb.ts:145-188, packages/chrome-extension/src/stubs/milvus-vectordb-stub.ts:114-165

Integration Implementations

Milvus gRPC Implementation

The MilvusVectorDatabase class uses the @zilliz/milvus2-sdk-node to provide high-performance connectivity. It includes robust lifecycle management, such as exponential backoff for index readiness and automatic collection loading into memory.

Key Lifecycle Logic:

1. Resolution: Resolves the connection address via the provided token if a direct address is missing.
2. Indexing: Creates a COSINE metric index for dense vectors and BM25 for sparse vectors.
3. Wait & Load: Polls the server until the index is 100% built before calling loadCollection.

Sources: packages/core/src/vectordb/milvus-vectordb.ts:50-135, packages/core/src/vectordb/milvus-vectordb.ts:203-215

RESTful Adapter for Browser Environments

In environments where gRPC is unavailable (e.g., Chrome Extensions), the system employs a REST-based approach. The MilvusRestfulVectorDatabase (or its stub) communicates via HTTP/HTTPS with the Milvus V2 VectorDB API.

Search Strategies

The integration supports two main search strategies:

1. Semantic Search: A single-vector search using COSINE similarity against the vector field.
2. Hybrid Search: A multi-modal search combining dense vector similarity and sparse vector (BM25) text relevance, merged using Reciprocal Rank Fusion (RRF).

Hybrid Search Execution Flow

When HYBRID_MODE is enabled, the Context class initiates a multi-stage search:

• Dense Phase: Uses query embeddings to search the vector field.
• Sparse Phase: Uses the raw query string to search the sparse_vector field via BM25.
• Rerank Phase: Applies RRF with a default k=100 to produce the final ranked result set.

Sources: packages/core/src/context.ts:311-360, packages/core/src/vectordb/milvus-vectordb.ts:486-535

Configuration and Environment Variables

Vector database connections are primarily configured through environment variables or the ContextConfig object.

Variable	Description	Default
MILVUS_ADDRESS	Public endpoint for the Milvus/Zilliz cluster.	localhost:19530
MILVUS_TOKEN	Authentication token/API Key for Zilliz Cloud.	N/A
HYBRID_MODE	Boolean flag to toggle between semantic and hybrid search.	true
MILVUS_USE_RESTFUL	Flag to force the RESTful implementation over gRPC.	false

Sources: packages/core/src/context.ts:133-145, examples/basic-usage/index.ts:22-30, packages/core/README.md:40-60

Conclusion

The Vector Database Integration layer ensures that Claude Context can scale from local development environments to large-scale codebase analysis on Zilliz Cloud. By abstracting the transport layer (gRPC vs. REST) and providing advanced hybrid search features, the system maintains high retrieval accuracy while ensuring cross-platform compatibility.