GitHub - oneKn8/VectorVault: HNSW approximate nearest neighbor engine from scratch in C++20. AVX2 SIMD-accelerated distance computation, memory-mapped persistence, sub-millisecond queries at 100k vectors.

Features • Quick Start • Architecture • Benchmarks • API • Contributing

What is VectorVault?

VectorVault is a production-grade Approximate Nearest Neighbor (ANN) search engine implementing the HNSW algorithm with AVX2 SIMD optimizations. Built from scratch in modern C++20, it provides a lightweight, blazing-fast alternative to FAISS with a dead-simple REST API.

Perfect for:

Semantic search over embeddings
Recommendation systems
Image similarity search
Real-time vector retrieval at scale

// C++20 Modern API
HNSWIndex index(768);

// Add vectors
index.add(1, embedding);

// Search (SIMD accelerated)
auto results = index.search(
    query, 
    k=10, 
    ef_search=50
);
// Sub-millisecond latency

Features

Core Algorithm

Feature	Description
HNSW Graph	Hierarchical Navigable Small World for O(log N) search
SIMD Acceleration	AVX2 optimization - 8 floats per instruction
Thread-Safe	Lock-free reads with `shared_mutex`
Smart Caching	Memory-mapped snapshots with zero-copy
Reliability	Save/load parity guaranteed - deterministic top-k results

Production Features

graph LR
    A[REST API] --> B[HNSW Index]
    B --> C[SIMD Distance]
    C --> D[Memory Map]
    B --> E[Thread Pool]
    style A fill:#00d9ff
    style B fill:#ff6b6b
    style C fill:#4ecdc4
    style D fill:#ffe66d
    style E fill:#a8dadc

REST API - JSON interface on port 8080
Docker Ready - Multi-stage optimized builds
Auto-Scaling - Thread pool for parallel queries
Persistent - CRC32 validated snapshots
Cross-Platform - Linux and Windows support

Quick Start

Installation Options

Build from Source

# Clone the repo
git clone git@github.com:Sant0-9/VectorVault.git
cd VectorVault

# Build (takes ~30s)
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

# Run server
./build/vectorvault_api --port 8080 --dim 768

Docker (Recommended)

# Build image
docker build -t vectorvault -f docker/Dockerfile .

# Run with persistent storage
docker run -d \
  --name vectorvault \
  -p 8080:8080 \
  -v $(pwd)/data:/data \
  vectorvault --dim 384

# Add vectors and save index
curl -X POST http://localhost:8080/add \
  -H 'Content-Type: application/json' \
  -d '{"id": 1, "vec": [0.1, 0.2, ...]}'

curl -X POST http://localhost:8080/save \
  -H 'Content-Type: application/json' \
  -d '{"path": "/data/index.vv"}'

# Index persists in ./data/index.vv even after container restart

Custom dimensions:

docker run -p 8080:8080 \
  -v $(pwd)/data:/data \
  vectorvault --dim 768

Usage Examples

Adding Vectors

curl -X POST http://localhost:8080/add \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 1,
    "vec": [0.1, 0.2, 0.3, ...]
  }'

Response:

{
  "status": "ok",
  "id": 1
}

Searching

curl -X POST 'http://localhost:8080/query?k=10&ef=50' \
  -H 'Content-Type: application/json' \
  -d '{
    "vec": [0.15, 0.25, 0.35, ...]
  }'

Response:

{
  "results": [
    {"id": 1, "distance": 0.045},
    {"id": 42, "distance": 0.123}
  ],
  "latency_ms": 1.234
}

Python Client

Full client available in clients/python/

from vectorvault_client import VectorVaultClient
import numpy as np

# Connect to server
client = VectorVaultClient(host="localhost", port=8080)

# Add vectors
for i in range(1000):
    vec = np.random.randn(384).tolist()
    client.add(id=i, vec=vec)

# Search
query = np.random.randn(384).tolist()
results = client.search(vec=query, k=10, ef=50)

print(f"Found {len(results['results'])} in {results['latency_ms']:.2f}ms")

Installation:

cd clients/python
pip install -r requirements.txt
python3 example.py

See clients/python/README.md for full documentation.

Architecture

