> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# VectoriaDB

> Lightweight in-memory vector database for semantic search with offline embeddings

VectoriaDB is a production-ready in-memory vector database built on transformers.js. Use it to surface the right tool, prompt, or document snippet from natural-language queries without shipping data to an external service.

## Features

<CardGroup cols={3}>
  <Card title="Offline Embeddings" icon="microchip">
    Embeddings run locally via transformers.js, so your data never leaves the server and you avoid API quotas.
  </Card>

  <Card title="Type-safe Metadata" icon="shield-check">
    Strong generics ensure every document you index keeps the same shape as your metadata interface.
  </Card>

  <Card title="Operational Guardrails" icon="gauge">
    Built-in rate limits, batch validation, HNSW indexing, and storage adapters keep the index production ready.
  </Card>
</CardGroup>

## When to Use VectoriaDB

* **Tool discovery** - Surface the right tool from natural-language queries
* **Document search** - Semantic search over documents, prompts, or code snippets
* **Recommendation systems** - Find similar items based on text embeddings
* **Offline-first applications** - No external API dependencies

<Note>
  The default Xenova `all-MiniLM-L6-v2` model is \~22 MB. The first initialization downloads and caches it under `cacheDir`; subsequent boots reuse the local copy.
</Note>

## Installation

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
npm install vectoriadb
```

## Quick Start

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { VectoriaDB, DocumentMetadata } from 'vectoriadb';

interface ToolDocument extends DocumentMetadata {
  toolName: string;
  owner: string;
  tags: string[];
  risk: 'safe' | 'destructive';
}

const toolIndex = new VectoriaDB<ToolDocument>({
  cacheDir: './.cache/transformers',
  defaultSimilarityThreshold: 0.4,
});

await toolIndex.initialize(); // downloads and warms the embedding model once

// Add a document
await toolIndex.add('users:list', 'List all users with pagination', {
  id: 'users:list',
  toolName: 'list',
  owner: 'users',
  tags: ['read'],
  risk: 'safe',
});

// Search
const results = await toolIndex.search('find users');
console.log(results[0].metadata.toolName); // 'list'
```

`initialize()` must run before `add`, `search`, or `update`. Calling it twice is safe because VectoriaDB short-circuits if it is already ready.

## Core Concepts

### Documents

Each document has:

* **id** - Unique identifier
* **text** - Natural language text to embed
* **metadata** - Type-safe custom data

### Embeddings

VectoriaDB generates embeddings locally using transformers.js. The default model is `all-MiniLM-L6-v2` which provides good quality with fast inference.

### Similarity Search

Search returns documents ranked by cosine similarity to your query. You can filter results by metadata and set minimum similarity thresholds.

## Configuration Options

| Option                       | Type    | Default                     | Description                    |
| ---------------------------- | ------- | --------------------------- | ------------------------------ |
| `modelName`                  | string  | `'Xenova/all-MiniLM-L6-v2'` | Embedding model to use         |
| `cacheDir`                   | string  | `'./.cache/transformers'`   | Model cache directory          |
| `dimensions`                 | number  | Auto-detected               | Vector dimensions              |
| `defaultSimilarityThreshold` | number  | `0.3`                       | Minimum similarity score       |
| `defaultTopK`                | number  | `10`                        | Default results limit          |
| `useHNSW`                    | boolean | `false`                     | Enable HNSW index              |
| `maxDocuments`               | number  | `100000`                    | Max documents (DoS protection) |
| `maxDocumentSize`            | number  | `1000000`                   | Max document size in chars     |
| `maxBatchSize`               | number  | `1000`                      | Max batch operation size       |
| `verboseErrors`              | boolean | `true`                      | Enable detailed errors         |

## Related Documentation

<CardGroup cols={2}>
  <Card title="Indexing" icon="plus" href="/vectoriadb/guides/indexing">
    Adding and updating documents
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/vectoriadb/guides/search">
    Querying the index
  </Card>

  <Card title="Persistence" icon="floppy-disk" href="/vectoriadb/guides/persistence">
    Storage adapters
  </Card>

  <Card title="HNSW" icon="chart-network" href="/vectoriadb/guides/hnsw">
    Scaling to large datasets
  </Card>

  <Card title="TF-IDF" icon="text" href="/vectoriadb/guides/tfidf">
    Zero-dependency alternative
  </Card>
</CardGroup>