Struct VectorIndex 

pub struct VectorIndex { /* private fields */ }

In-memory vector index for fast similarity search

Uses HNSW (Hierarchical Navigable Small World) for approximate nearest neighbor search. This provides O(log n) search time instead of O(n) brute-force, making it 10-100x faster for large repositories (10K+ spans).

Implementations

impl VectorIndex

pub fn build(spans: Vec<Span>) -> Self

Build an index from spans using HNSW

Arguments

• spans - Vector of spans with embeddings

Returns

A new VectorIndex ready for searching

HNSW Parameters

• m: Maximum number of connections per node (16 = good balance of speed/quality)
• ef_construction: Size of candidate list during construction (200 = high quality)
• ef_search: Size of candidate list during search (50 = good balance)

These parameters provide >95% recall@50 while being 10-100x faster than brute-force.

pub fn search( &self, query_embedding: &[f32], k: usize, ) -> Result<Vec<ScoredSpan>>

Search for similar spans using HNSW approximate nearest neighbor search

Arguments

• query_embedding - The query vector
• k - Number of results to return

Returns

Vector of scored spans, sorted by relevance (highest score first)

Performance

• O(log n) search time instead of O(n) brute-force
• 10-100x faster for large repositories (10K+ spans)

• 95% recall@k (quality maintained)

pub fn len(&self) -> usize

Get the number of spans in the index

pub fn is_empty(&self) -> bool

Check if the index is empty

pub fn spans(&self) -> &[Span]

Get all spans (for debugging and persistence)

pub fn save_to_disk(&self, cache_dir: &Path) -> Result<()>

Save HNSW index to disk for persistence (Phase 2.1)

Saves both the HNSW graph structure and the spans metadata. This allows instant loading on subsequent queries once hnsw_rs supports owned loading; for now we only reload from cached spans.

Arguments

• cache_dir - Directory to save index files

Returns

Ok(()) if successful

pub fn load_from_disk(cache_dir: &Path) -> Result<Option<Self>>

Load HNSW index from disk (Phase 2.1)

Note: Due to lifetime constraints in the hnsw_rs library, we cannot directly load the HNSW structure from disk. Instead, we load cached spans and rebuild HNSW. This is still faster than loading spans from SQLite, but not as fast as loading the HNSW structure directly would be.

For large repositories (>10K spans), consider using server mode which keeps the index in memory across queries for optimal performance.

Arguments

• cache_dir - Directory containing index files

Returns

Some(VectorIndex) if loaded successfully, None otherwise