Vectra

Vectra is a local, file-backed vector database designed for high-performance similarity search with minimal infrastructure. It functions similarly to managed services like Pinecone or Qdrant, but stores each index as a local folder on disk.

Key Features:

• Zero Infrastructure: No servers or managed services required; everything is stored in local folders.
• Fast Lookups: Achieves sub-millisecond to low-millisecond latency.
• Metadata Filtering: Supports MongoDB-style query operators for filtering results.
• Flexible Embeddings: Supports OpenAI, Azure, OSS endpoints, or local HuggingFace models (via LocalEmbeddings or TransformersEmbeddings) without requiring API keys.
• Pluggable Storage: Supports Filesystem, IndexedDB (for browsers), in-memory, or custom backends.
• Cross-Language Access: Includes a built-in gRPC server with bindings for Python, C#, Rust, Go, Java, and TypeScript.
• Multiple Formats: Supports human-readable JSON or highly efficient Protocol Buffers (40-50% smaller).

Vectra separates index logic from file I/O using the FileStorage interface. This abstraction allows you to swap storage backends (e.g., moving from local disk to S3 or IndexedDB) without modifying your core index code. Every index operation—reading vectors, writing metadata, or listing files—is routed through the chosen FileStorage implementation.

Built-in Implementations

Behavioral Contract

When implementing or using storage, note these key behaviors:

• createFile must throw if the file already exists.
• upsertFile should create the file if it doesn't exist or overwrite it if it does.
• createFolder must create parent directories recursively.
• deleteFolder must remove the folder and all its contents.
• listFiles accepts an optional filter: 'files', 'folders', or 'all' (default).

import { FileStorage } from 'vectra';

interface FileStorage {
  createFile(filePath: string, content: Buffer | string): Promise<void>;
  createFolder(folderPath: string): Promise<void>;
  deleteFile(filePath: string): Promise<void>;
  deleteFolder(folderPath: string): Promise<void>;
  getDetails(fileOrFolderPath: string): Promise<FileDetails>;
  listFiles(folderPath: string, filter?: 'files' | 'folders' | 'all'): Promise<FileDetails[]>;
  pathExists(fileOrFolderPath: string): Promise<boolean>;
  readFile(filePath: string): Promise<Buffer>;
  upsertFile(filePath: string, content: Buffer | string): Promise<void>;
}

interface FileDetails {
  name: string;
  path: string;
  isFolder: boolean;
  fileType?: string;
}

Vectra supports a 'skip-if-unchanged' optimization during document upserts. When you upsert a document with a URI that already exists in the index, Vectra computes a hash of the content (text, docType, and metadata). If the new hash matches the existing hash stored in the catalog, the operation short-circuits: no new embeddings are created, and no document deletion/re-insertion occurs. This significantly reduces latency and embedding costs during synchronization tasks.

Key Behaviors:

• Identical Content: If text and metadata are identical, the upsert returns the existing LocalDocument without calling the embedding provider.
• Metadata Sensitivity: Changes to metadata (even if text is identical) or changes to docType will trigger a full re-embed because they affect the content hash.
• Canonical Serialization: Metadata key order does not affect the hash; identical values with different key orders will still trigger a short-circuit.
• Force Re-embedding: If you need to bypass the hash check and force a re-embedding of an existing URI, use the force: true option.

// Example conceptual usage of the upsert with force option
await index.upsertDocument({
  uri: 'https://example.com/doc',
  text: 'some content',
  docType: 'text',
  metadata: { author: 'stevenic' },
  force: true // Forces re-embedding even if content is unchanged
});

Vectra uses a codec abstraction to manage how index data, catalogs, and metadata are serialized to disk. This decoupling allows the engine to support multiple storage formats without changing the core index logic.

There are two primary implementations:

1. JsonCodec: The default implementation. It uses JSON.stringify() and JSON.parse(). It is backward-compatible and requires no extra dependencies.
2. ProtobufCodec: An opt-in binary format using Protocol Buffers. It is more efficient for large indexes because vectors are stored as packed float arrays (reducing size from ~8-12 KB to ~6 KB for 1536-dimensional vectors) and offers faster I/O.

Note: To use the ProtobufCodec, you must manually install the protobufjs package, as it is an optional dependency: npm install protobufjs.

// Example of the IndexCodec interface structure
export interface IndexCodec {
  readonly extension: string; // e.g., '.json' or '.pb'
  serializeIndex(data: IndexData): Buffer;
  deserializeIndex(buffer: Buffer): IndexData;
  serializeCatalog(catalog: DocumentCatalog): Buffer;
  deserializeCatalog(buffer: Buffer): DocumentCatalog;
  serializeMetadata(metadata: Record<string, MetadataTypes>): Buffer;
  deserializeMetadata(buffer: Buffer): Record<string, MetadataTypes>;
}