How Embeddings Are Generated and Utilized for Semantic Search Ranking in GitNexus

GitNexus generates 384-dimensional embeddings using the snowflake-arctic-embed-xs transformer model, stores them in a KuzuDB vector index with cosine similarity, and combines semantic results with BM25 keyword search via Reciprocal Rank Fusion for hybrid ranking.

GitNexus is an open-source semantic code search engine that transforms repository contents into searchable vector representations. Understanding how embeddings are generated and utilized for semantic search ranking in GitNexus reveals a sophisticated pipeline that bridges transformer-based NLP with graph database vector indices.

Embedding Generation Pipeline

The embedding generation process follows a six-stage pipeline orchestrated by runEmbeddingPipeline() in src/core/embeddings/embedding-pipeline.ts. This pipeline converts raw source code into indexed vector representations ready for similarity search.

Model Initialization and Hardware Acceleration

The initEmbedder() function in src/core/embeddings/embedder.ts (lines 17-85) bootstraps the transformer pipeline as a singleton instance. It automatically probes for hardware acceleration, preferring CUDA on Linux and DirectML on Windows, with automatic fallback to CPU or WASM execution. The system loads the snowflake-arctic-embed-xs model, which produces dense 384-dimensional vectors optimized for code similarity tasks.

Node Discovery and Text Extraction

The queryEmbeddableNodes() function (lines 31-73 in embedding-pipeline.ts) traverses the graph database to identify all nodes labeled as embeddable—typically files, functions, classes, and methods. For each node, it extracts the id, name, label, filePath, and content fields, along with line number boundaries (startLine and endLine) for precise code element localization.

Batch Encoding and Vector Storage

Text preparation occurs through generateBatchEmbeddingTexts(), which concatenates relevant node metadata into a single textual representation per node. The embedBatch(texts) method (lines 36-61 in embedder.ts) then processes these texts through the transformer pipeline in batches, returning an array of Float32Array vectors.

The batchInsertEmbeddings() function (lines 90-101 in embedding-pipeline.ts) persists these vectors to the dedicated CodeEmbedding table in KuzuDB. This separation of concerns—storing vectors in a lightweight auxiliary table rather than updating original code tables—ensures efficient bulk operations without disrupting the primary graph structure.

Vector Index Creation with Cosine Similarity

Finally, createVectorIndex() (lines 107-113 in embedding-pipeline.ts) issues a KuzuDB command to build a vector index on the embedding column using cosine distance metrics. This index enables sub-second nearest-neighbor lookups across the entire code repository during query execution.

Semantic Search Execution at Query Time

When users submit search queries, GitNexus executes a three-phase retrieval process that transforms natural language into ranked code results.

Query Encoding and Vector Index Lookup

The semanticSearch() function (lines 97-108 in embedding-pipeline.ts) first verifies model readiness via isEmbedderReady(), then encodes the user's search string into a 384-dimensional vector using embedText(query). This vector feeds into a KuzuDB vector index query (CALL QUERY_VECTOR_INDEX …) that returns the closest node IDs along with their cosine distances.

Metadata Enrichment and Result Structuring

Each retrieved node ID undergoes metadata resolution (lines 40-66 in embedding-pipeline.ts) to fetch the original table context—whether the node represents a File, Function, Class, or Method. The system enriches the results with name, filePath, startLine, and endLine attributes, returning structured SemanticSearchResult objects that preserve code location precision.

Hybrid Ranking with Reciprocal Rank Fusion

GitNexus does not rely solely on semantic similarity. Instead, it implements a hybrid search strategy that combines vector-based semantic search with traditional BM25 keyword matching.

Combining BM25 and Semantic Results

The hybridSearch() function in src/core/search/hybrid-search.ts (lines 14-78) orchestrates the fusion process. It concurrently executes two retrieval paths: searchFTSFromKuzu for BM25 full-text search against the KuzuDB FTS index, and semanticSearch for vector similarity. Both result sets are normalized to a common format containing file identifiers and relevance scores.

RRF Score Calculation and Final Ranking

The mergeWithRRF() function applies Reciprocal Rank Fusion to combine the disparate scoring systems. For each result, it calculates an RRF score using the formula 1 / (k + rank), where k = 60 (the standard RRF constant). If a file appears in both the BM25 and semantic result sets, its RRF scores are summed, boosting its final position. The system sorts by the aggregated RRF score and returns the top-N results, ensuring that files matching both keyword patterns and semantic meaning surface first.

