tiny-vector-db

A lightweight vector search SDK for Node.js.

tiny-vector-db stores embeddings locally, performs cosine-similarity search, and keeps embedding integration optional so you can use OpenAI or your own provider.

Install

npm install tiny-vector-db

Features

• In-memory storage by default
• JSON file persistence with automatic writes
• Cosine similarity search
• Optional OpenAI embedding helper
• Custom embedder support for any provider
• Typed TypeScript API

API

class MiniVectorDB {
  constructor(options?: DBOptions);

  add(item: VectorItem): Promise<void>;

  addMany(items: VectorItem[]): Promise<void>;

  search(queryVector: number[], k?: number): Promise<SearchResult[]>;

  searchText(query: string, k?: number): Promise<SearchResult[]>;

  delete(id: string): Promise<void>;

  clear(): Promise<void>;
}

type VectorItem = {
  id: string;
  vector: number[];
  metadata?: Record<string, unknown>;
};

type SearchResult = {
  id: string;
  score: number;
  metadata?: Record<string, unknown>;
};

type DBOptions = {
  storage?: "memory" | "json" | "sqlite";
  path?: string;
  embedder?: (text: string) => Promise<number[]>;
  apiKey?: string;
  embeddingModel?: string;
  baseUrl?: string;
};

Quick Start

In-memory search

import { MiniVectorDB } from "tiny-vector-db";

const db = new MiniVectorDB();

await db.add({
  id: "hello",
  vector: [0.9, 0.1, 0.1],
  metadata: { text: "hello world" },
});

await db.add({
  id: "goodbye",
  vector: [0.1, 0.9, 0.1],
  metadata: { text: "goodbye world" },
});

const results = await db.search([1, 0, 0], 1);
console.log(results);

JSON persistence

import { MiniVectorDB } from "tiny-vector-db";

const db = new MiniVectorDB({
  storage: "json",
  path: "./db.json",
});

await db.add({
  id: "1",
  vector: [0.3, 0.4, 0.5],
  metadata: { text: "hello world" },
});

OpenAI embeddings

import { MiniVectorDB, embed } from "tiny-vector-db";

const db = new MiniVectorDB({
  storage: "json",
  path: "./db.json",
  apiKey: process.env.OPENAI_API_KEY,
});

await db.add({
  id: "1",
  vector: await embed("hello world"),
  metadata: { text: "hello world" },
});

const results = await db.searchText("greeting", 3);
console.log(results);

Custom embedder

import { MiniVectorDB } from "tiny-vector-db";

const fakeEmbedder = async (text: string) => {
  const code = text.length;
  return [code, code / 2, code / 4];
};

const db = new MiniVectorDB({ embedder: fakeEmbedder });

await db.add({
  id: "1",
  vector: await fakeEmbedder("hello world"),
  metadata: { text: "hello world" },
});

const results = await db.searchText("hello", 3);
console.log(results);

Notes

• JSON storage writes to a temporary file first, then renames it into place.
• All vectors in a database must have the same dimension.
• sqlite is reserved in the API but not implemented in this minimal build yet.

Development

npm install
npm run build