EdgeVec Overview

Relevant source files

The following files were used as context for generating this wiki page:

• GATE_1_COMPLETE.md
• CONTRIBUTING.md
• README.md
• wasm/README.md
• examples/nodejs/README.md
• wasm/examples/index.html

EdgeVec is an embedded, high-performance vector database built in Rust with first-class WebAssembly (WASM) support. It is designed to bring server-grade vector search capabilities directly to client-side environments such as web browsers and mobile devices. By leveraging technologies like Hierarchical Navigable Small World (HNSW) graphs and binary quantization, EdgeVec achieves significant memory efficiency and sub-millisecond search latencies without requiring a centralized server.

The system is architected for offline-capable applications, providing features such as metadata filtering, soft deletes, and persistence to IndexedDB or the local filesystem. It adheres to a strict "Nvidia Grade" development standard, ensuring correctness through comprehensive testing, including property-based and recall verification.

Sources: README.md:1-15, GATE_1_COMPLETE.md:110-135, CONTRIBUTING.md:5-15

Core Architecture

EdgeVec is structured into several distinct layers that handle indexing, storage, and persistence. The architecture is designed to be platform-agnostic while optimized for the WASM environment.

Architectural Components

1. HNSW Index Layer: Implements a Hierarchical Navigable Small World graph for approximate nearest neighbor search with $O(\log n)$ complexity. It includes compressed neighbor storage using VByte delta encoding.
2. Vector Storage Layer: Utilizes arena-based contiguous allocation for SIMD-friendly memory layouts. It supports soft-delete through a tombstone bitmap.
3. Persistence Layer: Employs a Write-Ahead Log (WAL) for crash recovery and supports atomic snapshots. It uses a StorageBackend trait to abstract between IndexedDB (WASM), native files, and memory.
4. WASM Boundary: A strictly defined FFI boundary that handles TypedArrays for vector data and provides async operations for I/O, ensuring no panics cross the boundary.

Sources: GATE_1_COMPLETE.md:112-132, README.md:155-170

Data Flow Diagram

The following diagram illustrates the high-level flow of data from insertion to persistent storage within EdgeVec.

This diagram shows how client requests pass through the WASM boundary to interact with the indexing and storage layers, which are eventually backed by a persistent storage medium.
Sources: GATE_1_COMPLETE.md:112-132, README.md:195-205

Key Features and Capabilities

EdgeVec provides several advanced database features optimized for resource-constrained edge environments.

Feature	Description
Binary Quantization (BQ)	Reduces memory usage by up to 32x with ~95% recall through rescoring.
Metadata Filtering	Supports SQL-like queries (e.g., category = "books" AND price < 50) using various operators.
Memory Pressure API	Allows monitoring of WASM heap usage and triggering compaction to free deleted vectors.
Soft Delete & Compaction	$O(1)$ soft delete with periodic background compaction to reclaim space.
SIMD Acceleration	Uses WASM SIMD128 instructions for 2x+ speedup in vector operations.

Sources: README.md:17-40, README.md:130-150, GATE_1_COMPLETE.md:115-120

Metadata Filtering Syntax

EdgeVec supports a variety of operators for metadata queries:

• Comparison: =, !=, >, <, >=, <=
• Logical: AND, OR, NOT
• Array: ANY, IN
• String: CONTAINS, STARTS_WITH, ENDS_WITH, LIKE

Sources: README.md:175-190, wasm/examples/index.html:1050-1100

Memory and Performance Budgets

EdgeVec is developed with strict performance and memory overhead targets to ensure viability in browser environments.

Metric	Target	Actual / Status
Per-vector overhead	<100 bytes	82 bytes (PASSED)
Search Latency (100k)	<10ms P99	<1ms mean (768D)
Index Load (100k)	<500ms	PASSED
Bundle Size	<500KB gzipped	217KB (SIMD enabled)

Sources: GATE_1_COMPLETE.md:85-105, GATE_1_COMPLETE.md:148-155, README.md:105-115

Usage Examples

JavaScript/TypeScript Client

The high-level wrapper provides a Promise-based API for browser and Node.js environments.

import init, { EdgeVec } from 'edgevec';

await init();

// Create index
const db = new EdgeVec({ dimensions: 768 });

// Insert with metadata
const id = db.insertWithMetadata(vector, {
    category: "electronics",
    price: 299.99
});

// Filtered search
const results = db.searchWithFilter(query, 'category = "electronics" AND price < 500', 10);

Sources: README.md:55-75, wasm/README.md:15-30

Rust Library Usage

EdgeVec can also be used as a standard Rust library for native applications.

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

let config = HnswConfig::new(768);
let mut storage = VectorStorage::new(&config, None);
let mut index = HnswIndex::new(config, &storage)?;

// Insert and Search
let id = index.insert(&vector, &mut storage)?;
let results = index.search(&query, 10, &storage)?;

Sources: README.md:215-230

Development Standards: "Nvidia Grade"

The project enforces high quality standards referred to as "Nvidia Grade." This includes a mandatory test-first development (TDD) approach and a multi-layer test pyramid.

Test Pyramid Structure

This hierarchy ensures that code is not only functionally correct but also memory-safe and mathematically accurate regarding search recall (threshold set at 95%).
Sources: CONTRIBUTING.md:150-170, GATE_1_COMPLETE.md:75-85

Implementation Constraints

• Single-User Design: EdgeVec is optimized for single-user, single-tab client access.
• Scale Limits: Practical browser memory limits restrict datasets to approximately 1GB (~100k vectors at 768D without BQ).
• Concurrency: It does not support multi-user concurrent access or distributed deployments.

Sources: README.md:245-260