Skip to content

Guide: Introduction

This page explains what Vecnest is, how it works, and when to use it.

What is Vecnest?

Vecnest is a browser-based vector database. It stores vectors (numeric arrays) and metadata in IndexedDB and lets you run similarity search over them. Optionally, it can embed text into vectors using Transformers.js so you can add and search by natural language—all in the browser, no server.

Core concepts

Vectors

A vector is an array of numbers, e.g. [0.1, -0.2, 0.5, ...]. In Vecnest, vectors typically come from embeddings: numerical representations of text (or other data) that capture meaning. Similar texts produce similar vectors.

Given a query vector, Vecnest finds stored vectors that are most similar to it. Similarity is measured with cosine similarity (higher = more similar). This enables semantic search: e.g. query “machine learning” and retrieve documents about “neural networks” or “AI” even if those words never appear.

IndexedDB storage

Vecnest uses IndexedDB to persist vectors and metadata. Data survives page reloads and stays same-origin. Storage is subject to browser quotas (often gigabytes per origin).

How it works (high level)

  1. Add data — You add text (Vecnest embeds it) or raw vectors. Each item is stored with optional metadata (e.g. source, category).
  2. Search — You provide a query (text or vector). Vecnest finds the top-k most similar vectors and returns them with scores and metadata.
  3. Optional filters — You can filter results by metadata (e.g. category: 'docs', score >= 0.8).

Under the hood, Vecnest uses HNSW (Hierarchical Navigable Small World) for approximate nearest neighbor search when possible, with a brute-force fallback. Web Workers can run search in a background thread to keep the UI responsive.

When to use Vecnest

Use case Fit
Offline / local-first RAG ✅ Data and search run entirely in the browser.
Privacy-preserving search ✅ No embeddings or vectors sent to a server.
Prototypes and demos ✅ Add vector search without deploying a backend.
Small–medium datasets ✅ Suited to thousands of vectors; very large sets may need tuning.
Server-side bulk indexing ❌ Vecnest is browser-only; use a server-side vector DB for that.

What you’ll learn in this guide

  • JavaScript API — VecnestDB, raw vectors, addText / searchText, and low-level APIs.
  • React hooks — useVecnest, useSearch, useSearchText and recommended patterns.
  • CRUD and list — Insert, update, delete, list, and count.
  • Search and filters — Search options, HNSW, Workers, and metadata filtering.

Next step

Continue with JavaScript API for a detailed walkthrough of the core API and code snippets.