Verso

High-performance vector search with HNSW indexing for Bun and Browser.

Performance

| Metric | Value | |--------|-------| | Recall@10 | 100% on 768D Wikipedia embeddings | | Query Performance | 95.5% improvement from baseline | | Memory Reduction | 4x with Int8 quantization |

Features

• HNSW Algorithm - Hierarchical Navigable Small World for fast approximate nearest neighbor search
• Multiple Distance Metrics - Cosine similarity, Euclidean, dot product
• Int8 Quantization - 4x memory reduction with minimal recall loss
• Multi-Platform - Bun (file system) and Browser (OPFS)
• Parameter Presets - Pre-tuned configurations for different use cases
• Batch Queries - Efficient batch processing for throughput
• Metadata Filtering - MongoDB-style query operators

Installation

# Bun
bun add verso

# npm
npm install verso

Quick Start

import { VectorDB, getRecommendedPreset } from 'verso';

// Create database
const db = new VectorDB();

// Get recommended parameters for your vector dimensions
const preset = getRecommendedPreset(768);

// Create collection
const collection = await db.createCollection('documents', {
  dimension: 768,
  metric: 'cosine',
  M: preset.M,
  efConstruction: preset.efConstruction
});

// Add vectors
await collection.add({
  ids: ['doc1', 'doc2', 'doc3'],
  vectors: [
    new Float32Array(768).fill(0.1),
    new Float32Array(768).fill(0.2),
    new Float32Array(768).fill(0.3)
  ],
  metadata: [
    { title: 'Document 1', category: 'tech' },
    { title: 'Document 2', category: 'science' },
    { title: 'Document 3', category: 'tech' }
  ]
});

// Query
const results = await collection.query({
  queryVector: new Float32Array(768).fill(0.15),
  k: 10,
  efSearch: preset.efSearch
});

console.log(results);
// [{ id: 'doc1', score: 0.99, metadata: { title: 'Document 1', ... } }, ...]

API Reference

VectorDB

Main database class for managing collections.

const db = new VectorDB();

// Create collection
const collection = await db.createCollection('name', {
  dimension: 768,
  metric: 'cosine',  // 'cosine' | 'euclidean' | 'dot_product'
  M: 16,             // Max connections per node
  efConstruction: 200 // Build-time search depth
});

// Get existing collection
const collection = await db.getCollection('name');

// List collections
const names = await db.listCollections();

// Delete collection
await db.deleteCollection('name');

Collection

// Add vectors
await collection.add({
  ids: string[],
  vectors: Float32Array[],
  metadata?: object[]
});

// Query
const results = await collection.query({
  queryVector: Float32Array,
  k: number,
  efSearch?: number,
  filter?: FilterExpression
});

// Batch query
const batchResults = await collection.queryBatch({
  queryVectors: Float32Array[],
  k: number,
  efSearch?: number
});

// Delete vectors
await collection.delete(ids: string[]);

// Get collection info
const info = await collection.info();

Metadata Filtering

const results = await collection.query({
  queryVector: queryVec,
  k: 10,
  filter: {
    category: 'tech',           // Exact match
    score: { $gt: 0.5 },        // Greater than
    tags: { $in: ['ai', 'ml'] } // In array
  }
});

Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin

Parameter Presets

import { getRecommendedPreset, getRAGPreset, PRESETS } from 'verso';

// Automatic preset based on dimensions
const preset = getRecommendedPreset(768);

// RAG-optimized preset (high recall)
const ragPreset = getRAGPreset(768);

// Available presets
PRESETS.LOW_DIM        // <= 128 dimensions
PRESETS.MEDIUM_DIM     // 256-512 dimensions
PRESETS.HIGH_DIM       // 768+ dimensions
PRESETS.VERY_HIGH_DIM  // 1024+ dimensions
PRESETS.SMALL_DATASET  // < 10k vectors
PRESETS.LARGE_DATASET  // 100k+ vectors
PRESETS.MAX_RECALL     // Prioritize accuracy
PRESETS.LOW_LATENCY    // Prioritize speed

Int8 Quantization

Reduce memory usage by 4x with minimal recall loss:

import { ScalarQuantizer, QuantizedVectorStore } from 'verso';

// Create quantizer
const quantizer = new ScalarQuantizer(768);

// Train on sample vectors
quantizer.train(sampleVectors);

// Quantize vectors
const quantized = quantizer.quantize(vector);

// Use with QuantizedVectorStore for integrated search
const store = new QuantizedVectorStore(768);
store.add(ids, vectors);
const results = store.search(queryVector, k);

Storage Backends

Verso automatically selects the appropriate storage backend:

| Environment | Backend | Storage | |-------------|---------|---------| | Bun | BunStorageBackend | File system | | Browser | OPFSBackend | Origin Private File System | | Fallback | MemoryBackend | In-memory (no persistence) |

import { createStorageBackend, getRecommendedStorageType } from 'verso';

// Automatic detection
const backend = await createStorageBackend({
  basePath: './vectors'
});

// Check available types
const type = getRecommendedStorageType(); // 'bun' | 'opfs' | 'memory'

Benchmarks

See docs/BENCHMARKS.md for detailed performance analysis.

Quick Summary (768D vectors, Cohere Wikipedia dataset):

• 100% Recall@10 with optimized parameters
• 95.5% query performance improvement through optimizations
• 4x memory reduction with Int8 quantization

Development

# Install dependencies
bun install

# Run tests
bun test

# Run browser tests
bun run test:browser

# Build
bun run build

# Run benchmarks
bun run bench

License

MIT