research: RVQ compressed ANN — nightly study 2026-07-28 - #742
Draft
ruvnet wants to merge 3 commits into
Draft
Conversation
Implements Residual Vector Quantization (RVQ) and Product Quantization (PQ) as compressed approximate nearest-neighbour indices in pure Rust with zero external dependencies. ADC lookup tables give O(S×N) query time vs O(D×N) for exact search. Includes: - VectorIndex trait + Hit struct + recall_at_k utility (lib.rs) - LCG PRNG + unit-vector dataset generator (dataset.rs) - Lloyd's k-means with Fisher-Yates init (kmeans.rs) - ExactSearch brute-force inner-product baseline (exact.rs) - PqIndex: M sub-spaces × K codewords ADC search (pq.rs) - RvqIndex: S stages × K codewords residual encoding + ADC (rvq.rs) - benchmark binary with env-var tuning + acceptance checks (bin/benchmark.rs) Co-Authored-By: claude-flow <ruv@ruv.net> Claude-Session: https://claude.ai/code/session_01KDumUj8CDoyXgvneENUjgu
Captures the architecture decision to adopt Residual Vector Quantization as the compressed index format in ruvector-rvq. Documents context, tradeoffs, alternatives considered (OPQ, AQ/AQLM, RaBitQ+, SQ8), and migration path. Co-Authored-By: claude-flow <ruv@ruv.net> Claude-Session: https://claude.ai/code/session_01KDumUj8CDoyXgvneENUjgu
Research document covers SOTA survey (RaBitQ, AQLM, FaTRQ, Qinco2), 10-20 year thesis, ecosystem fit, design rationale, real benchmark results, memory math, failure modes, MCP/edge implications, 8 practical and 8 exotic applications, and production roadmap. Gist is a full SEO-optimised public technical article with algorithm walkthrough, benchmark table, competitor comparison, optimization guide, and deep research notes with paper references. Real benchmark numbers (cargo run --release): Exact-f32 : 1,363 QPS, recall=1.0000, 2.44 MB PQ-4sub-64 : 7,388 QPS, recall=0.0490, 0.05 MB (build 237.6ms) RVQ-4s-64 : 6,311 QPS, recall=0.0585, 0.14 MB (build 1,370.6ms) Co-Authored-By: claude-flow <ruv@ruv.net> Claude-Session: https://claude.ai/code/session_01KDumUj8CDoyXgvneENUjgu
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
ruvector-rvq, a zero-dependency Rust crate providing Residual Vector Quantization (RVQ) and Product Quantization (PQ) as compressed approximate nearest-neighbour indices with ADC (Asymmetric Distance Computation) query-time lookup.What Changed
New crate:
crates/ruvector-rvqsrc/lib.rsVectorIndextrait,Hitstruct,recall_at_k,dot,l2_sq,nearest_centroid, stat helperssrc/dataset.rsDatasetConfig,Dataset::generate()(L2-normalised Gaussian unit vectors)src/kmeans.rssrc/exact.rsExactSearch)src/pq.rsPqIndex: M sub-spaces × K codewords, ADC search, memory accounting, unit testssrc/rvq.rsRvqIndex: S stages × K codewords residual encoding, reconstruct, reconstruction error, ADC search, unit testssrc/bin/benchmark.rsNew docs
docs/adr/ADR-273-rvq-compressed-ann.mddocs/research/nightly/2026-07-28-rvq-compressed-ann/README.mddocs/research/nightly/2026-07-28-rvq-compressed-ann/gist.mdBenchmark Results (measured)
N=5K, D=128, 4 sub-spaces/stages × 64 codewords, 8 k-means iters
RVQ recall is consistently ≥ PQ recall across D=32/64/128, with the gap widening at lower D. Reconstruction MSE decreases monotonically with stages (guaranteed by algorithm).
Test Plan
cargo build --release -p ruvector-rvqsucceedscargo test -p ruvector-rvq— 13/13 tests passcargo run --release -p ruvector-rvq --bin benchmark— all acceptance checks[PASS]cargo fmt -p ruvector-rvqappliedGenerated by Claude Code