Crate edgevec

Source

Expand description

§EdgeVec

High-performance embedded vector database for Browser, Node, and Edge.

§Current Status

PHASE 3: Implementation (Week 7 Complete)

Status: Week 7 Complete — Persistence Hardened

Core vector storage, HNSW graph indexing, and full durability (WAL + Snapshots) are implemented and verified.

§Implemented Features

HNSW Graph: Full insertion and search implementation with heuristic optimization.
Vector Storage: Contiguous memory layout for fast access.
Scalar Quantization (SQ8): 4x memory reduction (f32 -> u8) with high accuracy.
Durability: Write-Ahead Log (WAL) with CRC32 checksums, crash recovery, and atomic snapshots.
Metrics: L2 (Euclidean), Cosine, and Dot Product distance functions.

§Development Protocol

EdgeVec follows a military-grade development protocol:

Architecture Phase — Design docs must be approved before planning
Planning Phase — Roadmap must be approved before coding
Implementation Phase — Weekly tasks must be approved before coding
All gates require HOSTILE_REVIEWER approval

§Example

use edgevec::{HnswConfig, HnswIndex, Metric, VectorStorage};

// 1. Create Config
let config = HnswConfig::new(128);

// 2. Initialize Storage and Index
let mut storage = VectorStorage::new(&config, None);
let mut index = HnswIndex::new(config, &storage).expect("failed to create index");

// 3. Insert Vectors
let vector = vec![0.5; 128];
let id = index.insert(&vector, &mut storage).expect("failed to insert");

// 4. Search
let query = vec![0.5; 128];
let results = index.search(&query, 10, &storage).expect("failed to search");

assert!(!results.is_empty());
assert_eq!(results[0].vector_id, id);

§Persistence Example

use edgevec::{HnswConfig, HnswIndex, VectorStorage};
use edgevec::persistence::{write_snapshot, read_snapshot, MemoryBackend};

// Create index and storage
let config = HnswConfig::new(128);
let mut storage = VectorStorage::new(&config, None);
let mut index = HnswIndex::new(config, &storage).expect("failed to create");

// Save snapshot using storage backend
let mut backend = MemoryBackend::new();
write_snapshot(&index, &storage, &mut backend).expect("failed to save");

// Load snapshot
let (loaded_index, loaded_storage) = read_snapshot(&backend).expect("failed to load");

§Next Steps (Phase 5)

Documentation: Finalize API docs.
NPM Package: Release to npm registry.
Performance: Final tuning and benchmarks.

§Documentation

§🚀 `EdgeVec`

High-performance vector search for Browser, Node, and Edge

✅ STATUS: Alpha Release Ready — All performance targets exceeded.

§What’s New in v0.4.0

§Documentation & Quality Sprint

docs/TUTORIAL.md — Complete getting started guide
docs/PERFORMANCE_TUNING.md — HNSW parameter optimization
docs/TROUBLESHOOTING.md — Top 10 errors and solutions
docs/INTEGRATION_GUIDE.md — Third-party embedding integrations
docs/MIGRATION.md — Migration from hnswlib, FAISS, Pinecone

§Benchmark Dashboard

Interactive visualization at /wasm/examples/benchmark-dashboard.html
EdgeVec vs hnswlib-node vs voy comparison
Real-time performance charts with Chart.js

§Quality Infrastructure

Chaos Testing — 15 edge case tests (empty index, max dimensions, etc.)
Load Testing — 100k vector stress tests, sustained search load
P99 Latency Tracking — P50/P99/P999 percentile benchmarks
CI Regression Detection — 10% threshold enforcement

§Previous (v0.3.0)

Soft delete API with O(1) tombstone-based deletion
Compaction API for reclaiming space
Full WASM bindings for soft delete operations
Persistence format v0.3 with automatic migration

§What is `EdgeVec`?

EdgeVec is an embedded vector database built in Rust with first-class WASM support. It’s designed to run anywhere: browsers, Node.js, mobile apps, and edge devices.

§Key Features

