vecq-core 0.3.0

vecq-core 0.3.0

vecq-core 0.3.0 turns the library from a fixed 4-bit quantizer into a configurable-width quantization and search engine with five storage and serving modes. Same zero-dependency core, same deterministic output on every platform.

cargo add vecq-core

What's new

Configurable width, 5-bit default. VecqIndex::set_bits(4|5|6) picks the width per index. The 5-bit default is the sweet spot on real 768-dim embeddings: 4.78x compression at recall@10 0.979. 4-bit stays available for maximum squeeze and cascade search. 6-bit reaches residual-class recall while storing 25% less than residual mode. File format v1.5 records the width in the header.

Zero-copy views. VecqView::from_bytes serves queries straight from an mmap or any byte owner, with no payload copy. Map and parse takes about 64 microseconds at 12k vectors versus about 4.9 ms for a full load, and results are bit-identical to a loaded index.

Keyed API. add_keyed inserts or replaces under a stable u64 key, remove_keyed tombstones, and search_keyed queries by key, with compact, relabel, and multi-vectors per key. Format v1.3 persists the key map, so keys survive save and reload.

Cascade search. search_cascade runs a 2-bit prefilter then a 4-bit rescore. On 100k vectors it is up to 3.6x faster than a plain 4-bit scan at matched recall.

Residual mode. with_residual opt-in: two-pass 4-bit codes with exact-norm two-term scoring, for workloads where recall matters more than size (format v1.4).

Matryoshka-aware truncation. with_working_dim quantizes only the leading dims of Matryoshka-trained embeddings, cutting storage without cutting the useful signal.

x86_64 AVX2 path. Runtime-detected, bit-identical to the scalar and NEON paths, with 4-vector batching. Determinism holds across x86_64 and aarch64.

Upgrading

• VecqIndex::new now defaults to 5-bit width instead of 4-bit. Call set_bits(4) if you need the old default. Storage grows about 19% per vector and recall rises with it.
• Readers accept file formats v1 through v1.5. Existing files keep working. New writes use v1.5.

Numbers

Benchmark conditions and the full width matrix live in docs/BENCHMARK.md. Headline figures on real 768-dim embeddings: 4.78x compression at recall@10 0.979 (5-bit), 5.98x at 0.958 (4-bit), SQLite BLOB round-trip of 50k vectors in tens of milliseconds (see docs/SQLITE.md).

When to use vecq

Use it when you want embeddings on disk or in SQLite at a fraction of the size, with no training pass, no runtime dependencies, and identical results on every machine. Skip it when you need an ANN index over tens of millions of vectors; vecq is a brute-force scanner with SIMD kernels, and at that scale a graph index fits better.

Issues closed and pull requests merged

Issues: #22, #23, #24, #25, #26, #27, #28, #29, #31, #32, #39, #40

Pull requests: #30, #33, #34, #35, #36, #37, #38, #41, #42, #43, #44, #45, #46

Full changelog: https://github.com/codecoradev/vecq/blob/main/CHANGELOG.md