Implementation Examples

Initialize the Embedder

import { initEmbedder } from '@/core/embeddings/embedder';

// Load the model (uses GPU if available)
await initEmbedder();

Source: [embedder.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/embeddings/embedder.ts#L81-L89)

Run the Full Embedding Pipeline

import { runEmbeddingPipeline } from '@/core/embeddings/embedding-pipeline';
import { executeQuery, executeWithReusedStatement } from '@/storage/kuzu';

await runEmbeddingPipeline(
  executeQuery,
  executeWithReusedStatement,
  progress => console.log('Embedding progress', progress)
);

Source: [embedding-pipeline.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/embeddings/embedding-pipeline.ts#L33-L86)

Perform Pure Semantic Search

import { semanticSearch } from '@/core/embeddings/embedding-pipeline';

const results = await semanticSearch(
  executeQuery,
  'read a file from repository',
  10,          // top-k
  0.4          // max distance threshold
);
console.log(results);

Source: [embedding-pipeline.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/embeddings/embedding-pipeline.ts#L97-L108)

Execute Hybrid Search

import { hybridSearch } from '@/core/search/hybrid-search';
import { semanticSearch } from '@/core/embeddings/embedding-pipeline';

const results = await hybridSearch(
  'parse JSON payload',
  10,
  async cypher => await executeQuery(cypher),
  semanticSearch
);
console.log(results);

Source: [hybrid-search.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/search/hybrid-search.ts#L52-L62)

Summary

• GitNexus generates embeddings using the snowflake-arctic-embed-xs transformer model, producing 384-dimensional vectors optimized for code semantics.
• The embedding pipeline in src/core/embeddings/embedding-pipeline.ts orchestrates node discovery, batch encoding, and vector storage in a dedicated CodeEmbedding table.
• KuzuDB stores vectors and maintains a cosine-metric vector index for sub-second nearest-neighbor lookups during query execution.
• Semantic search encodes user queries on-the-fly and retrieves relevant code elements with precise file path and line number metadata.
• Hybrid ranking combines semantic and BM25 results using Reciprocal Rank Fusion (RRF) with k=60, ensuring files matching both keyword patterns and semantic meaning rank highest.

Frequently Asked Questions

What embedding model does GitNexus use?

GitNexus uses the snowflake-arctic-embed-xs transformer model, which generates 384-dimensional dense vectors specifically optimized for semantic similarity tasks. The model is loaded via the @huggingface/transformers library in src/core/embeddings/embedder.ts and supports automatic hardware acceleration through CUDA on Linux or DirectML on Windows.

How does GitNexus handle hardware acceleration for embedding generation?

The initEmbedder() function in src/core/embeddings/embedder.ts implements a cascading hardware detection strategy. It first attempts to use CUDA for GPU acceleration on Linux systems, then falls back to DirectML for Windows environments. If neither GPU backend is available, the system automatically falls back to CPU execution or WebAssembly (WASM) runtimes, ensuring consistent embedding generation across diverse deployment environments.

What is the difference between pure semantic search and hybrid search in GitNexus?

Pure semantic search uses only vector similarity to find code elements that are semantically related to the query, regardless of exact keyword matches. This is implemented in the semanticSearch() function in src/core/embeddings/embedding-pipeline.ts. Hybrid search, implemented in src/core/search/hybrid-search.ts, combines these semantic results with traditional BM25 keyword search results using Reciprocal Rank Fusion (RRF). The hybrid approach ensures that files matching both the semantic intent and specific keywords receive higher rankings, providing more robust search results across different query styles.

How does Reciprocal Rank Fusion improve search results in GitNexus?

Reciprocal Rank Fusion (RRF) addresses the fundamental incompatibility between semantic similarity scores (cosine distance) and keyword relevance scores (BM25). The mergeWithRRF() function in src/core/search/hybrid-search.ts assigns each result an RRF score calculated as 1 / (k + rank), where k is set to 60. When a file appears in both the semantic and keyword result sets, its RRF scores are summed, effectively boosting files that demonstrate both semantic relevance and keyword match quality. This fusion method eliminates the need to normalize disparate scoring scales while ensuring robust ranking across heterogeneous search signals.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}