graph TB
    A[Client Request] -->|HTTP/JSON| B[REST API Layer]
    B -->|Add/Query| C[HNSW Index Core]
    C -->|Compute| D[SIMD Distance Engine]
    C -->|Store| E[Memory-Mapped Storage]
    C -->|Parallel| F[Thread Pool]
    
    D -->|AVX2| D1[8 floats/cycle]
    D -->|Fallback| D2[Scalar compute]
    
    E -->|Save| E1[CRC32 validated]
    E -->|Load| E2[Zero-copy mmap]
    
    style A fill:#00d9ff,color:#000
    style B fill:#ff6b6b,color:#fff
    style C fill:#4ecdc4,color:#000
    style D fill:#ffe66d,color:#000
    style E fill:#a8dadc,color:#000
    style F fill:#95e1d3,color:#000

HNSW Algorithm Visualization

Hierarchical layers: Sparse top for long jumps, dense bottom for precision

Layer 3 (Sparse)
Long-range connections for fast navigation

Layer 1 (Medium)
Mid-range hops between clusters

Layer 0 (Dense)
Precise local neighborhood search

Benchmarks

Query Performance vs Brute Force Baseline

Test Setup: Smoke Dataset (10k vectors, 384 dimensions) | Measured against exact brute-force search

Recall@10 vs Speed Trade-off

efSearch	P50 Latency	P95 Latency	QPS	Recall@10	vs Brute Force
10	0.18ms	0.32ms	~5,500	87.3%	45x faster
50	0.42ms	0.78ms	~2,400	96.8%	19x faster
100	0.71ms	1.24ms	~1,400	99.2%	11x faster
Brute	8.2ms	9.1ms	~122	100%	baseline

Recall@10 = Fraction of true top-10 neighbors found (vs exact brute-force search)

Key Insights:

ef=50 provides 97% recall with 19x speedup - ideal for production
ef=100 achieves 99% recall with 11x speedup - best for accuracy-critical apps
ef=10 gives 87% recall with 45x speedup - good for exploratory search

Larger Scale Performance

Test Setup: 100k vectors | 768 dimensions | AMD Ryzen 9 5950X (16 cores)

efSearch	P50 Latency	P95 Latency	P99 Latency	QPS	Recall@10	Quality
`10`	0.21ms	0.45ms	0.68ms	4,761	87%	Fast
`50`	0.54ms	1.12ms	1.58ms	1,852	97%	Balanced
`100`	0.89ms	1.76ms	2.34ms	1,124	99%	Accurate
`200`	1.45ms	2.89ms	3.67ms	690	99.7%	Precise

Build Performance

Dataset Size	Dimension	Build Time	Throughput	Memory
100k	384	8.2s	12,200/sec	~850 MB
100k	768	14.1s	7,100/sec	~1.5 GB
1M	384	98s	10,200/sec	~8.2 GB

Run Your Own Benchmarks

