RFC-008: Temporal Index Architecture
See full RFC: design/CVX_RFC_008_Temporal_Index_Architecture.md
Summary
Section titled “Summary”Three architectural improvements that transform CVX from a temporal vector index into a temporally-aware storage engine:
| Improvement | What it solves |
|---|---|
| Temporal LSH (T-LSH) | Eliminates the 4× over-fetch penalty for composite distance queries (α < 1.0) |
| Time-Partitioned Sharding | Sub-linear query latency on historical data via partition pruning |
| Streaming Window Index | High-throughput ingestion with hot buffer + compaction pipeline |
Current Bottlenecks
Section titled “Current Bottlenecks”-
Over-fetch penalty: When α < 1.0, HNSW is organized by semantic distance only — temporally relevant but semantically distant nodes are never explored. The 4× over-fetch is a heuristic with bounded recall.
-
O(N) filter bitmap:
build_filter_bitmap()iterates ALL timestamps on every temporally-filtered query. For 10M points, this is a 10M-iteration loop. -
No partition pruning: A query for “last 24 hours” traverses the same full HNSW graph as “last 10 years.”
Target Improvements
Section titled “Target Improvements”| Metric | Current | Target |
|---|---|---|
| ”Last 24h” on 1-year data | Full HNSW + 10M filter scan | 1 partition (~30K pts) |
| Composite distance recall@10 | ~70% (4× over-fetch) | ~90% (T-LSH multi-probe) |
| Write throughput | ~800 pts/sec | ~50K pts/sec (WAL + buffer) |
Key Designs
Section titled “Key Designs”T-LSH: Dual-Hash for Spatiotemporal Candidates
Section titled “T-LSH: Dual-Hash for Spatiotemporal Candidates”Hash function: h_ST(v, t) = h_sem(v) ⊕ h_time(t) — concatenates semantic random hyperplane bits with temporal bucket bits. The bit ratio matches α: for α=0.5, equal semantic/temporal bits.
Time-Partitioned Sharding
Section titled “Time-Partitioned Sharding”Fixed-duration partitions (default: 7 days), each with its own HNSW graph. Query routing prunes non-overlapping partitions. Hot → Warm → Cold lifecycle.
Streaming Window Index
Section titled “Streaming Window Index”Write-Ahead Log → Hot Buffer (flat brute-force) → Compacted HNSW (partitioned). Queries search both buffer and compacted index, merge results.
Implementation Plan
Section titled “Implementation Plan”3 phases:
feat/time-partitions(P0) —PartitionedTemporalHnsw, global entity index, parallel fan-out — 18 testsfeat/temporal-lsh(P1) — T-LSH auxiliary index, multi-probe query, α-adaptive bit allocation — 15 testsfeat/streaming-index(P2) — HotBuffer + compaction pipeline + TemporalIndexAccess — 13 tests
Status: All 3 phases implemented and merged. 46 total tests.
Benchmarks (eRisk, 10K points, D=768)
Section titled “Benchmarks (eRisk, 10K points, D=768)”| Metric | Result |
|---|---|
| Ingestion (ef=25) | 915 pts/sec |
| Ingestion (ef=200) | 482 pts/sec |
| Search latency (all time) | 0.35ms mean, 0.47ms p99 |
| Search latency (temporal filter) | 0.28-0.33ms mean |
| Temporal filter speedup | 10-20% faster than unfiltered |
See notebooks/T_Benchmark_Partitioned.ipynb for full results.