Skip to content

feat(brain): vecq as opt-in vector backend for v0.15.0 (replace usearch long-term) #542

Description

@ajianaz

Context

Audit of codecoradev/vecq v0.1.1 (training-free 4-bit quantization, pure Rust, zero deps, Apache-2.0, same org) shows a strong fit for Brain Mode's vector index. Their benchmark (aarch64, 2k vectors, 768-dim, real EmbeddingGemma embeddings):

engine build ms/query recall@10 bytes/vector
vecq 4-bit 64 ms 0.89 0.961 514 (5.98x)
usearch f32 HNSW 893 ms 0.23 0.995 3,072

Wins: build 14x faster (helps cora index), 6x smaller index, bit-identical deterministic results, kills the vendored C++ FFI. Losses: ~8x slower per query (brute-force scan vs ANN graph — still sub-ms at cora's typical scale), recall delta washes out in Brain's RRF fusion (FTS5 + vector + graph, k=60). Caveat: headline numbers are aarch64/NEON; x86_64 still runs the scalar path.

Proposal (v0.15.0)

Add brain.embedding: vecq as a third runtime backend next to auto | hashing | pretrained (seam exists since v0.13.0). Default stays on the current backend; flip the default only after a soak release.

Integration gaps to close first (tracked in vecq):

  • Keyed insert/remove by symbol id — vecq#10 (main blocker; today VecqIndex is positional, append-only; cora needs remove + i64 keys. Wrapper options: tombstones + compact-on-save, or rebuild from the symbols table — 64 ms/2k vectors makes rebuild viable)
  • x86_64 AVX2 scoring path — vecq#11 (perf on CI/dev hardware)
  • Canonical SQLite BLOB storage pattern — vecq#12 (would retire the sidecar .usearch file and the documented ATTACH pitfall)

Plan

  1. Wait for vecq#10; contribute upstream if helpful
  2. Implement vecq backend behind config: CodeVectorIndex adapter (key mapping + tombstone/rebuild), persistence via to_bytes()
  3. Bench on real cora indexes (hashing 256d + pretrained 768d), compare recall/latency vs usearch
  4. Ship as opt-in in v0.15.0, soak, then revisit the default

Effort estimate: 1–2 days after vecq#10 lands.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions