Core Architecture
Relevant source files
The following files were used as context for generating this wiki page:
EdgeVec is a high-performance, embedded vector database designed specifically for Browser, Node, and Edge environments. Built in Rust and compiled to WebAssembly (WASM), it provides server-grade features like Hierarchical Navigable Small World (HNSW) indexing, metadata filtering, and binary quantization directly within the client-side runtime. The architecture prioritizes memory efficiency and low-latency search, achieving sub-millisecond search times and significant memory reduction through advanced quantization techniques.
Sources: Cargo.toml:13, README.md:3-6, GATE_1_COMPLETE.md:105-115
System Overview
The EdgeVec architecture is composed of four primary layers that handle graph management, data storage, persistence, and external interfacing. It is designed to be platform-agnostic while providing optimized bindings for WebAssembly environments.
Component Hierarchy
The diagram above illustrates the high-level relationship between the core layers of the system.
Sources: GATE_1_COMPLETE.md:103-125
Core Components
1. HNSW Index Layer
The HNSW layer implements a Hierarchical Navigable Small World graph for approximate nearest neighbor (ANN) search. It offers $O(\log n)$ search and insertion complexity. To maintain a small memory footprint, neighbor storage is compressed using VByte delta encoding.
Sources: GATE_1_COMPLETE.md:105-109, README.md:175-180
2. Vector Storage Layer
The storage layer utilizes an arena-based contiguous allocation strategy. This layout is SIMD-friendly, supporting 128-bit SIMD instructions on modern browsers for accelerated distance calculations. It employs a soft-delete mechanism managed by a tombstone bitmap, allowing for efficient $O(1)$ deletions and subsequent index compaction.
Sources: GATE_1_COMPLETE.md:111-113, README.md:108-112, CONTRIBUTING.md:183-195
3. Persistence Layer
Data durability is ensured through a Write-Ahead Log (WAL) for crash recovery and atomic snapshots. The system abstracts physical storage through a StorageBackend trait, supporting IndexedDB for WASM, file systems for native execution, and memory for testing.
Sources: GATE_1_COMPLETE.md:115-119, README.md:144-150
4. WASM Boundary
The boundary layer provides FFI-safe error handling using a custom EdgeVecError type. It facilitates data exchange via TypedArray for vector data and supports asynchronous I/O operations to prevent blocking the main browser thread.
Sources: GATE_1_COMPLETE.md:121-125, Cargo.toml:104-115
Data Layout and Invariants
EdgeVec enforces strict data layout invariants verified at compile-time to ensure memory safety and alignment.
| Struct | Size (Bytes) | Alignment | Purpose |
|---|---|---|---|
VectorId | - | 8 bytes | Unique identifier for vectors |
HnswConfig | 32 | 4 bytes | Configuration for HNSW parameters (M, ef_construction) |
FileHeader | 64 | 8 bytes | Metadata for persisted database files |
WalEntry | 16 | - | Single entry in the Write-Ahead Log |
SectionHeader | 24 | 8 bytes | Header for data sections in snapshots |
Sources: GATE_1_COMPLETE.md:43-52, GATE_1_COMPLETE.md:127-133
Memory Budget Per Vector
The architecture is optimized to keep per-vector overhead below 100 bytes.
| Component | Actual Size |
|---|---|
| HNSW Node | 16 bytes |
| Neighbors (compressed avg) | 66 bytes |
| Tombstone bit | 0.125 bytes |
| Total Overhead | 82.125 bytes |
Sources: GATE_1_COMPLETE.md:88-97
Performance Budgets
The system is designed to meet specific performance targets for client-side use cases.
| Operation | Target (100k vectors) | Verification Method |
|---|---|---|
| Search Latency | < 10ms P99 | SIMD-accelerated benchmarks |
| Single Insertion | < 1ms mean | Sequential benchmark suite |
| Index Load | < 500ms | Persistence layer benchmarks |
| Bundle Size | < 500KB gzipped | CI Build verification |
Sources: GATE_1_COMPLETE.md:135-141, README.md:128-132
Data Flow: Batch Insertion
EdgeVec supports both sequential and batch insertion. Batch insertion is significantly more efficient for initial data loads as it reduces the overhead of crossing the JavaScript-to-WASM boundary.
Memory Management and Quantization
EdgeVec provides built-in memory management features to handle browser-specific memory constraints.
Quantization Strategies
- Binary Quantization (BQ): Achieves a 32x memory reduction (e.g., 300MB to ~10MB for 100k 768D vectors) with approximately 95% recall when using rescoring.
- Scalar Quantization (SQ8): Provides a ~3.6x memory reduction by converting 32-bit floats to 8-bit integers.
Memory Pressure API
The API allows applications to monitor heap usage and trigger compaction when the memory level reaches a warning threshold.
Sources: README.md:10-15, README.md:108-115, README.md:131-140
Conclusion
The EdgeVec Core Architecture leverages Rust's memory safety and WebAssembly's execution speed to deliver a professional-grade vector database for the browser. By combining an HNSW index with SIMD-optimized storage and robust persistence mechanisms, it enables complex AI applications to run locally with server-like performance and efficiency.