Vectra is a lightweight, local, file-backed, in-memory vector database designed for Node.js (v22.x+) and browser environments. Currently at version 0.14.0, it follows an active release cadence, introducing significant features and occasional breaking changes. Its key differentiators include operating entirely locally with a file-system backend (each index corresponds to a folder on disk), offering Pinecone-compatible metadata filtering, and integrating hybrid BM25 keyword search for advanced Retrieval-Augmented Generation (RAG) pipelines. The package also provides an optional gRPC server for cross-language access, comprehensive browser and Electron support via a dedicated `vectra/browser` entry point, and the capability to use local embeddings with HuggingFace models without requiring external API keys. Data storage can be optimized using Protocol Buffers for more compact files.
npm install vectraVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize a `LocalDocumentIndex`, ensure its creation, upsert a document, and perform a semantic search using OpenAI embeddings in Node.js. It includes necessary environment variable checks for API keys.
Replace `axios`-specific configurations with `requestConfig` (a `RequestInit` object) on embedding provider options, e.g., `new OpenAIEmbeddings({ ..., requestConfig: { headers: { 'Authorization': 'Bearer ...' } } })`.Ensure your development and deployment environments are running Node.js 22.x or later. Use a Node Version Manager (e.g., `nvm`) to update: `nvm install 22 && nvm use 22`.
Always check for index existence with `await docs.isIndexCreated()` and conditionally call `await docs.createIndex({ version: 1 })` before interacting with the index, especially in application startup logic.Change your imports from `import { Symbol } from 'vectra';` to `import { Symbol } from 'vectra/browser';` when targeting browser or Electron environments.Upgrade your Node.js environment to version 22.x or higher. For example, using nvm: `nvm install 22 && nvm use 22`.
Use ES module `import` syntax: `import { LocalDocumentIndex } from 'vectra';`. If strictly using CommonJS, ensure proper destructuring: `const { LocalDocumentIndex } = require('vectra');`.Ensure `process.env.OPENAI_API_KEY` is set in your environment, or pass the API key directly in the `OpenAIEmbeddings` constructor: `new OpenAIEmbeddings({ apiKey: 'your-api-key' })`.Ensure you are using Node.js v22.x or higher (due to Vectra's requirements) which has `fetch` built-in. If you encounter this in a very specific environment, consider explicitly polyfilling `fetch` if Node.js v22.x is not an option (though it's required by Vectra v0.14+).