research(nightly): semantic-query-cache — cosine-similarity cache for agent memory workloads (ADR-298)

[ruvnet]

Summary

• Adds crates/ruvector-semantic-cache: a zero-dependency Rust crate implementing a semantic cache layer that maps (query_vector → result_ids) and detects cache hits via cosine similarity, enabling AI agents to skip redundant vector searches when they re-ask semantically identical questions with slightly different wording.
• Two production-relevant backends: LinearScanCache (O(C·D), optimal for C < 1 000) and ShardedCache (6-bit multi-probe LSH, O(7·C/64·D), suitable for C up to ~50 000), both implementing the QueryCache trait.
• Real benchmark results (N=10 000 base vectors, D=128, 50 clusters, 500 queries, k=10, threshold=0.92): LinearCache 90.0% hit rate / 9.5× speedup; ShardedCache 85.6% hit rate / 6.7× speedup — all 6 acceptance criteria PASS.
• Adds docs/adr/ADR-298-semantic-query-cache.md and full nightly research document under docs/research/nightly/2026-08-09-semantic-query-cache/.

What changed

New crate: crates/ruvector-semantic-cache

File	Purpose
src/lib.rs	QueryCache trait, NoCache baseline, dot() / normalize() utilities
src/linear.rs	LinearScanCache: exhaustive cosine scan with FIFO eviction and TTL
src/sharded.rs	ShardedCache: 6-bit LSH projection, multi-probe (primary + 6 one-bit-flip neighbors)
src/metrics.rs	CacheStats with Cell<u64> interior mutability (single-threaded / WASM-safe)
src/dataset.rs	Deterministic clustered dataset generator (LCG RNG, Box-Muller Gaussian, brute-force top-k)
src/bin/benchmark.rs	Three-variant benchmark with real acceptance thresholds; exits 1 on failure

Design choices

• Pre-normalized vectors: cosine similarity reduces to a dot product — no sqrt per comparison.
• TTL via monotonic u64 tick counter: avoids SystemTime so the crate compiles to WASM without shims.
• Recall tradeoff documented: cached hits return results from a prior similar query, not the exact query; mean recall ≈ 0.744 at 90% hit rate is inherent and documented as an acceptance floor (≥ 0.60), not a target.
• No external dependencies: pure Rust stdlib; compiles alongside all existing RuVector crates without dependency conflicts.

Documentation

• docs/adr/ADR-298-semantic-query-cache.md — context, decision, consequences, alternatives, benchmark evidence, failure modes, security considerations, migration path.
• docs/research/nightly/2026-08-09-semantic-query-cache/README.md — full research document with SOTA survey, forward-looking thesis, ecosystem fit analysis, architecture diagram, performance math, and next steps.
• docs/research/nightly/2026-08-09-semantic-query-cache/gist.md — SEO-optimized public article with comparison against 9 vector databases and practical + exotic application tables.

Test plan

• cargo test -p ruvector-semantic-cache — 21 tests, 0 failures
• cargo build --release -p ruvector-semantic-cache — clean build, 0 warnings (except dead_code on public API surface)
• cargo run --release -p ruvector-semantic-cache --bin benchmark — all 6 acceptance criteria PASS:
  • LinearCache hit rate ≥ 80%: PASS (90.0%)
  • ShardedCache hit rate ≥ 70%: PASS (85.6%)
  • LinearCache mean recall ≥ 60%: PASS (0.744)
  • ShardedCache mean recall ≥ 60%: PASS (0.757)
  • LinearCache speedup ≥ 3×: PASS (9.50×)
  • ShardedCache speedup ≥ 3×: PASS (6.65×)

---

Generated by Claude Code