Sub-millisecond search — 0.23ms at 100k vectors (768d, quantized)
HNSW Indexing — O(log n) approximate nearest neighbor search
Scalar Quantization (SQ8) — 3.6x memory compression
WASM-First — Native browser support via WebAssembly
Persistent Storage — IndexedDB in browser, file system elsewhere
Minimal Dependencies — No C compiler required, WASM-ready
Tiny Bundle — 227 KB gzipped (55% under 500KB target)

§Quick Start

§Installation

npm install edgevec

For Rust users: To achieve optimal performance, ensure your .cargo/config.toml includes:

[build]
rustflags = ["-C", "target-cpu=native"]

Without this configuration, performance will be 60-78% slower due to missing SIMD optimizations.

§Browser/Node.js Usage

import init, { EdgeVec, EdgeVecConfig } from 'edgevec';

async function main() {
    // 1. Initialize WASM (required once)
    await init();

    // 2. Create Config and Index
    const config = new EdgeVecConfig(128);  // 128 dimensions
    config.metric = 'cosine';  // Optional: 'l2', 'cosine', or 'dot'
    const index = new EdgeVec(config);

    // 3. Insert Vectors
    const vector = new Float32Array(128).fill(0.1);
    const id = index.insert(vector);
    console.log(`Inserted vector with ID: ${id}`);

    // 4. Search
    const query = new Float32Array(128).fill(0.1);
    const results = index.search(query, 10);
    console.log("Results:", results);
    // Results: [{ id: 0, score: 0.0 }, ...]

    // 5. Save to IndexedDB (browser) or file system
    await index.save("my-vector-db");
}

main().catch(console.error);

§Load Existing Index

import init, { EdgeVec } from 'edgevec';

await init();
const index = await EdgeVec.load("my-vector-db");
const results = index.search(queryVector, 10);

§Rust Usage

use edgevec::{HnswConfig, HnswIndex, VectorStorage};
use edgevec::persistence::{write_snapshot, MemoryBackend};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Create Config & Storage
    let config = HnswConfig::new(128);
    let mut storage = VectorStorage::new(&config, None);

    // 2. Create Index
    let mut index = HnswIndex::new(config, &storage)?;

    // 3. Insert Vectors
    let vec1 = vec![1.0; 128];
    let _id1 = index.insert(&vec1, &mut storage)?;

    // 4. Search
    let query = vec![1.0; 128];
    let results = index.search(&query, 10, &storage)?;
    println!("Found {} results", results.len());

    // 5. Save Snapshot
    let mut backend = MemoryBackend::new();
    write_snapshot(&index, &storage, &mut backend)?;

    Ok(())
}

§Batch Insert (Rust)

For inserting many vectors efficiently, use the batch insert API:

use edgevec::{HnswConfig, HnswIndex, VectorStorage};
use edgevec::batch::BatchInsertable;
use edgevec::error::BatchError;

fn main() -> Result<(), BatchError> {
    let config = HnswConfig::new(128);
    let mut storage = VectorStorage::new(&config, None);
    let mut index = HnswIndex::new(config, &storage).unwrap();

    // Prepare vectors as (id, data) tuples
    let vectors: Vec<(u64, Vec<f32>)> = (1..=1000)
        .map(|i| (i as u64, vec![i as f32; 128]))
        .collect();

    // Batch insert with progress tracking
    let ids = index.batch_insert(vectors, &mut storage, Some(|inserted, total| {
        println!("Progress: {}/{}", inserted, total);
    }))?;

    println!("Inserted {} vectors", ids.len());
    Ok(())
}

Features: Progress tracking, best-effort semantics, and unified error handling.

§Soft Delete (Rust)

Delete vectors without rebuilding the index (v0.3.0+):

use edgevec::{HnswConfig, HnswIndex, VectorStorage};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = HnswConfig::new(128);
    let mut storage = VectorStorage::new(&config, None);
    let mut index = HnswIndex::new(config, &storage)?;

    // Insert a vector
    let vector = vec![1.0; 128];
    let id = index.insert(&vector, &mut storage)?;

    // Soft delete (O(1) operation)
    let was_deleted = index.soft_delete(id)?;
    println!("Deleted: {}", was_deleted);

    // Check deletion status
    println!("Is deleted: {}", index.is_deleted(id)?);

    // Get statistics
    println!("Live: {}, Deleted: {}", index.live_count(), index.deleted_count());
    println!("Tombstone ratio: {:.1}%", index.tombstone_ratio() * 100.0);

    // Compact when tombstones accumulate (rebuilds index)
    if index.needs_compaction() {
        let (new_index, new_storage, result) = index.compact(&mut storage)?;
        println!("Removed {} tombstones", result.tombstones_removed);
        // Use new_index and new_storage for future operations
    }

    Ok(())
}

§Soft Delete (JavaScript)

import init, { EdgeVec, EdgeVecConfig } from 'edgevec';

await init();
const config = new EdgeVecConfig(128);
const index = new EdgeVec(config);

// Insert vectors
const vector = new Float32Array(128).fill(0.5);
const id = index.insert(vector);

// Soft delete
const wasDeleted = index.softDelete(id);
console.log('Deleted:', wasDeleted);

// Statistics
console.log('Live:', index.liveCount());
console.log('Deleted:', index.deletedCount());
console.log('Tombstone ratio:', index.tombstoneRatio());

// Compact when needed
if (index.needsCompaction()) {
    const result = index.compact();
    console.log(`Removed ${result.tombstones_removed} tombstones`);
}

Operation	Time Complexity	Notes
`soft_delete()`	O(1)	Set tombstone byte
`is_deleted()`	O(1)	Read tombstone byte
`search()`	O(log n)	Automatically excludes tombstones
`compact()`	O(n log n)	Full index rebuild

§Interactive Examples

Try EdgeVec directly in your browser with our NVIDIA-grade cyberpunk demo suite:

View All Examples | Launch Dashboard

§Demo Gallery

Performance Dashboard

Competitive analysis vs hnswlib-node & voy with interactive Chart.js visualizations

Soft Delete & Compaction

RFC-001 implementation with tombstone visualization and real-time metrics

Batch Insert

Sequential vs batch comparison with progress tracking

Stress Test

Push EdgeVec to its limits with continuous operations

§Running Locally

# Clone the repository
git clone https://github.com/matte1782/edgevec.git
cd edgevec

# IMPORTANT: Start server from project root!
python -m http.server 8080

# Open in browser (include full path)
# http://localhost:8080/wasm/examples/index.html

⚠️ Note: Do NOT start server from wasm/examples/ — WASM module requires /pkg/ access from root.

§Development Status

EdgeVec follows a military-grade development protocol. No code is written without an approved plan.

§✅ Alpha Release Ready (v0.1.0)

All Performance Targets Exceeded:

✅ Search Mean: 0.23ms (4.3x under 1ms target)
✅ Search P99 (estimated): <600µs (based on Mean + 2σ)
✅ Memory: 832 MB for 1M vectors (17% under 1GB target)
✅ Bundle Size: 227 KB (55% under 500KB target)

What Works Now:

✅ HNSW Indexing — Sub-millisecond search at 100k scale
✅ Scalar Quantization (SQ8) — 3.6x memory reduction
✅ SIMD Optimization — AVX2/FMA for 60-78% speedup
✅ Crash Recovery (WAL) — Log-based replay
✅ Atomic Snapshots — Safe background saving
✅ Browser Integration — WASM Bindings + IndexedDB
✅ npm Package — edgevec@0.4.0 published

Development Progress:

Phase 0: Environment Setup — ✅ COMPLETE
Phase 1: Architecture — ✅ COMPLETE
Phase 2: Planning — ✅ COMPLETE
Phase 3: Implementation — ✅ COMPLETE
Phase 4: WASM Integration — ✅ COMPLETE
Phase 5: Alpha Release — ✅ READY

§Future Roadmap (v0.5.0+)

