@monlite/vector

🌙 @monlite/vector

Local vector / semantic search for @monlite/core, powered by sqlite-vec. Adds collection.findSimilar() — RAG and AI-agent memory, all in your local .db.

A monlite plugin. Store documents with an embedding field, and search by nearest neighbour. The index is maintained automatically on every write (including changes applied by @monlite/sync).

import { createDb } from "@monlite/core";
import { vector } from "@monlite/vector";

const db = createDb("./app.db", {
  allowExtensions: true, // required: loads the sqlite-vec extension
  plugins: [vector({ docs: { field: "embedding", dimensions: 384 } })],
});

await db.collection("docs").create({
  data: { title: "Black holes", embedding: await embed("Black holes …") },
});

const hits = await db.collection("docs").findSimilar({
  vector: await embed("astrophysics"),
  topK: 5,
  where: { published: true }, // optional structured filter
});
// [ { _id, title, embedding, _distance, … } ]  — nearest first

You bring the embeddings (from any model — OpenAI, local, etc.); monlite stores and searches them.

Install

npm install @monlite/core @monlite/vector

@monlite/vector depends on sqlite-vec, which ships prebuilt native binaries. It works on both monlite backends (better-sqlite3 and node:sqlite), but the database must be opened with { allowExtensions: true }.

API

vector(spec: Record<string, {
  field: string;              // document field holding the embedding (number[])
  dimensions: number;         // must match your model
  distance?: "l2" | "cosine"; // default "l2"
}>): MonlitePlugin

collection.findSimilar({
  vector: number[],         // query embedding (length === dimensions)
  topK?: number,            // default 10
  where?: WhereInput<T>,    // also constrain with a normal monlite filter
}): Promise<Array<WithId<T> & { _distance: number }>>

Results are ordered nearest-first; _distance is the raw metric (smaller = closer). Documents without a valid embedding are simply not indexed.

import { reindex } from "@monlite/vector";
reindex(db, "docs", { field: "embedding", dimensions: 384 }); // rebuild

How it works

For each configured collection the plugin creates a sqlite-vec vec0 virtual table keyed by the document _id, indexes on init (backfilling existing documents), and keeps it current via the plugin afterWrite hook. findSimilar runs a KNN query, then returns the live documents in distance order.

Hybrid search

For the best retrieval quality, combine keyword (FTS) and semantic (vector) results. hybridSearch runs both and fuses the rankings with Reciprocal Rank Fusion — no score normalization needed.

import { createDb } from "@monlite/core";
import { fts } from "@monlite/fts";
import { vector, hybridSearch } from "@monlite/vector";

const db = createDb("./app.db", {
  allowExtensions: true,
  plugins: [
    fts({ docs: ["title", "body"] }),
    vector({ docs: { field: "embedding", dimensions: 384 } }),
  ],
});

const hits = await hybridSearch(db.collection("docs"), {
  text: "black holes",          // keyword arm (FTS)
  vector: await embed("black holes"), // semantic arm (vector)
  topK: 10,
  where: { published: true },   // optional, applied to both arms
});
// [ { _id, title, …, _rrf } ]  — fused, best first

If @monlite/fts isn't configured on the collection, it falls back to vector-only.

License

MIT 🌙