VectorIndex

VectorIndex is a from-scratch C++ vector similarity search engine. It implements a shared index interface with brute-force exact search, IVF clustering, and HNSW graph search, plus a small benchmark harness for recall-vs-throughput experiments.

This project intentionally does not wrap FAISS, Annoy, hnswlib, or another ANN library. The index data structures are implemented here.

Quickstart

cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failure
./build/vectorindex_bench --vectors 10000 --queries 100 --dims 128 --k 10

Benchmark CSV is written to benchmark_results.csv by default. Generate a plot with:

python3 bench/plot_results.py benchmark_results.csv docs/benchmark_qps_recall.png

Implemented Indexes

Index	Search type	Main knobs	Notes
Brute force	Exact	metric	Correctness oracle and ground-truth generator
IVF	Approximate	nlist, nprobe	K-means centroids plus inverted lists
HNSW	Approximate	M, efConstruction, efSearch	Layered navigable small-world graph with lazy deletion

Project Layout

include/vectorindex/   Public C++ API
src/                   Index implementations
bench/                 Synthetic datasets, ground truth, CSV benchmark runner
tests/                 Dependency-free correctness tests
docs/                  Architecture, algorithm notes, benchmark notes

Current Scope

The current implementation is a solid educational vector index core: it supports insertion, search, lazy deletion, binary save/load for all three index types, synthetic benchmarks, and correctness tests against brute force. It is not yet a production database server: there is no WAL, mmap loading, network API, or concurrent mutation layer.