@groundai/vector - In-Browser Vector Database

GroundAI Vector is a high-performance, in-browser vector database with pluggable storage backends and Rust WASM compute modules.

Getting started

Install

Install from npm using your preferred package manager:

npm install @groundai/vector
# or
pnpm add @groundai/vector
# or
yarn add @groundai/vector

GroundAI Vector is designed for modern browser environments. It uses IndexedDB or OPFS for storage and WebAssembly for compute.

Create a client

The main entrypoint is the async createClient function:

import { createClient } from '@groundai/vector';

async function main() {
  const client = await createClient({
    // Storage backend: 'indexeddb' (default) or 'opfs'
    storage: 'indexeddb',
    // Optional database name (default: 'groundai_vector')
    database_name: 'my_vector_db',
    // Enable verbose logging while developing
    debug: true,
  });

  // Use the client...
}

main().catch(console.error);

Create a collection and add/query vectors

Once you have a client, you can create (or get) a collection and start adding/querying vectors:

import { createClient, type DistanceMetric } from '@groundai/vector';

async function runExample() {
  const client = await createClient({
    storage: 'indexeddb',
    database_name: 'example_db',
  });

  // Create or get a collection
  const collection = await client.getOrCreateCollection({
    name: 'documents',
    metadata: {
      description: 'My document embeddings',
      dimensions: 768,
      distanceMetric: 'cosine' as DistanceMetric,
    },
  });

  // Add a single vector
  const embedding: number[] = /* your embedding vector */ [];

  await collection.add({
    ids: ['doc-1'],
    vectors: [embedding],
    metadatas: [{ title: 'Hello world' }],
    documents: ['Hello world body'],
  });

  // Query for similar vectors
  const queryEmbedding: number[] = /* embedding for your query */ [];

  const results = await collection.query({
    queryVectors: [queryEmbedding],
    nResults: 5,
    include: ['metadatas', 'documents', 'distances'],
  });

  console.log(results);

  await client.close();
}

runExample().catch(console.error);

Examples

This repository includes two example apps built with Vite:

• examples/semantic-search-demo – text semantic search using GroundAI Vector
• examples/image-similarity-demo – image similarity search using CLIP embeddings

See the READMEs in those folders for setup and usage details.

License

MIT