./scripts/run_bench.sh              # Run full benchmark suite
python3 scripts/plot_bench.py       # Generate plots
open bench/out/*.png                # View results

Quick Demo

# Start server
./build/vectorvault_api --port 8080 --dim 384

# Add a vector
curl -X POST http://localhost:8080/add \
  -H 'Content-Type: application/json' \
  -d '{"id": 1, "vec": [0.1, 0.2, 0.3, ...]}'
# {"status":"ok","id":1}

# Search
curl -X POST 'http://localhost:8080/query?k=5&ef=50' \
  -H 'Content-Type: application/json' \
  -d '{"vec": [0.15, 0.25, 0.35, ...]}'
# {"results":[{"id":1,"distance":0.045}],"latency_ms":0.234}

# Get stats
curl http://localhost:8080/stats
# {"dim":384,"size":1,"levels":0,"params":{...},"build":{...},"version":"0.1.0"}

Configuration

HNSW Parameters

Parameter	Default	Impact
M	`16`	Connections per node Higher = Better recall, more memory
ef_construction	`200`	Build quality Higher = Better index, slower build
ef_search	`50`	Query quality Higher = Better recall, slower search

Presets:

// Balanced (default)
M=16, efC=200, efSearch=50

// Speed-optimized
M=8, efC=100, efSearch=20

// Accuracy-optimized
M=32, efC=400, efSearch=200

Server Options

./build/vectorvault_api \
  --port 8080 \
  --dim 768 \
  --host 0.0.0.0

Environment Variables:

export VECTORVAULT_PORT=8080
export VECTORVAULT_DIM=768
export VECTORVAULT_LOG_LEVEL=info

Docker Compose:

services:
  vectorvault:
    image: vectorvault
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data
    environment:
      - VECTORVAULT_DIM=1536

API Reference

POST /add - Add vector to index

Request:

{
  "id": 123,
  "vec": [0.1, 0.2, 0.3, ...]
}

Response:

{
  "status": "ok",
  "id": 123
}

Error Codes:

400 - Invalid vector dimension
409 - ID already exists
500 - Internal error

POST /query - Search for nearest neighbors

Parameters:

k (int) - Number of results [1-1000]
ef (int) - Search quality [10-500]

Request:

{
  "vec": [0.1, 0.2, 0.3, ...]
}

Response:

{
  "results": [
    {"id": 123, "distance": 0.045}
  ],
  "latency_us": 1234,
  "latency_ms": 1.234
}

POST /save & /load - Persistence

Save Request:

{"path": "/data/index.vv"}

Load Request:

{"path": "/data/index.vv"}

Response:

{
  "status": "ok",
  "path": "/data/index.vv",
  "size": 1000000
}

GET /stats - Index statistics

Request:

curl http://localhost:8080/stats

Response:

{
  "dim": 768,
  "size": 1000000,
  "levels": 6,
  "params": {
    "M": 16,
    "efConstruction": 200,
    "efDefault": 50,
    "maxM": 16,
    "maxM0": 32,
    "metric": "L2"
  },
  "build": {
    "compiler": "GCC",
    "compiler_version": "11.4.0",
    "build_type": "Release",
    "flags": ["AVX2"]
  },
  "version": "1.0.0"
}

GET /health - Health check

Response:

{
  "status": "ok",
  "uptime_seconds": 3600
}

Development

Prerequisites

CMake 3.22+
C++20 compiler (GCC 10+, Clang 12+, MSVC 2019+)
AVX2 CPU (optional, auto-detected)

Build & Test

Debug Build

cmake -B build -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_CXX_FLAGS="-fsanitize=address"
  
cmake --build build -j

Run Tests

cd build
ctest --output-on-failure

# Specific test
./vectorvault_tests --gtest_filter="HNSW*"

Code Quality

# Format code (clang-format)
cmake --build build --target format

# Static analysis (clang-tidy)
cmake --build build --target tidy

# Check coverage
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON
cmake --build build
cd build && ctest
gcovr -r .. --html --html-details -o coverage.html

Performance Comparison

	VectorVault	FAISS	hnswlib	Milvus	Weaviate
Algorithm	HNSW	Multi	HNSW	Multi	HNSW
Language	C++20	C++	C++11	Go/C++	Go
REST API	Native	None	None	Yes	Yes
SIMD	AVX2	Yes	Yes	Yes	None
Docker	Yes	None	None	Yes	Yes
Memory Map	Yes	Yes	None	Yes	None
Size	Tiny	Large	Tiny	Medium	Medium
Setup Time	30s	5min	1min	15min	10min

Contributing

Report Bug

Open Issue

Found a bug? Let us know.

Request Feature

Open Discussion

Have an idea? Share it.

Submit PR

Pull Request

Code ready? Send it.

Quick Start:

# Fork & clone
git clone git@github.com:YOUR_USERNAME/VectorVault.git

# Create branch
git checkout -b feature/amazing-feature

# Make changes, test, commit
git commit -m "feat: add amazing feature"

# Push & create PR
git push origin feature/amazing-feature

See CONTRIBUTING.md for detailed guidelines.

License

MIT License

Copyright (c) 2025 Sant0-9

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...

Full license: LICENSE

Acknowledgments

HNSW Algorithm

Malkov & Yashunin, 2018

Original paper

Inspiration

FAISS • hnswlib

Meta AI & NMSLib

Modern C++

C++20 Standard

Concepts, Ranges, Modules

Author

Sant0-9

Built for Speed • Designed for Scale • Ready for Production

_{If you find this project useful, please give it a star}

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github/workflows		.github/workflows
.meta		.meta
api		api
bench		bench
clients/python		clients/python
cmake		cmake
docker		docker
include/vectorvault		include/vectorvault
scripts		scripts
src		src
tests		tests
.clang-format		.clang-format
.clang-tidy		.clang-tidy
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
CONTRIBUTING.md		CONTRIBUTING.md
IMPLEMENTATION_STATUS.md		IMPLEMENTATION_STATUS.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
VERSION		VERSION

Folders and files

Latest commit

History

Repository files navigation

What is VectorVault?

Features

Quick Start

Installation Options

Build from Source

Docker (Recommended)

Usage Examples

Adding Vectors

Searching

Python Client

Architecture

HNSW Algorithm Visualization

Benchmarks

Recall@10 vs Speed Trade-off

Run Your Own Benchmarks

Quick Demo

Configuration

HNSW Parameters

Server Options

API Reference

Development

Prerequisites

Build & Test

Code Quality

Performance Comparison

Contributing

Report Bug

Request Feature

Submit PR

License

Acknowledgments

Author

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages