Weavatrix Search Vector

weavatrix-search-vector is a first-party, in-memory vector-candidate engine for Weavatrix and other Rust applications. It provides deterministic hybrid HNSW plus multi-probe SimHash search and an exact brute-force oracle over dense f32 cosine vectors.

The public API is safe Rust, requires Rust 1.88, and has no runtime dependencies, native libraries, helper processes, or external vector engines. One private audited std::arch module dispatches to AVX2, SSE2, or NEON after runtime feature detection and otherwise uses a scalar fallback.

Installation

cargo add weavatrix-search-vector

Or add the crate directly to Cargo.toml:

[dependencies]
weavatrix-search-vector = "0.1"

Boundary

Vector Search owns:

• vector and query validation;
• deterministic HNSW construction;
• uncertainty-driven SimHash candidate recovery;
• approximate and exact top-K candidate search;
• stable equal-distance ordering by caller-provided u64 key;
• bounded batch workers;
• recall and retained-allocation evidence.

It does not know about graphs, semantic thresholds, embedding models, provenance, mutual/union policies, text search, or repository discovery. Semantic consumers remain responsible for exact rescoring and relationship policy.

Example

use weavatrix_search_vector::{IndexConfig, VectorIndex};

let first = [1.0, 0.0, 0.0];
let second = [0.9, 0.1, 0.0];
let third = [0.0, 1.0, 0.0];
let vectors = [(10, first.as_slice()), (20, second.as_slice()), (30, third.as_slice())];

let index = VectorIndex::build(IndexConfig::new(3), &vectors)?;
let hits = index.search(&[1.0, 0.0, 0.0], 2)?;

assert_eq!(hits[0].key, 10);
assert_eq!(hits[1].key, 20);
# Ok::<(), weavatrix_search_vector::SearchError>(())

VectorIndex::search_batch preserves query order and reuses one visited set and heap set per bounded standard-library worker. VectorIndex::search_exact and ExactIndex provide deterministic ground truth for recall tests.

Algorithm

Each HNSW replica uses:

• key-sorted normalized vector storage;
• seed/key-derived levels and insertion permutation;
• deterministic parallel bulk-construction waves;
• greedy upper-layer descent;
• bounded best-first layer search;
• diversified outgoing links and retained reverse links;
• doubled layer-zero outgoing degree;
• a compact 14-bit SimHash table with five uncertainty-driven probes;
• runtime-dispatched first-party cosine kernels;
• exact cosine distances for every returned hit.

Independent replicas and the construction work inside each replica share the configured build-worker budget. The built index is immutable, Send, and Sync. Memory is proportional to vector storage and retained graph links, never to the square of the vector count.

Reference benchmark

The reference gate is 10,000 vectors x 384 dimensions, cosine distance, top-8, one warm-up and three release runs:

• build plus all 10,000 approximate queries at most 3 seconds on the reference Windows host;
• recall@8 at least 99.9% against the exact oracle;
• retained allocation estimate below 256 MiB;
• identical API behavior on Windows, Linux, and macOS;
• Rust 1.88, rustfmt, Clippy and rustdoc with warnings denied.

The 2026-07-27 Windows run passes the local performance, recall, and allocation gates:

Machine: Intel Core Ultra 7 255U, 12 cores / 14 logical processors, Windows 11 Enterprise 10.0.26200, rustc 1.97.1 GNU. The corpus is deterministic, synthetic, and clustered. The allocation figure is calculated from retained vector/link capacities; it is not process RSS. See docs/benchmark-2026-07-27.md for commands, raw results, and limitations.

cargo bench --bench vector_search -- run

Environment variables WV_VECTOR_COUNT, WV_VECTOR_DIMENSIONS, WV_VECTOR_TOP_K, WV_VECTOR_RUNS, WV_VECTOR_EXACT_QUERIES, WV_VECTOR_CONNECTIVITY, WV_VECTOR_EXPANSION_BUILD, WV_VECTOR_EXPANSION_QUERY, and WV_VECTOR_REPLICAS control the reproducible corpus and policy. Set WV_VECTOR_EXACT_QUERIES=10000 for the complete reference recall calculation.

These figures establish this crate's disclosed workload, not a general speed claim against another vector engine. Cross-engine benchmarks require identical vectors, query sets, thread budgets, recall, and process-memory measurement.

Competitors

The five-run quality-gated comparison against hnsw_rs 0.3.4 and usearch 2.26.0 found:

Weavatrix is fastest in build, query-only, and build-plus-query on the reference corpus while staying above the 99.9% recall gate. At 50,000 x 384, Weavatrix retained 99.95% sampled recall with a 0.956-second all-query pass; the tested usearch policies were slower and did not retain a 99.9% three-run minimum. See docs/competitive-benchmark-2026-07-27.md for policies, three-run minimum recall, full-oracle evidence, memory caveats, functional gaps, and reproduction commands.

Not in 0.1

Persistence, memory mapping, incremental mutation, deletion, metadata filters, quantization, embeddings, graph construction, and distributed search remain outside the initial package.