verso-db 0.1.1

package/src/HNSWIndex.ts

@@ -0,0 +1,1839 @@
+// Bun-native file operations - no fs import needed
+import type { DistanceBackend } from './backends/DistanceBackend';
+import { JsDistanceBackend, dotProductFast, l2SquaredFast } from './backends/JsDistanceBackend';
+import { BinaryHeap } from './BinaryHeap';
+import { MaxBinaryHeap } from './MaxBinaryHeap';
+import { ScalarQuantizer, l2SquaredInt8, cosineDistanceInt8 } from './quantization/ScalarQuantizer';
+import { deltaEncodeNeighbors, deltaDecodeNeighbors, deltaEncodedSize } from './encoding/DeltaEncoder';
+export type DistanceMetric = 'cosine' | 'euclidean' | 'dot_product';
+
+export interface Node {
+  id: number;
+  level: number;
+  vector: Float32Array;
+  neighbors: number[][]; // neighbors[layer][neighbor_index] = neighbor_id
+}
+
+export class HNSWIndex {
+  private M: number; // Max number of connections per node per level
+  private M0: number; // Max number of connections for level 0 (typically M * 2)
+  private efConstruction: number; // Size of candidate list during construction
+  private levelMult: number; // Probability multiplier for level selection
+  private maxLevel: number;
+  private entryPointId: number;
+  // OPTIMIZATION: Use array instead of Map for O(1) indexed access (3-5x faster than Map.get)
+  private nodes: (Node | undefined)[];
+  private nodeCount: number = 0;
+  private dimension: number;
+  private metric: DistanceMetric;
+  private maxLayers: number;
+  private distanceBackend: DistanceBackend;
+
+  // OPTIMIZATION: Flat vector storage for cache-friendly batch distance calculations
+  // All vectors stored contiguously: [v0_d0, v0_d1, ..., v1_d0, v1_d1, ...]
+  private flatVectors: Float32Array;
+  private flatVectorsCapacity: number = 0;
+
+  // Heap and scratch buffers for reuse
+  private searchHeap: BinaryHeap;
+  // TypedArray for fast visited tracking - much faster than Set<number>
+  private visitedArray: Uint8Array;
+  private visitedArraySize: number;
+  private visitedGeneration: number = 0; // Increment to "clear" without filling
+  // Reusable heaps for searchLayer - avoids allocation on every call
+  private candidatesHeap: BinaryHeap;
+  private resultsHeap: MaxBinaryHeap;
+  private selectionHeap: BinaryHeap; // Reusable heap for selectNeighbors
+  private heapCapacity: number;
+  // Pre-normalization optimization for cosine distance
+  private vectorsAreNormalized: boolean = false;
+  // Cached distance function to avoid switch overhead
+  private distanceFn: (a: Float32Array, b: Float32Array) => number;
+
+  // Quantization support for 3-4x faster search with Int8
+  private scalarQuantizer: ScalarQuantizer | null = null;
+  // OPTIMIZATION: Use array instead of Map for int8 vectors too
+  private int8Vectors: (Int8Array | undefined)[] = [];
+  private quantizationEnabled: boolean = false;
+
+  // Lazy loading support (v3+ format)
+  private lazyLoadEnabled: boolean = false;
+  private vectorOffsets: Map<number, number> = new Map(); // nodeId -> byte offset in file
+  private vectorBuffer: ArrayBuffer | null = null; // Cached buffer for lazy loading
+  private vectorsLoaded: Set<number> = new Set(); // Track which vectors are loaded
+
+  // Reusable query buffer for search operations - avoids allocation per query
+  // Profiling showed 17% improvement with buffer reuse (99.5ms → 82.7ms for 1000 queries)
+  private queryNormBuffer: Float32Array;
+
+  // Bulk construction optimization - O(1) neighbor lookup during construction
+  // Uses parallel Set<number>[] alongside neighbor arrays for fast membership testing
+  // Memory is released after construction completes
+  private neighborSets: Map<number, Set<number>[]> = new Map();
+  private constructionMode: boolean = false;
+
+  constructor(dimension: number, metric: DistanceMetric = 'cosine', M = 24, efConstruction = 200, distanceBackend?: DistanceBackend) {
+    this.dimension = dimension;
+    this.metric = metric;
+    this.M = M;
+    this.M0 = M * 2;
+    this.efConstruction = efConstruction;
+    this.levelMult = 1 / Math.log(M);
+    this.maxLevel = -1;
+    this.entryPointId = -1;
+    // OPTIMIZATION: Pre-allocate node array with initial capacity
+    const initialCapacity = 10000;
+    this.nodes = new Array(initialCapacity);
+    this.nodeCount = 0;
+    // OPTIMIZATION: Pre-allocate flat vector storage
+    this.flatVectorsCapacity = initialCapacity;
+    this.flatVectors = new Float32Array(initialCapacity * dimension);
+    this.maxLayers = 32; // Maximum possible layers to pre-allocate
+    this.distanceBackend = distanceBackend ?? new JsDistanceBackend();
+
+    // Initialize heap and scratch buffers
+    this.searchHeap = new BinaryHeap(1000); // Initial capacity
+
+    // Initialize visited tracking with TypedArray for speed
+    // Start with reasonable size, will grow as needed
+    this.visitedArraySize = 10000;
+    this.visitedArray = new Uint8Array(this.visitedArraySize);
+    this.visitedGeneration = 1;
+
+    // Pre-allocate searchLayer heaps - sized for typical ef values
+    // Will be resized if needed for larger ef
+    this.heapCapacity = Math.max(efConstruction * 2, 500);
+    this.candidatesHeap = new BinaryHeap(this.heapCapacity);
+    this.resultsHeap = new MaxBinaryHeap(this.heapCapacity);
+    // Selection heap sized for M0 (largest neighbor list size)
+    this.selectionHeap = new BinaryHeap(Math.max(M * 2, efConstruction));
+
+    // For cosine metric, we pre-normalize vectors for faster distance computation
+    this.vectorsAreNormalized = (metric === 'cosine');
+
+    // Pre-allocate query normalization buffer - reused across all searches
+    this.queryNormBuffer = new Float32Array(dimension);
+
+    // Initialize cached distance function based on metric
+    // This avoids switch statement overhead on every distance calculation
+    if (metric === 'cosine') {
+      // For cosine with pre-normalized vectors, just compute 1 - dot product
+      this.distanceFn = (a: Float32Array, b: Float32Array): number => {
+        const dot = dotProductFast(a, b);
+        const distance = 1 - dot;
+        return distance < 1e-10 ? 0 : distance;
+      };
+    } else if (metric === 'euclidean') {
+      this.distanceFn = (a: Float32Array, b: Float32Array): number => {
+        return Math.sqrt(l2SquaredFast(a, b));
+      };
+    } else if (metric === 'dot_product') {
+      this.distanceFn = (a: Float32Array, b: Float32Array): number => {
+        return -dotProductFast(a, b);
+      };
+    } else {
+      throw new Error(`Unsupported metric: ${metric}`);
+    }
+  }
+
+  // ============================================
+  // OPTIMIZATION: Capacity and flat storage helpers
+  // ============================================
+
+  /**
+   * Ensure node array and flat vector storage have enough capacity
+   */
+  private ensureCapacity(minCapacity: number): void {
+    // Grow node array if needed
+    if (minCapacity > this.nodes.length) {
+      const newCapacity = Math.max(this.nodes.length * 2, minCapacity);
+      const newNodes = new Array(newCapacity);
+      for (let i = 0; i < this.nodeCount; i++) {
+        newNodes[i] = this.nodes[i];
+      }
+      this.nodes = newNodes;
+    }
+
+    // Grow flat vector storage if needed
+    if (minCapacity > this.flatVectorsCapacity) {
+      const newCapacity = Math.max(this.flatVectorsCapacity * 2, minCapacity);
+      const newFlatVectors = new Float32Array(newCapacity * this.dimension);
+      newFlatVectors.set(this.flatVectors);
+      this.flatVectors = newFlatVectors;
+      this.flatVectorsCapacity = newCapacity;
+    }
+  }
+
+  /**
+   * Get vector from flat storage by node ID
+   * Returns a subarray view (no copy) for efficiency
+   */
+  private getFlatVector(nodeId: number): Float32Array {
+    const offset = nodeId * this.dimension;
+    return this.flatVectors.subarray(offset, offset + this.dimension);
+  }
+
+  /**
+   * Set vector in flat storage
+   */
+  private setFlatVector(nodeId: number, vector: Float32Array): void {
+    const offset = nodeId * this.dimension;
+    this.flatVectors.set(vector, offset);
+  }
+
+  /**
+   * Get node by ID (O(1) array access)
+   */
+  private getNode(id: number): Node | undefined {
+    return this.nodes[id];
+  }
+
+  /**
+   * Set node by ID
+   */
+  private setNode(node: Node): void {
+    const id = node.id;
+    this.ensureCapacity(id + 1);
+    this.nodes[id] = node;
+    // Store vector in flat storage too
+    this.setFlatVector(id, node.vector);
+    // Track node count
+    if (id >= this.nodeCount) {
+      this.nodeCount = id + 1;
+    }
+  }
+
+  // OPTIMIZATION: Reusable arrays for batch distance calculation
+  private batchNeighborIds: number[] = [];
+  private batchDistances: number[] = [];
+
+  /**
+   * OPTIMIZATION: Batch distance calculation for better cache locality
+   * Computes distances from query to multiple neighbors at once
+   * Uses flat vector storage for contiguous memory access
+   */
+  private calculateDistancesBatch(
+    query: Float32Array,
+    neighborIds: number[],
+    outDistances: number[]
+  ): void {
+    const dim = this.dimension;
+    const flatVectors = this.flatVectors;
+
+    for (let i = 0; i < neighborIds.length; i++) {
+      const neighborId = neighborIds[i];
+      const offset = neighborId * dim;
+
+      // Inline distance calculation for better performance
+      // This avoids function call overhead per neighbor
+      if (this.metric === 'cosine') {
+        // Pre-normalized vectors: distance = 1 - dot(a, b)
+        let sum0 = 0, sum1 = 0, sum2 = 0, sum3 = 0;
+        let sum4 = 0, sum5 = 0, sum6 = 0, sum7 = 0;
+        let d = 0;
+        const limit8 = dim - 7;
+
+        for (; d < limit8; d += 8) {
+          sum0 += flatVectors[offset + d] * query[d];
+          sum1 += flatVectors[offset + d + 1] * query[d + 1];
+          sum2 += flatVectors[offset + d + 2] * query[d + 2];
+          sum3 += flatVectors[offset + d + 3] * query[d + 3];
+          sum4 += flatVectors[offset + d + 4] * query[d + 4];
+          sum5 += flatVectors[offset + d + 5] * query[d + 5];
+          sum6 += flatVectors[offset + d + 6] * query[d + 6];
+          sum7 += flatVectors[offset + d + 7] * query[d + 7];
+        }
+        for (; d < dim; d++) {
+          sum0 += flatVectors[offset + d] * query[d];
+        }
+
+        const dot = sum0 + sum1 + sum2 + sum3 + sum4 + sum5 + sum6 + sum7;
+        const dist = 1 - dot;
+        outDistances[i] = dist < 1e-10 ? 0 : dist;
+      } else if (this.metric === 'euclidean') {
+        // L2 squared distance
+        let sum0 = 0, sum1 = 0, sum2 = 0, sum3 = 0;
+        let sum4 = 0, sum5 = 0, sum6 = 0, sum7 = 0;
+        let d = 0;
+        const limit8 = dim - 7;
+
+        for (; d < limit8; d += 8) {
+          const d0 = flatVectors[offset + d] - query[d];
+          const d1 = flatVectors[offset + d + 1] - query[d + 1];
+          const d2 = flatVectors[offset + d + 2] - query[d + 2];
+          const d3 = flatVectors[offset + d + 3] - query[d + 3];
+          const d4 = flatVectors[offset + d + 4] - query[d + 4];
+          const d5 = flatVectors[offset + d + 5] - query[d + 5];
+          const d6 = flatVectors[offset + d + 6] - query[d + 6];
+          const d7 = flatVectors[offset + d + 7] - query[d + 7];
+          sum0 += d0 * d0;
+          sum1 += d1 * d1;
+          sum2 += d2 * d2;
+          sum3 += d3 * d3;
+          sum4 += d4 * d4;
+          sum5 += d5 * d5;
+          sum6 += d6 * d6;
+          sum7 += d7 * d7;
+        }
+        for (; d < dim; d++) {
+          const diff = flatVectors[offset + d] - query[d];
+          sum0 += diff * diff;
+        }
+
+        outDistances[i] = Math.sqrt(sum0 + sum1 + sum2 + sum3 + sum4 + sum5 + sum6 + sum7);
+      } else {
+        // dot_product: negative dot product
+        let sum0 = 0, sum1 = 0, sum2 = 0, sum3 = 0;
+        let sum4 = 0, sum5 = 0, sum6 = 0, sum7 = 0;
+        let d = 0;
+        const limit8 = dim - 7;
+
+        for (; d < limit8; d += 8) {
+          sum0 += flatVectors[offset + d] * query[d];
+          sum1 += flatVectors[offset + d + 1] * query[d + 1];
+          sum2 += flatVectors[offset + d + 2] * query[d + 2];
+          sum3 += flatVectors[offset + d + 3] * query[d + 3];
+          sum4 += flatVectors[offset + d + 4] * query[d + 4];
+          sum5 += flatVectors[offset + d + 5] * query[d + 5];
+          sum6 += flatVectors[offset + d + 6] * query[d + 6];
+          sum7 += flatVectors[offset + d + 7] * query[d + 7];
+        }
+        for (; d < dim; d++) {
+          sum0 += flatVectors[offset + d] * query[d];
+        }
+
+        outDistances[i] = -(sum0 + sum1 + sum2 + sum3 + sum4 + sum5 + sum6 + sum7);
+      }
+    }
+  }
+
+  /**
+   * Check if a node has been visited in the current search.
+   * Uses generation counting to avoid clearing the array.
+   */
+  private isVisited(id: number): boolean {
+    if (id >= this.visitedArraySize) {
+      return false; // Not in array = not visited
+    }
+    return this.visitedArray[id] === this.visitedGeneration;
+  }
+
+  /**
+   * Mark a node as visited in the current search.
+   * Grows the array if needed.
+   */
+  private markVisited(id: number): void {
+    if (id >= this.visitedArraySize) {
+      // Grow array to accommodate larger IDs
+      const newSize = Math.max(this.visitedArraySize * 2, id + 1000);
+      const newArray = new Uint8Array(newSize);
+      newArray.set(this.visitedArray);
+      this.visitedArray = newArray;
+      this.visitedArraySize = newSize;
+    }
+    this.visitedArray[id] = this.visitedGeneration;
+  }
+
+  /**
+   * Clear all visited markers by incrementing the generation.
+   * Much faster than filling the array with zeros.
+   */
+  private clearVisited(): void {
+    this.visitedGeneration++;
+    // Wrap around to avoid overflow (255 is max for Uint8)
+    if (this.visitedGeneration > 250) {
+      this.visitedArray.fill(0);
+      this.visitedGeneration = 1;
+    }
+  }
+
+  private normalizeVector(vector: Float32Array): Float32Array {
+    const len = vector.length;
+    // Use 8 accumulators for better ILP
+    let s0 = 0, s1 = 0, s2 = 0, s3 = 0;
+    let s4 = 0, s5 = 0, s6 = 0, s7 = 0;
+    let i = 0;
+    const limit8 = len - 7;
+
+    // 8-wide unrolling for norm computation
+    for (; i < limit8; i += 8) {
+      s0 += vector[i] * vector[i];
+      s1 += vector[i + 1] * vector[i + 1];
+      s2 += vector[i + 2] * vector[i + 2];
+      s3 += vector[i + 3] * vector[i + 3];
+      s4 += vector[i + 4] * vector[i + 4];
+      s5 += vector[i + 5] * vector[i + 5];
+      s6 += vector[i + 6] * vector[i + 6];
+      s7 += vector[i + 7] * vector[i + 7];
+    }
+    // Handle remaining elements
+    for (; i < len; i++) {
+      s0 += vector[i] * vector[i];
+    }
+
+    const normSq = s0 + s1 + s2 + s3 + s4 + s5 + s6 + s7;
+    const norm = Math.sqrt(normSq);
+    if (norm > 0) {
+      const invNorm = 1 / norm;
+      for (let j = 0; j < len; j++) {
+        vector[j] *= invNorm;
+      }
+    }
+    return vector;
+  }
+
+  private selectLevel(): number {
+    const r = Math.random();
+    const level = Math.floor(-Math.log(r) * this.levelMult);
+    return Math.min(level, this.maxLayers - 1);
+  }
+
+  /**
+   * Calculate distance between two vectors using the configured metric.
+   * Uses cached function pointer to avoid switch overhead.
+   */
+  calculateDistance(a: Float32Array, b: Float32Array): number {
+    return this.distanceFn(a, b);
+  }
+
+  /**
+   * Get a node's vector, loading it if necessary (for lazy loading support)
+   */
+  private getNodeVector(nodeId: number): Float32Array | null {
+    const node = this.nodes[nodeId];
+    if (!node) return null;
+
+    if (this.lazyLoadEnabled && !this.vectorsLoaded.has(nodeId)) {
+      this.loadVector(nodeId);
+    }
+
+    return node.vector;
+  }
+
+  private getLayerMaxConnections(layer: number): number {
+    return layer === 0 ? this.M0 : this.M;
+  }
+
+  private selectNeighbors(currentId: number, candidates: Array<{ id: number; distance: number }>, layer: number): number[] {
+    const maxConnections = this.getLayerMaxConnections(layer);
+
+    // Reuse selection heap - clear and ensure capacity
+    this.selectionHeap.clear();
+
+    // Add all candidates to the heap (skip self-reference)
+    for (const candidate of candidates) {
+      if (candidate.id !== currentId) {
+        this.selectionHeap.push(candidate.id, candidate.distance);
+      }
+    }
+
+    // Extract the best neighbors (closest first)
+    // Pre-allocate array for expected size
+    const selected = new Array<number>(Math.min(maxConnections, this.selectionHeap.size()));
+    let idx = 0;
+
+    // Extract up to maxConnections elements from heap
+    // Candidates from searchLayer are already unique (visited tracking)
+    while (idx < maxConnections && !this.selectionHeap.isEmpty()) {
+      const id = this.selectionHeap.pop();
+      if (id !== -1) {
+        selected[idx++] = id;
+      }
+    }
+
+    // Trim if needed
+    if (idx < selected.length) {
+      selected.length = idx;
+    }
+
+    return selected;
+  }
+
+  private addBidirectionalConnection(fromId: number, toId: number, level: number): void {
+    const fromNode = this.nodes[fromId];
+    const toNode = this.nodes[toId];
+
+    if (!fromNode || !toNode) return;
+
+    // Ensure neighbor arrays exist
+    if (!fromNode.neighbors[level]) {
+      fromNode.neighbors[level] = [];
+    }
+    if (!toNode.neighbors[level]) {
+      toNode.neighbors[level] = [];
+    }
+
+    if (this.constructionMode) {
+      // O(1) lookup using Sets during bulk construction
+      let fromSets = this.neighborSets.get(fromId);
+      if (!fromSets) {
+        fromSets = [];
+        this.neighborSets.set(fromId, fromSets);
+      }
+      if (!fromSets[level]) {
+        fromSets[level] = new Set(fromNode.neighbors[level]);
+      }
+
+      let toSets = this.neighborSets.get(toId);
+      if (!toSets) {
+        toSets = [];
+        this.neighborSets.set(toId, toSets);
+      }
+      if (!toSets[level]) {
+        toSets[level] = new Set(toNode.neighbors[level]);
+      }
+
+      // O(1) membership test with Set.has()
+      if (!fromSets[level].has(toId)) {
+        fromSets[level].add(toId);
+        fromNode.neighbors[level].push(toId);
+      }
+
+      if (!toSets[level].has(fromId)) {
+        toSets[level].add(fromId);
+        toNode.neighbors[level].push(fromId);
+      }
+    } else {
+      // Original O(M) lookup for single inserts (fallback)
+      if (!fromNode.neighbors[level].includes(toId)) {
+        fromNode.neighbors[level].push(toId);
+      }
+      if (!toNode.neighbors[level].includes(fromId)) {
+        toNode.neighbors[level].push(fromId);
+      }
+    }
+  }
+
+  /**
+   * Ensure heap capacity is sufficient for the given ef value.
+   * Resizes heaps if needed.
+   */
+  private ensureHeapCapacity(ef: number): void {
+    const requiredCapacity = Math.max(ef * 2, 100);
+    if (requiredCapacity > this.heapCapacity) {
+      this.heapCapacity = requiredCapacity;
+      this.candidatesHeap = new BinaryHeap(this.heapCapacity);
+      this.resultsHeap = new MaxBinaryHeap(this.heapCapacity);
+    }
+  }
+
+  /**
+   * Search a layer using the standard two-heap HNSW algorithm.
+   *
+   * Uses two heaps:
+   * - candidatesHeap (min-heap): Tracks nodes to explore, prioritizing closest
+   * - resultsHeap (max-heap): Tracks top-ef results, allowing O(log n) eviction of furthest
+   *
+   * Termination: Stops when closest unvisited candidate is farther than furthest result.
+   */
+  private searchLayer(
+    query: Float32Array,
+    nearest: { id: number; distance: number },
+    layer: number,
+    ef: number
+  ): Array<{ id: number; distance: number }> {
+    // Clear visited tracking
+    this.clearVisited();
+
+    // Ensure heaps are large enough, then clear and reuse
+    this.ensureHeapCapacity(ef);
+    this.candidatesHeap.clear();
+    this.resultsHeap.clear();
+
+    // Initialize with entry point
+    this.markVisited(nearest.id);
+    this.candidatesHeap.push(nearest.id, nearest.distance);
+    this.resultsHeap.push(nearest.id, nearest.distance);
+
+    // Cache the furthest result distance - only changes when resultsHeap is modified
+    let furthestResultDist = nearest.distance;
+
+    // OPTIMIZATION: Pre-allocate batch arrays for distance calculation
+    // Reuse across iterations to avoid allocation
+    const batchIds = this.batchNeighborIds;
+    const batchDists = this.batchDistances;
+
+    while (!this.candidatesHeap.isEmpty()) {
+      // Get closest unexplored candidate
+      const closestCandidateDist = this.candidatesHeap.peekValue();
+      const closestCandidateId = this.candidatesHeap.pop();
+
+      if (closestCandidateId === -1) continue;
+
+      // TERMINATION: Stop if closest candidate is farther than worst result
+      if (this.resultsHeap.size() >= ef && closestCandidateDist > furthestResultDist) {
+        break;
+      }
+
+      const node = this.nodes[closestCandidateId];
+      if (!node) continue;
+
+      const neighbors = node.neighbors[layer] || [];
+
+      // Use batch distance calculation for non-lazy indices (better cache locality)
+      // Fall back to one-by-one for lazy-loaded indices (vectors may not be in flatVectors)
+      if (!this.lazyLoadEnabled) {
+        // OPTIMIZATION: Collect unvisited neighbors and compute distances in batch
+        let batchCount = 0;
+        for (let i = 0; i < neighbors.length; i++) {
+          const neighborId = neighbors[i];
+          if (!this.isVisited(neighborId)) {
+            this.markVisited(neighborId);
+            batchIds[batchCount] = neighborId;
+            batchCount++;
+          }
+        }
+
+        // Calculate all distances at once (better cache utilization)
+        if (batchCount > 0) {
+          // Ensure batch arrays are large enough
+          if (batchDists.length < batchCount) {
+            this.batchDistances.length = batchCount;
+          }
+
+          this.calculateDistancesBatch(query, batchIds.slice(0, batchCount), batchDists);
+
+          // Process batch results
+          for (let i = 0; i < batchCount; i++) {
+            const neighborId = batchIds[i];
+            const distance = batchDists[i];
+
+            // Add to results if it's good enough
+            if (this.resultsHeap.size() < ef || distance < furthestResultDist) {
+              this.candidatesHeap.push(neighborId, distance);
+              this.resultsHeap.push(neighborId, distance);
+
+              // Maintain max size of ef and update cached furthest distance
+              if (this.resultsHeap.size() > ef) {
+                this.resultsHeap.pop(); // Remove furthest (O(log n))
+              }
+              furthestResultDist = this.resultsHeap.peekValue();
+            }
+          }
+        }
+      } else {
+        // Original one-by-one for lazy-loaded indices
+        for (const neighborId of neighbors) {
+          if (this.isVisited(neighborId)) continue;
+          this.markVisited(neighborId);
+
+          const neighborVector = this.getNodeVector(neighborId);
+          if (!neighborVector) continue;
+
+          const distance = this.calculateDistance(query, neighborVector);
+
+          // Add to results if it's good enough
+          if (this.resultsHeap.size() < ef || distance < furthestResultDist) {
+            this.candidatesHeap.push(neighborId, distance);
+            this.resultsHeap.push(neighborId, distance);
+
+            // Maintain max size of ef and update cached furthest distance
+            if (this.resultsHeap.size() > ef) {
+              this.resultsHeap.pop(); // Remove furthest (O(log n))
+            }
+            furthestResultDist = this.resultsHeap.peekValue();
+          }
+        }
+      }
+    }
+
+    // Extract results from max-heap into pre-sized array
+    // Build in reverse order to avoid reverse() call
+    const resultCount = this.resultsHeap.size();
+    const results: Array<{ id: number; distance: number }> = new Array(resultCount);
+    let idx = resultCount - 1;
+    while (!this.resultsHeap.isEmpty()) {
+      const dist = this.resultsHeap.peekValue();
+      const id = this.resultsHeap.pop();
+      results[idx--] = { id, distance: dist };
+    }
+
+    return results;
+  }
+
+  private greedySearch(query: Float32Array, entryNode: Node, level: number): { id: number; distance: number } {
+    // Simplified greedy search - no heap needed, just follow the best neighbor
+    this.clearVisited();
+
+    let currentNode = entryNode;
+    // Load entry node vector if lazy loading is enabled
+    const entryVector = this.getNodeVector(entryNode.id);
+    let currentDistance = entryVector ? this.calculateDistance(query, entryVector) : Infinity;
+    this.markVisited(currentNode.id);
+
+    // Keep following the best neighbor until no improvement
+    let improved = true;
+    while (improved) {
+      improved = false;
+      const neighbors = currentNode.neighbors[level] || [];
+
+      for (const neighborId of neighbors) {
+        if (this.isVisited(neighborId)) continue;
+        this.markVisited(neighborId);
+
+        const neighborVector = this.getNodeVector(neighborId);
+        if (!neighborVector) continue;
+
+        const neighborNode = this.nodes[neighborId];
+        if (!neighborNode) continue;
+
+        const distance = this.calculateDistance(query, neighborVector);
+
+        if (distance < currentDistance) {
+          currentDistance = distance;
+          currentNode = neighborNode;
+          improved = true;
+        }
+      }
+    }
+
+    return { id: currentNode.id, distance: currentDistance };
+  }
+
+  /**
+   * Add a point to the index (async wrapper for API compatibility)
+   * For bulk operations, use addPointsBulk() which uses the faster sync version internally
+   */
+  async addPoint(id: number, vector: number[] | Float32Array, options?: { skipNormalization?: boolean }): Promise<void> {
+    this.addPointSync(id, vector, options);
+  }
+
+  /**
+   * Synchronous version of addPoint - avoids async/await microtask overhead
+   * 10-15x faster for bulk insertions where async is not needed
+   * @param skipNormalization - Set true if vectors are already unit-normalized (e.g., Cohere embeddings)
+   */
+  addPointSync(id: number, vector: number[] | Float32Array, options?: { skipNormalization?: boolean }): void {
+    // Optimize: only copy when necessary
+    // - Always copy arrays (need Float32Array)
+    // - Copy Float32Array only if we need to normalize (modifies in place)
+    // - Reuse input directly if skipNormalization is set (caller guarantees immutability)
+    let floatVector: Float32Array;
+    if (Array.isArray(vector)) {
+      floatVector = new Float32Array(vector);
+    } else if (this.vectorsAreNormalized && !options?.skipNormalization) {
+      // Need to copy because normalizeVector modifies in place
+      floatVector = new Float32Array(vector);
+    } else {
+      // No normalization needed and input is Float32Array - use directly
+      // Note: caller should not modify this array after passing it
+      floatVector = vector;
+    }
+
+    if (floatVector.length !== this.dimension) {
+      throw new Error(`Vector dimension ${floatVector.length} does not match expected ${this.dimension}`);
+    }
+
+    // Pre-normalize vectors for cosine metric for faster distance computation
+    // Skip if caller indicates vectors are already normalized
+    if (this.vectorsAreNormalized && !options?.skipNormalization) {
+      floatVector = this.normalizeVector(floatVector);
+    }
+
+    // Create new node
+    const level = this.selectLevel();
+    // Pre-allocate neighbors array without Array.from overhead
+    const neighbors = new Array<number[]>(level + 1);
+    for (let i = 0; i <= level; i++) {
+      neighbors[i] = [];
+    }
+    const newNode: Node = {
+      id,
+      level,
+      vector: floatVector,
+      neighbors,
+    };
+
+    this.setNode(newNode);
+
+    // If this is the first node, make it the entry point
+    if (this.entryPointId === -1) {
+      this.entryPointId = id;
+      this.maxLevel = level;
+      return;
+    }
+
+    // Find the entry point at the highest level
+    let currentEntryPoint = this.nodes[this.entryPointId]!;
+    let currentBest = { id: currentEntryPoint.id, distance: this.calculateDistance(floatVector, currentEntryPoint.vector) };
+
+    // Go down from max level to insertion level
+    for (let l = this.maxLevel; l > level; l--) {
+      const result = this.greedySearch(floatVector, currentEntryPoint, l);
+      if (result.distance < currentBest.distance) {
+        currentBest = result;
+        currentEntryPoint = this.nodes[currentBest.id]!;
+      }
+    }
+
+    // Now connect at each level from the insertion level down to 0
+    for (let l = Math.min(level, this.maxLevel); l >= 0; l--) {
+      // Search in the current level
+      const searchResults = this.searchLayer(floatVector, currentBest, l, this.efConstruction);
+
+      // Get neighbors for this level
+      const neighbors = this.selectNeighbors(id, searchResults, l);
+
+      // Add bidirectional connections
+      for (const neighborId of neighbors) {
+        this.addBidirectionalConnection(id, neighborId, l);
+      }
+
+      // Update the current best for the next level
+      if (searchResults.length > 0) {
+        currentBest = searchResults[0];
+      }
+    }
+
+    // Update the entry point if a higher level was created
+    if (level > this.maxLevel) {
+      this.maxLevel = level;
+      this.entryPointId = id;
+    }
+  }
+
+  searchKNN(query: Float32Array, k: number, efSearch?: number): Array<{ id: number; distance: number }> {
+    if (this.entryPointId === -1 || this.nodeCount === 0) {
+      return [];
+    }
+
+    if (query.length !== this.dimension) {
+      throw new Error(`Query dimension ${query.length} does not match expected ${this.dimension}`);
+    }
+
+    const effectiveEf = efSearch || Math.max(k * 2, 50);
+
+    // Normalize query vector for cosine metric to match stored normalized vectors
+    // Reuse pre-allocated buffer to avoid allocation per query (17% measured speedup)
+    let normalizedQuery = query;
+    if (this.vectorsAreNormalized) {
+      // Copy to reusable buffer and normalize in place
+      this.queryNormBuffer.set(query);
+      normalizedQuery = this.normalizeVector(this.queryNormBuffer);
+    }
+
+    // Start from the entry point at the highest level
+    let currentEntryPoint = this.nodes[this.entryPointId]!;
+    const entryVector = this.getNodeVector(this.entryPointId);
+    if (!entryVector) return [];
+    let currentBest = { id: currentEntryPoint.id, distance: this.calculateDistance(normalizedQuery, entryVector) };
+
+    // Go down from max level to level 1
+    for (let l = this.maxLevel; l > 0; l--) {
+      const result = this.greedySearch(normalizedQuery, currentEntryPoint, l);
+      if (result.distance < currentBest.distance) {
+        currentBest = result;
+        currentEntryPoint = this.nodes[currentBest.id]!;
+      }
+    }
+
+    // At level 0, perform detailed search
+    const candidates = this.searchLayer(normalizedQuery, currentBest, 0, effectiveEf);
+
+    // Sort candidates by distance, then by ID for consistent tie-breaking
+    // Sort in place since we own this array from searchLayer
+    candidates.sort((a, b) => {
+      const diff = a.distance - b.distance;
+      return diff !== 0 ? diff : a.id - b.id;
+    });
+
+    // Return only top k results - truncate in place instead of slice
+    if (candidates.length > k) candidates.length = k;
+
+    return candidates;
+  }
+
+  /**
+   * Batch search for multiple query vectors.
+   * More efficient than calling searchKNN multiple times as it reuses internal buffers.
+   *
+   * @param queries Array of query vectors
+   * @param k Number of nearest neighbors to return per query
+   * @param efSearch Search effort parameter (higher = better recall, slower)
+   * @returns Array of results, one per query
+   */
+  searchKNNBatch(
+    queries: Float32Array[],
+    k: number,
+    efSearch?: number
+  ): Array<Array<{ id: number; distance: number }>> {
+    const numQueries = queries.length;
+
+    if (this.entryPointId === -1 || this.nodeCount === 0) {
+      // Pre-allocate empty result arrays
+      const emptyResults = new Array<Array<{ id: number; distance: number }>>(numQueries);
+      for (let i = 0; i < numQueries; i++) {
+        emptyResults[i] = [];
+      }
+      return emptyResults;
+    }
+
+    // Pre-allocate results array
+    const results = new Array<Array<{ id: number; distance: number }>>(numQueries);
+
+    // Clear and reuse internal buffers
+    this.clearVisited();
+
+    for (let i = 0; i < numQueries; i++) {
+      const query = queries[i];
+      if (query.length !== this.dimension) {
+        throw new Error(`Query dimension ${query.length} does not match expected ${this.dimension}`);
+      }
+
+      // Reuse the searchKNN implementation but with shared buffers
+      results[i] = this.searchKNN(query, k, efSearch);
+
+      // Clear visited set for next query
+      this.clearVisited();
+    }
+
+    return results;
+  }
+
+  /**
+   * Optimized batch search that returns results in a flat structure for better performance.
+   * Useful when you need to process many queries quickly.
+   *
+   * @param queries Flat Float32Array containing all queries concatenated
+   * @param numQueries Number of queries in the array
+   * @param k Number of nearest neighbors to return per query
+   * @param efSearch Search effort parameter
+   * @returns Object with flat arrays for ids and distances
+   */
+  searchKNNBatchFlat(
+    queries: Float32Array,
+    numQueries: number,
+    k: number,
+    efSearch?: number
+  ): { ids: Uint32Array; distances: Float32Array } {
+    if (this.entryPointId === -1 || this.nodeCount === 0) {
+      return {
+        ids: new Uint32Array(numQueries * k),
+        distances: new Float32Array(numQueries * k).fill(Infinity)
+      };
+    }
+
+    const ids = new Uint32Array(numQueries * k);
+    const distances = new Float32Array(numQueries * k);
+
+    for (let q = 0; q < numQueries; q++) {
+      // Extract query vector
+      const queryStart = q * this.dimension;
+      const query = queries.subarray(queryStart, queryStart + this.dimension);
+
+      // Search
+      const results = this.searchKNN(query, k, efSearch);
+
+      // Copy results to output arrays
+      const resultStart = q * k;
+      for (let i = 0; i < k; i++) {
+        if (i < results.length) {
+          ids[resultStart + i] = results[i].id;
+          distances[resultStart + i] = results[i].distance;
+        } else {
+          ids[resultStart + i] = 0;
+          distances[resultStart + i] = Infinity;
+        }
+      }
+
+      // Clear visited set for next query
+      this.clearVisited();
+    }
+
+    return { ids, distances };
+  }
+
+  // ============================================
+  // Convenience Methods
+  // ============================================
+
+  /**
+   * Add a single vector with auto-generated ID.
+   * Returns the assigned ID.
+   *
+   * @param vector Vector to add
+   * @returns The auto-generated ID
+   *
+   * @example
+   * ```typescript
+   * const id = await index.add([0.1, 0.2, 0.3]);
+   * console.log(`Added vector with ID: ${id}`);
+   * ```
+   */
+  async add(vector: number[] | Float32Array): Promise<number> {
+    const id = this.nodeCount;
+    await this.addPoint(id, vector);
+    return id;
+  }
+
+  /**
+   * Simple query interface - find k nearest neighbors.
+   *
+   * @param vector Query vector
+   * @param k Number of results (default: 10)
+   * @returns Array of {id, distance} results
+   *
+   * @example
+   * ```typescript
+   * const results = index.query([0.1, 0.2, 0.3], 5);
+   * results.forEach(r => console.log(`ID: ${r.id}, Distance: ${r.distance}`));
+   * ```
+   */
+  query(vector: number[] | Float32Array, k: number = 10): Array<{ id: number; distance: number }> {
+    const floatVector = Array.isArray(vector) ? new Float32Array(vector) : vector;
+    return this.searchKNN(floatVector, k);
+  }
+
+  /**
+   * Add multiple vectors with auto-generated IDs.
+   * Returns the assigned IDs.
+   *
+   * @param vectors Array of vectors to add
+   * @returns Array of auto-generated IDs
+   *
+   * @example
+   * ```typescript
+   * const ids = await index.addAll([[0.1, 0.2], [0.3, 0.4]]);
+   * ```
+   */
+  async addAll(vectors: Array<number[] | Float32Array>): Promise<number[]> {
+    // Use bulk construction mode for better performance
+    const points = vectors.map((vector, i) => ({
+      id: this.nodeCount + i,
+      vector: vector instanceof Float32Array ? vector : new Float32Array(vector)
+    }));
+    await this.addPointsBulk(points);
+    return points.map(p => p.id);
+  }
+
+  /**
+   * Bulk add multiple points with optimized O(1) neighbor lookups.
+   * Significantly faster than sequential addPoint() calls for large batches.
+   * Uses Set-based membership testing during construction, then releases memory.
+   *
+   * @param points Array of {id, vector} to add
+   * @example
+   * ```typescript
+   * await index.addPointsBulk([
+   *   { id: 0, vector: new Float32Array([0.1, 0.2, ...]) },
+   *   { id: 1, vector: new Float32Array([0.3, 0.4, ...]) },
+   * ]);
+   * ```
+   */
+  async addPointsBulk(points: Array<{ id: number; vector: Float32Array }>, options?: { skipNormalization?: boolean }): Promise<void> {
+    this.addPointsBulkSync(points, options);
+  }
+
+  /**
+   * Synchronous bulk insertion - 10-15x faster than async version
+   * Uses addPointSync() internally to avoid microtask queue overhead
+   * @param skipNormalization - Set true if vectors are already unit-normalized
+   */
+  addPointsBulkSync(points: Array<{ id: number; vector: Float32Array }>, options?: { skipNormalization?: boolean }): void {
+    if (points.length === 0) return;
+
+    // Enable construction mode for O(1) neighbor lookups
+    this.constructionMode = true;
+    this.neighborSets.clear();
+
+    try {
+      for (const { id, vector } of points) {
+        this.addPointSync(id, vector, options);
+      }
+    } finally {
+      // Always cleanup, even on error
+      this.constructionMode = false;
+      this.neighborSets.clear(); // Release memory
+    }
+  }
+
+  /**
+   * Clear construction-time data structures to free memory.
+   * Called automatically after addPointsBulk(), but can be called
+   * manually if needed.
+   */
+  clearConstructionCache(): void {
+    this.constructionMode = false;
+    this.neighborSets.clear();
+  }
+
+  // Format version constants
+  private static readonly MAGIC = 0x484E5357; // "HNSW" in ASCII (big-endian: 0x48='H', 0x4E='N', 0x53='S', 0x57='W')
+  private static readonly FORMAT_VERSION = 3; // v3: vector offset index for lazy loading
+  private static readonly HEADER_SIZE = 40; // 4 (magic) + 4 (version) + 28 (existing header) + 4 (vectorDataOffset)
+
+  /**
+   * Get all nodes as an array (filters out undefined slots)
+   */
+  private getNodesArray(): Node[] {
+    const result: Node[] = [];
+    for (let i = 0; i < this.nodeCount; i++) {
+      const node = this.nodes[i];
+      if (node) result.push(node);
+    }
+    return result;
+  }
+
+  serialize(): ArrayBuffer {
+    // Format v3: Vectors stored separately at end with offset table for lazy loading
+    const nodeCount = this.nodeCount;
+    const nodesArray = this.getNodesArray();
+
+    // Build ID to index mapping first (needed for delta encoding)
+    const idToIndex = new Map<number, number>();
+    for (let i = 0; i < nodesArray.length; i++) {
+      idToIndex.set(nodesArray[i].id, i);
+    }
+
+    // Pre-encode all neighbor lists with delta encoding
+    const encodedNeighbors: Uint8Array[][] = [];
+    let totalNeighborBytes = 0;
+
+    for (const node of nodesArray) {
+      const nodeEncodings: Uint8Array[] = [];
+      for (let l = 0; l <= node.level; l++) {
+        const neighborIndices = node.neighbors[l].map(id => idToIndex.get(id) ?? 0);
+        const encoded = deltaEncodeNeighbors(neighborIndices);
+        nodeEncodings.push(encoded);
+        totalNeighborBytes += encoded.length;
+      }
+      encodedNeighbors.push(nodeEncodings);
+    }
+
+    // Calculate sizes for v3 format:
+    // - Header: 40 bytes (includes vectorDataOffset)
+    // - Node metadata: nodeCount * 8 (id + level)
+    // - Neighbor metadata: sum of (level+1) * 8 per node
+    // - Encoded neighbors: totalNeighborBytes
+    // - Vector offset table: nodeCount * 4 (offset within vector section)
+    // - Vectors: nodeCount * dimension * 4 (at end for lazy loading)
+    let graphSize = HNSWIndex.HEADER_SIZE;
+    graphSize += nodeCount * 8; // id + level per node
+
+    for (const node of nodesArray) {
+      graphSize += (node.level + 1) * 8; // neighbor metadata per level
+    }
+    graphSize += totalNeighborBytes;
+    graphSize += nodeCount * 4; // vector offset table
+
+    const vectorDataOffset = graphSize;
+    const vectorDataSize = nodeCount * this.dimension * 4;
+    const totalSize = graphSize + vectorDataSize;
+
+    const buffer = new ArrayBuffer(totalSize);
+    const view = new DataView(buffer);
+    const uint8Array = new Uint8Array(buffer);
+
+    let offset = 0;
+
+    // Write header with magic, version, and vectorDataOffset
+    view.setUint32(offset, HNSWIndex.MAGIC, true); offset += 4;
+    view.setUint32(offset, HNSWIndex.FORMAT_VERSION, true); offset += 4;
+    view.setUint32(offset, this.dimension, true); offset += 4;
+    const metricCode = this.metric === 'cosine' ? 0 : this.metric === 'euclidean' ? 1 : 2;
+    view.setUint32(offset, metricCode, true); offset += 4;
+    view.setUint32(offset, this.M, true); offset += 4;
+    view.setUint32(offset, this.efConstruction, true); offset += 4;
+    view.setUint32(offset, this.maxLevel, true); offset += 4;
+    view.setUint32(offset, this.entryPointId, true); offset += 4;
+    view.setUint32(offset, nodeCount, true); offset += 4;
+    view.setUint32(offset, vectorDataOffset, true); offset += 4; // New in v3
+
+    // Write node metadata (without vectors)
+    for (let i = 0; i < nodesArray.length; i++) {
+      const node = nodesArray[i];
+      view.setUint32(offset, node.id, true); offset += 4;
+      view.setUint32(offset, node.level, true); offset += 4;
+    }
+
+    // Write neighbor metadata (counts and encoded sizes)
+    for (let i = 0; i < nodesArray.length; i++) {
+      const node = nodesArray[i];
+      const nodeEncodings = encodedNeighbors[i];
+
+      for (let l = 0; l <= node.level; l++) {
+        view.setUint32(offset, node.neighbors[l].length, true); offset += 4;
+        view.setUint32(offset, nodeEncodings[l].length, true); offset += 4;
+      }
+    }
+
+    // Write all encoded neighbor data
+    for (let i = 0; i < nodesArray.length; i++) {
+      const nodeEncodings = encodedNeighbors[i];
+      for (const encoded of nodeEncodings) {
+        uint8Array.set(encoded, offset);
+        offset += encoded.length;
+      }
+    }
+
+    // Write vector offset table (offset within vector section)
+    for (let i = 0; i < nodesArray.length; i++) {
+      view.setUint32(offset, i * this.dimension * 4, true); // Relative offset
+      offset += 4;
+    }
+
+    // Write vectors at end (for lazy loading capability)
+    for (let i = 0; i < nodesArray.length; i++) {
+      const node = nodesArray[i];
+      for (let j = 0; j < this.dimension; j++) {
+        view.setFloat32(offset, node.vector[j], true);
+        offset += 4;
+      }
+    }
+
+    return buffer;
+  }
+
+  /**
+   * Deserialize an HNSW index from a buffer.
+   *
+   * @param buffer The serialized index buffer
+   * @param options Optional loading options
+   *   - lazyLoadVectors: If true, don't load vectors immediately (v3+ only)
+   */
+  static deserialize(buffer: ArrayBuffer, options?: { lazyLoadVectors?: boolean }): HNSWIndex {
+    const view = new DataView(buffer);
+    const uint8Array = new Uint8Array(buffer);
+    const lazyLoad = options?.lazyLoadVectors ?? false;
+
+    let offset = 0;
+
+    // Check for magic header (new format v1+)
+    const possibleMagic = view.getUint32(0, true);
+    let formatVersion = 0;
+
+    if (possibleMagic === HNSWIndex.MAGIC) {
+      offset += 4; // Skip magic
+      formatVersion = view.getUint32(offset, true); offset += 4;
+
+      if (formatVersion > HNSWIndex.FORMAT_VERSION) {
+        throw new Error(`Unsupported HNSW format version: ${formatVersion}. Maximum supported: ${HNSWIndex.FORMAT_VERSION}`);
+      }
+    } else {
+      formatVersion = 0;
+      offset = 0;
+    }
+
+    // Read common header fields
+    const dimension = view.getUint32(offset, true); offset += 4;
+    const metricCode = view.getUint32(offset, true);
+    const metric = metricCode === 0 ? 'cosine' : metricCode === 1 ? 'euclidean' : 'dot_product';
+    offset += 4;
+    const M = view.getUint32(offset, true); offset += 4;
+    const efConstruction = view.getUint32(offset, true); offset += 4;
+    const maxLevel = view.getInt32(offset, true); offset += 4;
+    const entryPointId = view.getInt32(offset, true); offset += 4;
+    const nodeCount = view.getUint32(offset, true); offset += 4;
+
+    // V3+ has vectorDataOffset in header
+    let vectorDataOffset = 0;
+    if (formatVersion >= 3) {
+      vectorDataOffset = view.getUint32(offset, true); offset += 4;
+    }
+
+    const index = new HNSWIndex(dimension, metric, M, efConstruction);
+    index.maxLevel = maxLevel;
+    index.entryPointId = entryPointId;
+
+    const indexToId: number[] = new Array(nodeCount);
+
+    if (formatVersion >= 3) {
+      // V3 format: vectors at end, supports lazy loading
+      const nodeMetadata: Array<{ id: number; level: number }> = [];
+      const neighborMetadata: Array<Array<{ count: number; encodedSize: number }>> = [];
+
+      // First pass: read node metadata (no vectors here)
+      for (let i = 0; i < nodeCount; i++) {
+        const id = view.getUint32(offset, true); offset += 4;
+        const level = view.getUint32(offset, true); offset += 4;
+        indexToId[i] = id;
+        nodeMetadata.push({ id, level });
+      }
+
+      // Second pass: read neighbor metadata
+      for (let i = 0; i < nodeCount; i++) {
+        const level = nodeMetadata[i].level;
+        const levelMeta: Array<{ count: number; encodedSize: number }> = [];
+
+        for (let l = 0; l <= level; l++) {
+          const count = view.getUint32(offset, true); offset += 4;
+          const encodedSize = view.getUint32(offset, true); offset += 4;
+          levelMeta.push({ count, encodedSize });
+        }
+
+        neighborMetadata.push(levelMeta);
+      }
+
+      // Third pass: read and decode neighbor data
+      const nodeNeighbors: number[][][] = [];
+      for (let i = 0; i < nodeCount; i++) {
+        const level = nodeMetadata[i].level;
+        const neighbors = new Array<number[]>(level + 1);
+
+        for (let l = 0; l <= level; l++) {
+          const { count, encodedSize } = neighborMetadata[i][l];
+
+          if (count === 0 || encodedSize === 0) {
+            neighbors[l] = [];
+          } else {
+            const encodedSlice = uint8Array.subarray(offset, offset + encodedSize);
+            const neighborIndices = deltaDecodeNeighbors(encodedSlice, count);
+            neighbors[l] = neighborIndices.map(idx =>
+              idx >= 0 && idx < indexToId.length ? indexToId[idx] : 0
+            );
+            offset += encodedSize;
+          }
+        }
+
+        nodeNeighbors.push(neighbors);
+      }
+
+      // Read vector offset table
+      for (let i = 0; i < nodeCount; i++) {
+        const relativeOffset = view.getUint32(offset, true); offset += 4;
+        const id = nodeMetadata[i].id;
+        index.vectorOffsets.set(id, vectorDataOffset + relativeOffset);
+      }
+
+      // Create nodes and optionally load vectors
+      if (lazyLoad) {
+        // Lazy loading: store buffer, don't load vectors yet
+        index.lazyLoadEnabled = true;
+        index.vectorBuffer = buffer;
+
+        for (let i = 0; i < nodeCount; i++) {
+          const { id, level } = nodeMetadata[i];
+          // Create node with empty vector (will be loaded on demand)
+          const node: Node = {
+            id,
+            level,
+            vector: new Float32Array(dimension), // Placeholder
+            neighbors: nodeNeighbors[i]
+          };
+          index.setNode(node);
+        }
+      } else {
+        // Eager loading: load all vectors now
+        for (let i = 0; i < nodeCount; i++) {
+          const { id, level } = nodeMetadata[i];
+          const vectorOffset = index.vectorOffsets.get(id)!;
+
+          const vector = new Float32Array(dimension);
+          for (let j = 0; j < dimension; j++) {
+            vector[j] = view.getFloat32(vectorOffset + j * 4, true);
+          }
+
+          const node: Node = { id, level, vector, neighbors: nodeNeighbors[i] };
+          index.setNode(node);
+          index.vectorsLoaded.add(id);
+        }
+      }
+    } else if (formatVersion >= 2) {
+      // V2 format: delta-encoded neighbor lists, vectors inline
+      const nodeMetadata: Array<{ id: number; level: number; vector: Float32Array }> = [];
+      const neighborMetadata: Array<Array<{ count: number; encodedSize: number }>> = [];
+
+      for (let i = 0; i < nodeCount; i++) {
+        const id = view.getUint32(offset, true); offset += 4;
+        const level = view.getUint32(offset, true); offset += 4;
+        indexToId[i] = id;
+
+        const vector = new Float32Array(dimension);
+        for (let j = 0; j < dimension; j++) {
+          vector[j] = view.getFloat32(offset, true);
+          offset += 4;
+        }
+
+        nodeMetadata.push({ id, level, vector });
+      }
+
+      for (let i = 0; i < nodeCount; i++) {
+        const level = nodeMetadata[i].level;
+        const levelMeta: Array<{ count: number; encodedSize: number }> = [];
+
+        for (let l = 0; l <= level; l++) {
+          const count = view.getUint32(offset, true); offset += 4;
+          const encodedSize = view.getUint32(offset, true); offset += 4;
+          levelMeta.push({ count, encodedSize });
+        }
+
+        neighborMetadata.push(levelMeta);
+      }
+
+      for (let i = 0; i < nodeCount; i++) {
+        const { id, level, vector } = nodeMetadata[i];
+        const neighbors = new Array<number[]>(level + 1);
+
+        for (let l = 0; l <= level; l++) {
+          const { count, encodedSize } = neighborMetadata[i][l];
+
+          if (count === 0 || encodedSize === 0) {
+            neighbors[l] = [];
+          } else {
+            const encodedSlice = uint8Array.subarray(offset, offset + encodedSize);
+            const neighborIndices = deltaDecodeNeighbors(encodedSlice, count);
+            neighbors[l] = neighborIndices.map(idx =>
+              idx >= 0 && idx < indexToId.length ? indexToId[idx] : 0
+            );
+            offset += encodedSize;
+          }
+        }
+
+        const node: Node = { id, level, vector, neighbors };
+        index.setNode(node);
+      }
+    } else {
+      // V0/V1 format: raw neighbor IDs
+      for (let i = 0; i < nodeCount; i++) {
+        const id = view.getUint32(offset, true); offset += 4;
+        const level = view.getUint32(offset, true); offset += 4;
+        indexToId[i] = id;
+
+        const vector = new Float32Array(dimension);
+        for (let j = 0; j < dimension; j++) {
+          vector[j] = view.getFloat32(offset, true);
+          offset += 4;
+        }
+
+        const neighbors = new Array<number[]>(level + 1);
+        for (let l = 0; l <= level; l++) {
+          const neighborCount = view.getUint32(offset, true); offset += 4;
+          neighbors[l] = new Array(neighborCount);
+        }
+        const node: Node = { id, level, vector, neighbors };
+
+        index.setNode(node);
+      }
+
+      for (const node of index.nodes.values()) {
+        if (!node) continue;
+        for (let l = 0; l <= node.level; l++) {
+          for (let j = 0; j < node.neighbors[l].length; j++) {
+            const neighborIndex = view.getInt32(offset, true); offset += 4;
+            if (neighborIndex >= 0 && neighborIndex < indexToId.length) {
+              node.neighbors[l][j] = indexToId[neighborIndex];
+            }
+          }
+        }
+      }
+    }
+
+    return index;
+  }
+
+  /**
+   * Load a specific vector on demand (for lazy-loaded indices).
+   * Returns the vector if lazy loading is enabled, otherwise returns the already-loaded vector.
+   */
+  loadVector(nodeId: number): Float32Array | null {
+    const node = this.nodes[nodeId];
+    if (!node) return null;
+
+    // If not lazy loading or already loaded, return existing vector
+    if (!this.lazyLoadEnabled || this.vectorsLoaded.has(nodeId)) {
+      return node.vector;
+    }
+
+    // Load vector from buffer
+    if (!this.vectorBuffer) return null;
+
+    const vectorOffset = this.vectorOffsets.get(nodeId);
+    if (vectorOffset === undefined) return null;
+
+    const view = new DataView(this.vectorBuffer);
+    const vector = new Float32Array(this.dimension);
+    for (let j = 0; j < this.dimension; j++) {
+      vector[j] = view.getFloat32(vectorOffset + j * 4, true);
+    }
+
+    // Update node with loaded vector
+    node.vector = vector;
+    this.vectorsLoaded.add(nodeId);
+
+    // OPTIMIZATION: Also update flat vector storage for batch distance calculations
+    this.setFlatVector(nodeId, vector);
+
+    return vector;
+  }
+
+  /**
+   * Preload vectors for specific node IDs.
+   * Useful for warming up cache before searches.
+   */
+  preloadVectors(nodeIds: number[]): void {
+    if (!this.lazyLoadEnabled) return;
+
+    for (const nodeId of nodeIds) {
+      this.loadVector(nodeId);
+    }
+  }
+
+  /**
+   * Check if lazy loading is enabled
+   */
+  isLazyLoadEnabled(): boolean {
+    return this.lazyLoadEnabled;
+  }
+
+  /**
+   * Get lazy loading statistics
+   */
+  getLazyLoadStats(): { enabled: boolean; totalNodes: number; loadedVectors: number; memoryReduction: string } {
+    const totalNodes = this.nodeCount;
+    const loadedVectors = this.vectorsLoaded.size;
+
+    if (!this.lazyLoadEnabled) {
+      return {
+        enabled: false,
+        totalNodes,
+        loadedVectors: totalNodes,
+        memoryReduction: '0%'
+      };
+    }
+
+    const reduction = totalNodes > 0 ? ((1 - loadedVectors / totalNodes) * 100).toFixed(1) : '0';
+    return {
+      enabled: true,
+      totalNodes,
+      loadedVectors,
+      memoryReduction: `${reduction}%`
+    };
+  }
+
+  // Save to binary file using Bun APIs
+  async saveToFile(filePath: string): Promise<void> {
+    const buffer = this.serialize();
+    await Bun.write(filePath, buffer);
+  }
+
+  // Load from binary file using Bun APIs
+  static async loadFromFile(filePath: string): Promise<HNSWIndex> {
+    const file = Bun.file(filePath);
+    const buffer = await file.arrayBuffer();
+    return HNSWIndex.deserialize(buffer);
+  }
+
+  // Clean up resources
+  destroy(): void {
+    // Clear all nodes to free memory
+    this.nodes = [];
+    this.nodeCount = 0;
+    this.flatVectors = new Float32Array(0);
+    this.flatVectorsCapacity = 0;
+  }
+
+  /**
+   * Get memory usage statistics
+   */
+  getMemoryUsage(): number {
+    // Calculate approximate memory usage in bytes
+    let totalBytes = 0;
+
+    // Node objects
+    for (let i = 0; i < this.nodeCount; i++) {
+      const node = this.nodes[i];
+      if (!node) continue;
+      // Node structure: id (4 bytes), level (4 bytes), vector (4*dimension), neighbors array overhead
+      totalBytes += 8; // id + level
+      totalBytes += node.vector.length * 4; // vector data
+      totalBytes += 24; // neighbors array overhead (rough estimate)
+
+      // Neighbor connections
+      for (const neighborList of node.neighbors) {
+        totalBytes += neighborList.length * 4; // neighbor IDs
+        totalBytes += 16; // array overhead per level
+      }
+    }
+
+    // Flat vector storage
+    totalBytes += this.flatVectors.byteLength;
+
+    // Array overhead
+    totalBytes += this.nodeCount * 8; // Array entry overhead (rough estimate)
+
+    // Object overhead
+    totalBytes += 1024; // Base object overhead
+
+    return totalBytes;
+  }
+
+  /**
+   * Get all vectors for brute-force search
+   */
+  getAllVectors(): Map<number, Float32Array> {
+    const result = new Map<number, Float32Array>();
+    for (let i = 0; i < this.nodeCount; i++) {
+      const node = this.nodes[i];
+      if (node) result.set(node.id, node.vector);
+    }
+    return result;
+  }
+
+  // ============================================
+  // Quantized Search (Int8 with automatic rescoring)
+  // ============================================
+
+  /**
+   * Enable Int8 quantization for faster search with automatic rescoring.
+   * Trains the quantizer on existing vectors and quantizes them.
+   *
+   * Performance:
+   * - 4x memory reduction
+   * - 3-4x faster distance calculations
+   * - 99%+ recall with automatic rescoring
+   *
+   * @example
+   * ```typescript
+   * // After adding vectors
+   * index.enableQuantization();
+   *
+   * // Now use quantized search (automatically rescores for high recall)
+   * const results = index.searchKNNQuantized(query, 10);
+   * ```
+   */
+  enableQuantization(): void {
+    if (this.nodeCount === 0) {
+      throw new Error('Cannot enable quantization on empty index. Add vectors first.');
+    }
+
+    // Collect all vectors for training
+    const vectors: Float32Array[] = [];
+    for (let i = 0; i < this.nodeCount; i++) {
+      const node = this.nodes[i];
+      if (node) vectors.push(node.vector);
+    }
+
+    // Initialize and train scalar (int8) quantizer
+    this.scalarQuantizer = new ScalarQuantizer(this.dimension);
+    this.scalarQuantizer.train(vectors);
+
+    // Quantize all existing vectors - use array instead of Map
+    this.int8Vectors = new Array(this.nodeCount);
+    for (let i = 0; i < this.nodeCount; i++) {
+      const node = this.nodes[i];
+      if (node) {
+        this.int8Vectors[node.id] = this.scalarQuantizer.quantize(node.vector);
+      }
+    }
+
+    this.quantizationEnabled = true;
+  }
+
+  /**
+   * Check if quantization is enabled
+   */
+  isQuantizationEnabled(): boolean {
+    return this.quantizationEnabled;
+  }
+
+  /**
+   * Fast quantized search with automatic rescoring.
+   *
+   * Uses Int8 quantized vectors for initial candidate retrieval (3-4x faster),
+   * then rescores top candidates with float32 for accurate ranking.
+   *
+   * @param query Query vector
+   * @param k Number of results to return
+   * @param candidateMultiplier How many extra candidates to retrieve for rescoring (default: 3)
+   * @param efSearch Search effort parameter
+   * @returns Array of {id, distance} results (same format as searchKNN)
+   *
+   * Performance:
+   * - 3-4x faster than float32 for distance calculations
+   * - 99%+ recall with candidateMultiplier=3 (automatic rescoring)
+   * - 4x memory reduction
+   */
+  searchKNNQuantized(
+    query: Float32Array,
+    k: number,
+    candidateMultiplier: number = 3,
+    efSearch?: number
+  ): Array<{ id: number; distance: number }> {
+    // Fallback to standard search if quantization not enabled
+    if (!this.quantizationEnabled) {
+      return this.searchKNN(query, k, efSearch);
+    }
+
+    if (this.entryPointId === -1 || this.nodeCount === 0) {
+      return [];
+    }
+
+    // Normalize query if needed - reuse buffer for efficiency
+    let normalizedQuery = query;
+    if (this.vectorsAreNormalized) {
+      this.queryNormBuffer.set(query);
+      normalizedQuery = this.normalizeVector(this.queryNormBuffer);
+    }
+
+    // Get more candidates than needed for rescoring
+    const numCandidates = k * candidateMultiplier;
+    const effectiveEf = efSearch || Math.max(numCandidates * 2, 50);
+
+    // Phase 1: Fast HNSW navigation using float32 (only for graph traversal)
+    let currentEntryPoint = this.nodes[this.entryPointId]!;
+    const entryVector = this.getNodeVector(this.entryPointId);
+    if (!entryVector) return [];
+    let currentBest = { id: currentEntryPoint.id, distance: this.calculateDistance(normalizedQuery, entryVector) };
+
+    for (let l = this.maxLevel; l > 0; l--) {
+      const result = this.greedySearch(normalizedQuery, currentEntryPoint, l);
+      if (result.distance < currentBest.distance) {
+        currentBest = result;
+        currentEntryPoint = this.nodes[currentBest.id]!;
+      }
+    }
+
+    // Phase 2: Search layer 0 with quantized distance for speed
+    const candidates = this.searchLayerQuantized(normalizedQuery, currentBest, 0, effectiveEf);
+
+    // Phase 3: Rescore top candidates with float32 for accuracy
+    // Pre-allocate rescored array
+    const rescoreCount = Math.min(candidates.length, numCandidates);
+    const rescored = new Array<{ id: number; distance: number }>(rescoreCount);
+
+    for (let i = 0; i < rescoreCount; i++) {
+      const c = candidates[i];
+      const nodeVector = this.getNodeVector(c.id);
+      if (nodeVector) {
+        rescored[i] = { id: c.id, distance: this.calculateDistance(normalizedQuery, nodeVector) };
+      } else {
+        rescored[i] = c; // Keep original if node not found
+      }
+    }
+
+    // Sort by accurate distance
+    rescored.sort((a, b) => a.distance - b.distance);
+
+    // Return top k
+    if (rescored.length > k) rescored.length = k;
+    return rescored;
+  }
+
+  /**
+   * Search layer using Int8 quantized distances for speed.
+   * Same algorithm as searchLayer but uses faster Int8 distance calculations.
+   */
+  private searchLayerQuantized(
+    query: Float32Array,
+    nearest: { id: number; distance: number },
+    layer: number,
+    ef: number
+  ): Array<{ id: number; distance: number }> {
+    // Quantize query once
+    const int8Query = this.scalarQuantizer ? this.scalarQuantizer.quantize(query) : null;
+
+    // Clear visited tracking
+    this.clearVisited();
+
+    // Ensure heaps are large enough, then clear and reuse
+    this.ensureHeapCapacity(ef);
+    this.candidatesHeap.clear();
+    this.resultsHeap.clear();
+
+    // Initialize with entry point
+    this.markVisited(nearest.id);
+    this.candidatesHeap.push(nearest.id, nearest.distance);
+    this.resultsHeap.push(nearest.id, nearest.distance);
+
+    let furthestResultDist = nearest.distance;
+
+    while (!this.candidatesHeap.isEmpty()) {
+      const closestCandidateDist = this.candidatesHeap.peekValue();
+      const closestCandidateId = this.candidatesHeap.pop();
+
+      if (closestCandidateId === -1) continue;
+
+      // TERMINATION
+      if (this.resultsHeap.size() >= ef && closestCandidateDist > furthestResultDist) {
+        break;
+      }
+
+      const node = this.nodes[closestCandidateId];
+      if (!node) continue;
+
+      const neighbors = node.neighbors[layer] || [];
+
+      for (const neighborId of neighbors) {
+        if (this.isVisited(neighborId)) continue;
+        this.markVisited(neighborId);
+
+        // Use Int8 quantized distance for speed
+        let distance: number;
+        if (int8Query) {
+          const neighborInt8 = this.int8Vectors[neighborId];
+          if (neighborInt8) {
+            // Use appropriate int8 distance based on metric
+            if (this.metric === 'cosine') {
+              distance = cosineDistanceInt8(int8Query, neighborInt8);
+            } else {
+              distance = l2SquaredInt8(int8Query, neighborInt8);
+            }
+          } else {
+            // Fallback to float32
+            const neighborNode = this.nodes[neighborId];
+            if (!neighborNode) continue;
+            distance = this.calculateDistance(query, neighborNode.vector);
+          }
+        } else {
+          // Fallback to float32
+          const neighborNode = this.nodes[neighborId];
+          if (!neighborNode) continue;
+          distance = this.calculateDistance(query, neighborNode.vector);
+        }
+
+        if (this.resultsHeap.size() < ef || distance < furthestResultDist) {
+          this.candidatesHeap.push(neighborId, distance);
+          this.resultsHeap.push(neighborId, distance);
+
+          if (this.resultsHeap.size() > ef) {
+            this.resultsHeap.pop();
+          }
+          furthestResultDist = this.resultsHeap.peekValue();
+        }
+      }
+    }
+
+    // Extract results from max-heap
+    const resultCount = this.resultsHeap.size();
+    const results: Array<{ id: number; distance: number }> = new Array(resultCount);
+    let idx = resultCount - 1;
+    while (!this.resultsHeap.isEmpty()) {
+      const dist = this.resultsHeap.peekValue();
+      const id = this.resultsHeap.pop();
+      results[idx--] = { id, distance: dist };
+    }
+
+    return results;
+  }
+
+  /**
+   * Get quantization statistics
+   */
+  getQuantizationStats(): {
+    enabled: boolean;
+    vectorCount: number;
+    memoryReduction: string;
+    expectedSpeedup: string;
+  } {
+    const vectorCount = this.nodeCount;
+    const float32Size = vectorCount * this.dimension * 4;
+
+    if (this.quantizationEnabled) {
+      const int8Size = vectorCount * this.dimension;
+      const reduction = (float32Size / int8Size).toFixed(1);
+      return {
+        enabled: true,
+        vectorCount,
+        memoryReduction: `${reduction}x (${(float32Size / 1024 / 1024).toFixed(1)}MB → ${(int8Size / 1024 / 1024).toFixed(1)}MB)`,
+        expectedSpeedup: '3-4x for distance calculations'
+      };
+    }
+
+    return {
+      enabled: false,
+      vectorCount,
+      memoryReduction: '1x (no quantization)',
+      expectedSpeedup: '1x (baseline)'
+    };
+  }
+}