SurgeDB

The SIMD-powered, ultra-lightweight vector database for the Edge.

---

Why SurgeDB?

Most vector databases are designed for massive cloud clusters. SurgeDB is designed for efficiency.

• Ultra-Low Footprint: While production databases like Qdrant or Milvus often require 500MB+ just to idle, SurgeDB can index 100k vectors using only ~39MB of RAM (with SQ8).
• Edge Ready: Optimized specifically for Apple Silicon (NEON) and modern x86_64 (AVX-512).
• Zero Dependencies: Written in pure Rust. No Python runtime, no Docker containers required.

---

Features

• Adaptive HNSW Indexing: High-speed approximate nearest neighbor search.
• SIMD Optimized: Hand-tuned kernels for NEON (Apple Silicon) and AVX-512 (x86).
• Plug-and-Play Quantization:
  • SQ8: 4x compression with <1% accuracy loss.
  • Binary: 32x compression for massive datasets.
• ACID-Compliant Persistence: Write-Ahead Log (WAL) and Snapshots for crash-safe data.
• Mmap Support: Disk-resident vectors for datasets larger than RAM.
• Collections & Metadata: Manage multiple collections with rich JSON metadata.
• Metadata Filtering: Filter search results using structured queries (e.g., category == "books").
• HTTP Server: Built-in high-performance Axum server for easy deployment.

---

Architecture

SurgeDB uses a hybrid storage engine to balance speed and durability.

graph TD
    Client["Client / HTTP"] --> API["Axum API Layer"]
    API --> Engine["Core Vector Engine"]
    Engine --> HNSW["HNSW Index (RAM)"]
    Engine --> Storage{"Storage Backend"}
    Storage -->|Hot Data| WAL["Write-Ahead Log"]
    Storage -->|Cold Data| Mmap["Mmap Vectors (Disk)"]
    Storage -->|Recovery| Snap["Snapshots"]

Loading

---

Performance Snapshot

We validate every build for Recall (accuracy) and Latency across different vector sizes.

Heavy Workload (768 dim)

SurgeDB local benchmark on 5,000 vectors.

Operation	SurgeDB (Local)
Bulk Upsert (5k)	5.69 s
Search Avg	0.77 ms
Search Throughput	1,300 QPS

HNSW Accuracy & Recall

Measured on 2k vectors (128 dim) against exact brute-force truth.

Metric	Full Precision HNSW	SQ8 Quantized HNSW	Result
Top-10 Recall	99.20%	98.90%	Near Perfect

Standard Workload (128 dim)

Mode	Recall @ 10	Latency (Avg)	Compression
HNSW (In-Memory)	99.20%	0.14 ms	1x
SQ8 (Quantized)	98.90%	0.20 ms	3.76x
Binary (1-bit)	25.30%	0.02 ms	32.0x

Scaling Benchmarks (384 dim)

Dataset Size	Mode	Latency (Avg)	Throughput	Memory Usage
50,000 Vectors	HNSW	0.93 ms	1,080 QPS	~86.80 MB
100,000 Vectors	SQ8 (Indexed)	1.29 ms	776 QPS	~95.50 MB

Performance measured locally on February 4, 2026. HNSW provides sub-millisecond search at scale, while SQ8 offers significant memory savings.

Benchmark commands used:

cargo run --release -p surgedb-cli -- validate -c 2000 --dimensions 128 -k 10
cargo run --release -p surgedb-cli -- bench -c 5000 -d 768
cargo run --release -p surgedb-cli -- bench -c 50000 -d 384
cargo run --release -p surgedb-cli -- bench -c 100000 -d 384 -q sq8

---

Installation

🦀 Rust (Core)

Add SurgeDB to your Cargo.toml:

[dependencies]
surgedb-core = { git = "https://github.com/meet447/SurgeDB" }

📚 Clients & Bindings

For detailed installation, usage, and API references, please read the specific package guides:

• 🐍 Python: Read the Python Guide & Docs
• 🌐 JavaScript / WASM: Read the WASM Guide & Docs