ARM/NEON Optimization — Cross-platform SIMD verification
Mobile Support — iOS Safari and Android Chrome formalized
CLI Tools — Optional developer command-line interface
Enhanced Metadata Storage — Native metadata support

§Path to v1.0

EdgeVec will reach v1.0 after:

Production usage feedback from v0.4.0/v0.5.0
Security audit
API stability guarantee commitment

§📊 Performance (Alpha Release)

§Search Latency (768-dimensional vectors, k=10)

Scale	Float32	Quantized (SQ8)	Target	Status
10k vectors	203 µs	88 µs	<1 ms	✅ 11x under
50k vectors	480 µs	167 µs	<1 ms	✅ 6x under
100k vectors	572 µs	329 µs	<1 ms	✅ 3x under

Note: Mean latencies from Criterion benchmarks (10 samples). Max observed: 622µs (100k Float32). Outliers: 0-20% (mostly high mild/severe). P99 estimates are all <650µs. See docs/benchmarks/ for full analysis.

§Memory Efficiency (768-dimensional vectors)

Mode	Memory per Vector	1M Vectors	Compression
Float32	3,176 bytes	3.03 GB	Baseline
Quantized (SQ8)	872 bytes	832 MB	3.6x smaller

Memory per vector includes: vector storage + HNSW graph overhead (node metadata + neighbor pool). Measured using index.memory_usage() + storage.memory_usage() after building 100k index.

§Bundle Size

Package	Size (Gzipped)	Target	Status
`edgevec@0.4.0`	227 KB	<500 KB	✅ 55% under

§Competitive Comparison (10k vectors, 128 dimensions)

Library	Search P50	Insert P50	Type	Notes
EdgeVec	0.20ms	0.83ms	WASM	Fastest WASM solution
hnswlib-node	0.05ms	1.56ms	Native C++	Requires compilation
voy	4.78ms	0.03ms	WASM	KD-tree, batch-only

EdgeVec is 24x faster than voy for search while both are pure WASM. Native bindings (hnswlib-node) are faster but require C++ compilation and don’t work in browsers.

Full competitive analysis →

§Key Advantages

✅ Sub-millisecond search at 100k scale
✅ Fastest pure-WASM solution — 24x faster than voy
✅ Zero network latency — runs 100% locally (browser, Node, edge)
✅ Privacy-preserving — no data leaves the device
✅ Tiny bundle — 227 KB gzipped
✅ No compilation required — unlike native bindings

§Test Environment

Hardware: AMD Ryzen 7 5700U, 16GB RAM
OS: Windows 11
Rust: 1.94.0-nightly (2025-12-05)
Criterion: 0.5.x
Compiler flags: -C target-cpu=native (AVX2 SIMD enabled)

Full benchmarks →

§Development Protocol

§The Agents

Agent	Role
META_ARCHITECT	System design, data layouts
PLANNER	Roadmaps, weekly task plans
`RUST_ENGINEER`	Core Rust implementation
`WASM_SPECIALIST`	WASM bindings, browser integration
`BENCHMARK_SCIENTIST`	Performance testing
HOSTILE_REVIEWER	Quality gate (has veto power)
DOCWRITER	Documentation, README

§Development Environment

§Local CI Simulation

Before pushing changes, run the local CI simulation to catch issues:

# Run full CI check with timing validation
cargo xtask ci-check

# Run pre-release validation (CI + docs + publish dry-run)
cargo xtask pre-release

The ci-check command:

Sets CI environment variables (RUSTFLAGS, PROPTEST_CASES, NUM_VECTORS)
Runs formatting, clippy, tests, and WASM checks
Validates each step completes within CI timeout limits

Timing Budgets (xtask / CI timeout):

Step	Local Limit	CI Timeout	Typical
Formatting	30s	5min	<1s
Clippy	180s	10min	~20s
Tests	600s	30min	~50s
WASM Check	120s	10min	<1s

If a step exceeds its local limit, the build fails to catch performance regressions before CI.

§Environment Variables

