vectra

Stores vector embeddings and metadata in JSON files on disk while maintaining an in-memory index for fast similarity search. Uses a hybrid architecture where the file system serves as the persistent store and RAM holds the active search index, enabling both durability and performance without requiring a separate database server. Supports automatic index persistence and reload cycles.

Implements vector similarity search using cosine distance calculation on normalized embeddings, with support for alternative distance metrics. Performs brute-force similarity computation across all indexed vectors, returning results ranked by distance score. Includes configurable thresholds to filter results below a minimum similarity threshold.

Accepts vectors of configurable dimensionality and automatically normalizes them for cosine similarity computation. Validates that all vectors have consistent dimensions and rejects mismatched vectors. Supports both pre-normalized and unnormalized input, with automatic L2 normalization applied during insertion.

Exports the entire vector database (embeddings, metadata, index) to standard formats (JSON, CSV) for backup, analysis, or migration. Imports vectors from external sources in multiple formats. Supports format conversion between JSON, CSV, and other serialization formats without losing data.

Implements BM25 (Okapi BM25) lexical search algorithm for keyword-based retrieval, then combines BM25 scores with vector similarity scores using configurable weighting to produce hybrid rankings. Tokenizes text fields during indexing and performs term frequency analysis at query time. Allows tuning the balance between semantic and lexical relevance.

Supports filtering search results using a Pinecone-compatible query syntax that allows boolean combinations of metadata predicates (equality, comparison, range, set membership). Evaluates filter expressions against metadata objects during search, returning only vectors that satisfy the filter constraints. Supports nested metadata structures and multiple filter operators.

Integrates with multiple embedding providers (OpenAI, Azure OpenAI, local transformer models via Transformers.js) to generate vector embeddings from text. Abstracts provider differences behind a unified interface, allowing users to swap providers without changing application code. Handles API authentication, rate limiting, and batch processing for efficiency.

Runs entirely in the browser using IndexedDB for persistent storage, enabling client-side vector search without a backend server. Synchronizes in-memory index with IndexedDB on updates, allowing offline search and reducing server load. Supports the same API as the Node.js version for code reuse across environments.

Accepts multiple vectors and metadata objects in a single operation, inserting them into the vector database and updating the search index atomically. Handles deduplication by vector ID and supports upsert semantics (insert or update). Batching improves throughput compared to single-vector insertions by amortizing index update costs.

Removes vectors from the database by ID and updates the search index to reflect deletions. Supports bulk deletion of multiple vectors. Includes index compaction and cleanup operations to reclaim disk space and optimize search performance after many deletions.

Returns search results with associated metadata objects, allowing applications to access both similarity scores and rich contextual information. Supports projection to return only specified metadata fields, reducing payload size. Metadata is stored alongside vectors and retrieved without additional lookups.

Serializes the in-memory search index to JSON files on disk, enabling index snapshots and recovery after application restarts. Supports incremental persistence (only changed vectors) and full index dumps. Deserializes persisted indices back into memory on application startup, restoring search capability without recomputing embeddings.