research(nightly): semantic-query-cache — skip near-duplicate ANN calls in agentic workloads

[ruvnet]

Summary

Adds the 2026-08-10 nightly RuVector research: semantic query cache for ANN search (ruvector-semantic-cache).

Agentic workloads generate near-duplicate query embeddings (cosine sim > 0.97) in rapid succession — an agent revisiting the same topic with slightly different phrasing pays full ANN cost on every call. This crate intercepts those redundant calls before they reach the vector index.

• 40% hit rate on a 40%-near-duplicate topic-local workload
• 65% throughput gain (757 → 1251 QPS)
• 39% mean latency reduction (1321 µs → 800 µs)
• 97.3% recall@1 on cache hits (threshold = 0.97)
• Zero external Rust dependencies; WASM-compatible

Changes

New crate: crates/ruvector-semantic-cache

Three variants under a common SemanticCache trait:

Variant	Strategy	Status
ExactCache	Bit-identical hash match (baseline)	✓
LinearCache	Cosine scan, fixed threshold, ring-buffer	✓
AdaptiveCache	Self-tuning cosine threshold (FP-rate controller)	✓

19 unit tests pass. Benchmark binary produces real numbers from a deterministic synthetic workload.

Documentation

• docs/research/nightly/2026-08-10-semantic-query-cache/README.md — full research document
• docs/adr/ADR-298-semantic-query-cache.md — architecture decision record
• docs/research/nightly/2026-08-10-semantic-query-cache/gist.md — SEO-optimised public article

Workspace

• Added ruvector-semantic-cache to workspace members in Cargo.toml

Benchmark Evidence

cargo run --release -p ruvector-semantic-cache --bin benchmark

Variant	Hit rate	Recall@1	Mean µs	QPS	Result
ExactCache (baseline)	0.0%	1.000	1321.3	757	PASS ✓
LinearCache (0.97)	40.0%	0.973	802.8	1246	PASS ✓
AdaptiveCache (0.95)	40.0%	0.973	799.4	1251	PASS ✓

x86_64 Linux, 10 000 × 128-dim dataset, 1000 queries (40% near-dup), cache cap = 64.

Ecosystem Connections

• ruvector-agent-memory — primary integration target (wrap ANN search with LinearCache)
• ruvector-speculative-ann — complementary: reduces per-miss cost; cache reduces miss frequency
• WASM / Cognitum edge — zero deps, ~40 KB RAM at N=64 entries
• ruFlo — on_session_start cache warm-up hook (future ADR)
• MCP — vector/cache/stats tool surface (future ADR)

Test Plan

• cargo build --release -p ruvector-semantic-cache — clean
• cargo test -p ruvector-semantic-cache — 19/19 passed
• cargo run --release -p ruvector-semantic-cache --bin benchmark — ALL TESTS PASSED
• No secrets committed
• All files under 500 lines

---

Generated by Claude Code