Variable	Local Default	CI Value	Purpose
`RUSTFLAGS`	(native)	`-C target-cpu=x86-64-v2`	Prevent SIGILL on CI runners
`PROPTEST_CASES`	256	32	Reduce proptest runtime
`NUM_VECTORS`	10000	1000	Reduce integration test runtime

§Building

# Standard build
cargo build --release

# WASM build
wasm-pack build --release

# Run tests
cargo test --all

# Run benchmarks
cargo bench

§Release Process

See CONTRIBUTING.md for the full release process, including:

§Origins

EdgeVec builds upon lessons learned from binary_semantic_cache, a high-performance semantic caching library. Specifically:

Salvaged (MIT Licensed):

Hamming distance implementation (~10 lines)
Binary quantization math (~100 lines)

Built Fresh:

HNSW graph indexing
WASM-native architecture
IndexedDB persistence
Everything else

§Acknowledgments

Thanks to the Reddit community for identifying a potential alignment issue in the persistence layer, which led to improved safety via bytemuck in v0.2.1.
Thanks to the Hacker News community for feedback on competitive positioning and benchmarking.

§License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Built with 🦀 Rust + 🕸️ WebAssembly

Correctness by Construction

Re-exports§

pub use batch::BatchInsertable;
pub use error::BatchError;
pub use hnsw::BatchDeleteError;
pub use hnsw::BatchDeleteResult;
pub use hnsw::HnswConfig;
pub use hnsw::HnswIndex;
pub use hnsw::SearchResult;
pub use metric::Metric;
pub use persistence::ChunkedWriter;
pub use quantization::BinaryQuantizer;
pub use quantization::QuantizedVector;
pub use quantization::QuantizerConfig;
pub use quantization::ScalarQuantizer;
pub use simd::capabilities;
pub use simd::warn_if_suboptimal;
pub use simd::SimdCapabilities;
pub use storage::VectorStorage;

Modules§

batch: Batch insertion API. Batch insertion API for HNSW indexes.
error: Unified error handling. Unified error hierarchy for EdgeVec.
hnsw: HNSW Graph implementation. HNSW module containing graph logic, configuration, and search.
metric: Distance metrics. Distance metrics for vector comparison.
persistence: Persistence and file format definitions. Persistence module for EdgeVec.
quantization: Quantization support. Quantization logic for vector compression.
simd: SIMD capability detection and runtime optimization. SIMD capability detection and runtime optimization.
storage: Vector storage. Vector Storage Module.
wasm: WASM bindings. WASM Bindings for EdgeVec.

Constants§

VERSION: The crate version string.

Functions§

version: Returns the crate version string.

Crate edgevec

Crate edgevec Copy item path

§EdgeVec

§Current Status

§Implemented Features

§Development Protocol

§Example

§Persistence Example

§Next Steps (Phase 5)

§Documentation

§🚀 EdgeVec

§What’s New in v0.4.0

§Documentation & Quality Sprint

§Benchmark Dashboard

§Quality Infrastructure

§Previous (v0.3.0)

§What is EdgeVec?

§Key Features

§Quick Start

§Installation

§Browser/Node.js Usage

§Load Existing Index

§Rust Usage

§Batch Insert (Rust)

§Soft Delete (Rust)

§Soft Delete (JavaScript)

§Interactive Examples

§Demo Gallery

Performance Dashboard

Soft Delete & Compaction

Batch Insert

Stress Test

§Running Locally

§Development Status

§✅ Alpha Release Ready (v0.1.0)

§Future Roadmap (v0.5.0+)

§Path to v1.0

§📊 Performance (Alpha Release)

§Search Latency (768-dimensional vectors, k=10)

§Memory Efficiency (768-dimensional vectors)

§Bundle Size

§Competitive Comparison (10k vectors, 128 dimensions)

§Key Advantages

§Test Environment

§Development Protocol

§The Agents

§Development Environment

§Local CI Simulation

§Environment Variables

§Building

§Release Process

§Origins

§Acknowledgments

§License

§Contribution

Re-exports§

Modules§

Constants§

Functions§

Crate edgevec

§🚀 `EdgeVec`

§What is `EdgeVec`?