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

v0.2.0

No changelog entry found for 0.2.0.

v0.1.1

vecq-core 0.1.1

First public release of vecq on crates.io. vecq is a training-free 4-bit vector quantization and search library written in pure Rust with zero dependencies, built for on-device and edge workloads where index size and build simplicity matter more than last-millisecond latency.

[dependencies]
vecq-core = "0.1.1"

Highlights

• 4-bit quantization, no training - quantize float32 vectors to 4-bit codes with no calibration dataset, no training pass, no model artifacts. Add vectors, search, persist, load.
• 6x smaller index - 514 bytes per 768-dim vector vs 3072 bytes for f32 (5.98x compression).
• Zero dependencies - cargo add vecq-core pulls exactly one crate. No C++ toolchain, no transitive deps, compiles anywhere Rust does.
• Deterministic results - bit-identical rankings across every ARM64 device (no FMA contraction, no platform-dependent reordering).
• ARM64 NEON path - 4-vector batch scoring with bounded-heap top-k for flat, predictable scan latency.

Benchmark

768-dim EmbeddingGemma embeddings, 2000 index vectors, 100 queries, ARM64. Full methodology in docs/BENCHMARK.md.

Metric	vecq	f32 brute force	usearch
Bytes per vector	514	3072	-
Compression	5.98x	1x	-
Query latency	0.89 ms	-	0.23 ms
Recall@10	0.958	1.000	0.995

What's Changed

Added

• Release pipeline: push a vX.Y.Z tag on main to publish vecq-core to crates.io, verify the version via the crates.io API, and create the GitHub Release.

Full changelog: v0.1.0...v0.1.1

When to use vecq

Use it when the index lives on-device, dimensions are a few hundred to a thousand, the corpus is in the tens of thousands, and you value small files and simple builds. For server-side workloads at scale, use a full ANN index (Qdrant, usearch) and keep vecq for the edge.

v0.1.0

What's Changed

• docs: public readiness — Apache-2.0, governance, CI, packaging by @ajianaz in #1
• release: v0.1.0 public readiness by @ajianaz in #5

Full Changelog: https://github.com/codecoradev/vecq/commits/v0.1.0