Skip to main content
Brian Sunter
Launched

Verso

Embedded TypeScript vector database for Bun, Node.js, and browsers, with portable HNSW search and OPFS persistence.

Visit Project View Source
TypeScript Vector Search HNSW Embeddings RAG Bun OPFS
Cover image for Verso

Overview

Verso is an embedded TypeScript vector database for Bun, Node.js, and browser applications. Its stable API is intentionally small: VectorDB opens a database, collections hold typed records and vectors, and collection search returns matches. HNSW, storage backends, workers, WAL, and quantization are advanced extension surfaces rather than root-package contract.

Node and Bun use filesystem storage; browsers use OPFS when available. Verso is designed for local vector retrieval without a separate service, while full-text indexing, hybrid fusion, query expansion, and model reranking remain application-layer concerns.

Verso vector index architecture diagram
Verso vector index architecture diagram

Features

HNSW index

  • Hierarchical Navigable Small World graph for approximate nearest neighbor search
  • Cosine, Euclidean, and dot product distance metrics
  • Build-time (M, efConstruction) and query-time (efSearch) tuning
  • Advanced HNSW tuning is available from the explicit verso-db/advanced surface

Int8 quantization

A ScalarQuantizer trains on a sample of vectors and produces an Int8 representation that uses 4x less memory than the original Float32 vectors, with minimal recall loss. A QuantizedVectorStore keeps the compact form in memory for environments where every byte matters.

Multi-platform storage

Node and Bun use filesystem storage; browsers use Origin Private File System (OPFS) when available. A requested persistent backend fails closed by default, with an explicit in-memory fallback when an application chooses it.

Metadata filtering

Each vector can carry JSON-compatible metadata, and collection search accepts strict filters alongside vector retrieval:

ts
const results = await documents.search({
  vector: queryEmbedding,
  limit: 10,
  filter: {
    category: { $in: ['tech', 'science'] },
    score: { $gte: 0.8 }
  }
});

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

Search strategies and advanced surfaces

The root collection API supports exact and approximate search, accuracy and tuning options, batch search, filters, and explain data. HNSW, storage, workers, WAL, and quantization APIs are explicit advanced subpaths; full-text indexing, hybrid fusion, query expansion, and model reranking belong in the application layer.

Batch and upsert

Insert, upsert, batch insert/import, update, delete, list/scan, snapshot/restore, and compact() operations are available for collection workflows.

Quick start

ts
import { VectorDB } from 'verso-db';

const db = await VectorDB.open({ path: './vectors' });
const documents = await db.createCollection('documents', {
  vector: { dimensions: 3, metric: 'cosine' },
  index: { type: 'hnsw', profile: 'balanced' },
});

await documents.insert([{
  id: 'doc-1',
  vector: new Float32Array([1, 0, 0]),
  metadata: { title: 'HNSW explained', category: 'tech' },
}]);

const result = await documents.search({
  vector: new Float32Array([1, 0.1, 0]),
  limit: 1,
});
console.log(result.matches);
await db.close();

Technology stack

  • TypeScript, distributed on npm as verso-db
  • HNSW implementation written from scratch
  • Bun and Node.js runtime support, plus a browser build using OPFS
  • Vitest for unit tests, plus a separate browser test suite
  • Recall, storage, and end-to-end benchmark suites against the Cohere Wikipedia dataset

Share this project