Hybrid Semantic Search

Relevant source files

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

• packages/core/src/context.ts
• packages/core/src/vectordb/milvus-vectordb.ts
• packages/core/src/vectordb/milvus-restful-vectordb.ts
• packages/mcp/src/handlers.ts
• README.md
• packages/core/README.md

Hybrid Semantic Search is a core retrieval mechanism in Claude Context that combines traditional keyword-based search (BM25) with AI-powered dense vector embeddings. This approach enables the system to locate relevant code snippets by understanding both the literal text and the semantic meaning behind natural language queries. By integrating these two methods, the project provides a more robust search experience that handles technical jargon and conceptual descriptions with high precision.

Sources: README.md:162-164, packages/core/src/context.ts:380-384

System Architecture

The hybrid search architecture relies on a specialized schema within the Milvus vector database, utilizing two distinct vector types for every indexed code chunk: dense vectors for semantic similarity and sparse vectors for keyword relevance.

Core Components

• Embedding Provider: Generates dense vector representations of code and queries using models like OpenAI's text-embedding-3-small.
• BM25 Function: A database-side function that converts raw text into sparse vectors to support keyword matching.
• Vector Database: Either MilvusVectorDatabase (gRPC) or MilvusRestfulVectorDatabase (REST) manages the storage and retrieval of these multi-vector documents.
• Reranker: Uses Reciprocal Rank Fusion (RRF) to combine results from both search methods into a single, ranked list.

Sources: packages/core/src/context.ts:80-86, packages/core/src/vectordb/milvus-vectordb.ts:468-475, packages/core/src/vectordb/milvus-vectordb.ts:634-637

Data Flow for Search Execution

The search process begins by generating a dense embedding for the user's query and then executing parallel searches against the dense and sparse indexes.

The diagram shows the parallel search paths for dense and sparse vectors, followed by the RRF reranking phase.
Sources: packages/core/src/context.ts:405-430

Database Schema & Indexing

To support hybrid search, the system creates a collection with a specific field configuration that enables both vector types and full-text analysis.

Hybrid Collection Schema

Field Name	Data Type	Description
id	VarChar	Unique hash-based ID for the code chunk
content	VarChar	Full text content for BM25 and storage; enable_analyzer: true
vector	FloatVector	Dense vector embedding generated by the embedding provider
sparse_vector	SparseFloatVector	Sparse vector embedding generated via BM25 function
relativePath	VarChar	Relative path to the file in the codebase
metadata	VarChar	JSON string containing language, codebasePath, and chunk index

Sources: packages/core/src/vectordb/milvus-vectordb.ts:443-465

Indexing Logic

During the indexCodebase operation, code is split into chunks and processed in batches. When HYBRID_MODE is enabled, the system uses the insertHybrid method to populate both vector fields.

// From packages/core/src/context.ts:581-605
const documents: VectorDocument[] = chunks.map((chunk, index) => {
    return {
        id: this.generateId(relativePath, chunk.metadata.startLine || 0, chunk.metadata.endLine || 0, chunk.content),
        content: chunk.content, 
        vector: embeddings[index].vector, // Dense vector
        relativePath,
        // ... metadata and lines
    };
});
await this.vectorDatabase.insertHybrid(this.getCollectionName(codebasePath), documents);

Sources: packages/core/src/context.ts:577-606

Search Implementation

The search logic is implemented in Context.semanticSearch. When the system detects it is in hybrid mode (controlled by the HYBRID_MODE environment variable), it constructs a HybridSearchRequest.

Search Parameters

Parameter	Default/Strategy	Description
Dense Params	nprobe: 10	Search parameters for the HNSW/AutoIndex
Sparse Params	drop_ratio_search: 0.2	Parameters for the Sparse Inverted Index
Rerank Strategy	rrf	Reciprocal Rank Fusion used to merge dense and sparse scores
Rerank K	100	The constant K used in the RRF algorithm

Sources: packages/core/src/context.ts:413-435, packages/core/src/vectordb/milvus-vectordb.ts:634-637

Sequence Diagram: Search Execution

This sequence illustrates the interaction between the core context, embedding provider, and the hybrid-capable vector database.
Sources: packages/core/src/context.ts:410-445

Environment Configuration

The behavior of the Hybrid Semantic Search is influenced by environment variables managed by the envManager.

• HYBRID_MODE: Determines if the system uses hybrid search (BM25 + Dense) or standard semantic search. Defaults to true.
• EMBEDDING_BATCH_SIZE: Sets the number of chunks processed at once during indexing. Defaults to 100.
• MILVUS_ADDRESS & MILVUS_TOKEN: Connection details for the vector database required to store the hybrid index.

Sources: packages/core/src/context.ts:182-188, packages/core/README.md:35-45, packages/mcp/src/handlers.ts:311-315

Conclusion

Hybrid Semantic Search represents an advancement over standard vector retrieval by utilizing both the structural keyword relevance of code and the conceptual understanding of large language models. Through the use of Milvus's multi-vector capabilities and RRF reranking, Claude Context ensures that searches like "function that handles user authentication" return the most relevant snippets, regardless of whether the specific keywords appear in the code.

Sources: README.md:183-188, evaluation/case_study/README.md:27-33