---

Examples

Standalone examples for different SDKs can be found in the examples/ directory:

• Rust Basic Example
• Python Basic Example

---

Quick Start (WASM / Browser)

SurgeDB runs entirely in the browser using WebAssembly.

import init, { SurgeDB } from './pkg/surgedb_wasm.js';

async function run() {
    await init();
    
    // 1. Create DB
    const db = new SurgeDB(384);
    
    // 2. Insert
    db.insert("doc_1", new Float32Array([0.1, ...]), { title: "Hello" });
    
    // 3. Search
    const results = db.search(new Float32Array([0.1, ...]), 5);
    console.log(results);
}

---

Quick Start (Rust)

use surgedb_core::{PersistentVectorDb, PersistentConfig, DistanceMetric};

fn main() {
    // 1. Setup Persistent Database
    let config = PersistentConfig {
        dimensions: 384, // MiniLM size
        distance_metric: DistanceMetric::Cosine,
        ..Default::default()
    };
    let mut db = PersistentVectorDb::open("./surgedb_data", config).unwrap();

    // 2. Insert Vector with Metadata
    let vec = vec![0.1; 384];
    let meta = serde_json::json!({"title": "SurgeDB Guide"});
    db.insert("doc_1", &vec, Some(meta)).unwrap();

    // 3. Search
    let query = vec![0.1; 384];
    let results = db.search(&query, 5).unwrap();
    
    println!("Found match: {} (meta: {:?})", results[0].0, results[0].2);
}

---

HTTP Server

SurgeDB includes a high-performance HTTP server powered by Axum.

Start the Server

cargo run --release -p surgedb-server
# Server listening on 0.0.0.0:3000

API Usage

Create Collection

curl -X POST http://localhost:3000/collections \
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "docs", 
    "dimensions": 384,
    "quantization": "SQ8" 
  }'

Upsert Vector (Insert or Update)

curl -X POST http://localhost:3000/collections/docs/upsert \
  -H "Content-Type: application/json" \
  -d '{
    "id": "vec1",
    "vector": [0.1, 0.2, 0.3, ...],
    "metadata": { "category": "AI", "tags": ["fast"] }
  }'

Batch Upsert (Bulk)

curl -X POST http://localhost:3000/collections/docs/vectors/batch \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": [
      { "id": "vec1", "vector": [...], "metadata": {...} },
      { "id": "vec2", "vector": [...], "metadata": {...} }
    ]
  }'

Get Vector by ID

curl http://localhost:3000/collections/docs/vectors/vec1

List Vectors (Pagination)

curl "http://localhost:3000/collections/docs/vectors?offset=0&limit=10"

Delete Vector by ID

curl -X DELETE http://localhost:3000/collections/docs/vectors/vec1

Search

curl -X POST http://localhost:3000/collections/docs/search \
  -H "Content-Type: application/json" \
  -d '{ 
    "vector": [0.1, 0.2, 0.3, ...], 
    "k": 5,
    "filter": { "Exact": ["category", "AI"] }
  }'

Delete Collection

curl -X DELETE http://localhost:3000/collections/docs

---

CLI Usage

SurgeDB comes with a powerful CLI for benchmarking and validation.

# Run the validation suite (Recall & Latency)
cargo run --release -- validate

# Benchmark with 10k vectors + SQ8 compression
cargo run --release -- bench -c 10000 -q sq8

# Test persistence and recovery
cargo run --release -- persist

---

Roadmap

See ROADMAP.md for the detailed path to production.

• SIMD Distance Kernels (NEON/AVX)
• HNSW Algorithm
• SQ8 & Binary Quantization
• WAL & Snapshot Persistence
• Mmap Storage Backend
• Collections & Metadata Support
• Metadata Filtering (Exact, And, Or, Not)
• HTTP Server (Axum)
• UniFFI Bindings (Python, Swift, Kotlin)
• WASM / Browser Support (Edge)
• Zero-Config RAG Pipeline (Candle Integration)

License

Distributed under the MIT License. See LICENSE for more information.