vectra

vectra is a Python library for vector search: a vector database and indexing library built without any ANN dependencies, no FAISS, no wrappers around someone else's index. Given a set of embedding vectors, it supports both exact brute-force search and approximate nearest-neighbour search over an HNSW graph written entirely in NumPy, with cosine, Euclidean, and dot-product metrics on float32 data.

The public surface is a single VectorIndex class: batch add, search, lazy delete, rebuild, and metadata filtering through an inverted index, plus async and batched query paths. A command-line interface covers building, inspecting, and benchmarking indexes.

HNSW from scratch

The approximate index is the substantive part of the project. The graph implements the full Hierarchical Navigable Small World algorithm: random level assignment, greedy layer descent, best-first beam search at the base layer, and heuristic neighbour selection, with M, ef_construction, and ef_search exposed as tunable parameters. A per-query ef_search override lets callers trade recall for latency without rebuilding, and the included benchmark script measures the actual recall-latency-memory tradeoff on clustered data rather than quoting theoretical bounds.

Storage and quantization

Indexes persist to a custom sectioned binary format (.vdb) with a magic header, a section table, and separate regions for configuration, ids, raw vectors, an alive bitmask, metadata, quantization codes, and the serialized HNSW graph. VectorIndex.mmap() maps the vector section directly from disk, so large flat indexes can be searched without loading them into memory.

Two quantizers reduce footprint: a scalar quantizer compressing each dimension to a uint8 bin (roughly 4x smaller), and a product quantizer using learned k-means subquantizers. Both are implemented here, including the clustering.