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

``bash


Bun

bun add verso

npm

npm install verso
`

Quick Start

`typescript
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

$3

Main database class for managing collections.

`typescript
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');
`

$3

`typescript
// 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();
`

$3

`typescript
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

$3

`typescript
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
`

$3

Reduce memory usage by 4x with minimal recall loss:

`typescript
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) |

`typescript
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

`bash


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