ruvector

Implements Hierarchical Navigable Small World (HNSW) algorithm for sub-linear time vector similarity search across high-dimensional embeddings. Uses a multi-layer graph structure with greedy search traversal to locate nearest neighbors in logarithmic complexity, enabling fast retrieval from million-scale vector collections without exhaustive scanning.

Merges HNSW dense vector search with BM25-style sparse keyword matching, then re-ranks results using configurable fusion strategies (RRF, weighted sum). Allows queries to match both semantic meaning and exact terminology, improving recall for domain-specific or technical documents where keyword precision matters alongside semantic similarity.

Integrates with multiple embedding model providers (OpenAI, Hugging Face, local models) through a pluggable backend interface, handling tokenization, batching, and error retry logic. Allows switching embedding models without changing application code, and supports local model execution for privacy-sensitive deployments or cost optimization.

Automatically expands queries with synonyms, related terms, and semantic variations before search, or rewrites queries to improve retrieval quality. Uses attention mechanisms and language models to generate alternative query formulations that capture different aspects of user intent, increasing recall by matching documents that use different terminology.

Normalizes and calibrates similarity scores from HNSW search to produce interpretable confidence values (0-1 range) that reflect actual retrieval quality. Uses statistical calibration based on query patterns to adjust raw distance scores, enabling consistent ranking across different embedding models and distance metrics without manual threshold tuning.

Constructs a knowledge graph from indexed documents where nodes represent entities/concepts and edges represent relationships, enabling multi-hop retrieval that follows semantic connections across documents. Queries traverse the graph to gather contextually related information beyond direct similarity matches, improving context coherence for LLM generation by providing interconnected knowledge.

Implements FlashAttention-3 algorithm for efficient attention mechanism computation during embedding refinement and query processing, reducing memory bandwidth requirements and computational complexity from O(n²) to near-linear through IO-aware tiling and kernel fusion. Enables processing of longer context windows and larger batch sizes without proportional memory growth.

Provides a modular architecture supporting 50+ attention variants (multi-head, multi-query, grouped-query, linear attention, sparse attention, etc.) that can be swapped during embedding computation. Allows fine-tuning embedding quality for specific domains by selecting attention patterns that emphasize different aspects of token relationships, without recomputing base embeddings.

Continuously monitors query patterns and result quality, automatically adjusting HNSW parameters (M, ef_construction, ef_search) and attention mechanism selection based on observed performance. Uses statistical feedback from queries to optimize index structure without manual tuning, improving search latency and recall over time as the system learns domain-specific access patterns.

Supports adding, updating, and deleting vectors in batches without full index reconstruction, using HNSW insertion algorithms and conflict resolution strategies to maintain index integrity. Detects duplicate embeddings or conflicting metadata and applies configurable merge strategies (keep-newest, keep-oldest, merge-metadata), enabling continuous corpus updates without downtime.

Compiles core vector search algorithms (HNSW, attention mechanisms, indexing) to WebAssembly and Rust native binaries, exposing them via Node.js native bindings (N-API). Avoids JavaScript performance bottlenecks by executing compute-intensive operations in compiled code while maintaining JavaScript API ergonomics, achieving 10-100x speedup over pure-JS implementations.

Supports filtering search results by metadata attributes using boolean logic (AND, OR, NOT) and range queries (numeric comparisons, date ranges, string matching). Filters are applied post-search (after HNSW retrieval) or pre-search (to narrow candidate set), allowing queries like 'find similar documents from 2024 with category=research AND author IN [list]' without separate database lookups.

Stores vector index and metadata to disk (file system or cloud storage) with optional in-memory cache layer for frequently accessed vectors. Supports both memory-mapped access (for large indexes exceeding RAM) and full in-memory operation, with configurable cache eviction policies (LRU, LFU) to balance memory usage and latency.