@zukhruf/embeddings weekly downloads statistics

@zukhruf/embeddings

A program that compares texts by meaning needs a vector for each text, and the model call that makes the vector is slow. This package keeps the vectors of documents in a SQLite database. An upsert calls the model only for new or changed text. A search gives the nearest documents of a document, by exact cosine similarity, from the documents published near it. A query gives the similarity of a vector of another text, for example a search sentence, to each document, or to each document of a date range. This kind of package is also known as a vector store.

The words in these documents have one meaning each. See the glossary in CONTEXT.md.

Use it

This project is an experiment. It uses node:sqlite and an embedding model of the AI SDK. The package does not start a model or a server. Give it a model that is ready.

npm install @zukhruf/embeddings ai

import { DatabaseSync } from 'node:sqlite';

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { embed } from 'ai';

import { Collection } from '@zukhruf/embeddings';

const local = createOpenAICompatible({
  name: 'llama.cpp',
  baseURL: 'http://127.0.0.1:8080/v1',
});
using database = new DatabaseSync('embeddings.sqlite');
const collection = new Collection({
  database,
  model: local.embeddingModel('embeddinggemma'),
});

await collection.upsert([
  {
    id: 'a',
    text: 'Storm closes the port',
    publishedAt: new Date('2026-10-20'),
  },
  {
    id: 'b',
    text: 'Port shut as storm hits',
    publishedAt: new Date('2026-10-21'),
  },
  { id: 'c', text: 'Port opens again', publishedAt: new Date('2026-11-30') },
]);

collection.nearest('a', { k: 10, withinDays: 7 }); // [{ id: 'b', similarity: … }]
collection.similarity('a', 'c');

// Compare a text that is not a document with the documents of October.
const { embedding } = await embed({
  model: local.embeddingModel('embeddinggemma'),
  value: 'task: search result | query: ports closed by weather',
});
collection.query(embedding, {
  from: new Date('2026-10-01'),
  to: new Date('2026-10-31'),
}); // [{ id: 'a', similarity: … }, { id: 'b', similarity: … }]

collection.fetch(['a']); // Map { 'a' => Float32Array [ … ] }
collection.delete(['c']);
collection.count(); // 2

Search a vector table of your own

Another program can write the vectors into its own table. A VectorSearch searches that table with the same rules as a collection. The table or view must have the columns id (text) and vector. Each vector must be a unit vector, as a BLOB of float32 values in the byte order of the platform (ADR 0005). Each call except a query without a date range also reads the column published_at (milliseconds since the Unix epoch). Thus a table of documents with no publish date supports a query without a date range (ADR 0007).

import { DatabaseSync } from 'node:sqlite';

import { VectorSearch } from '@zukhruf/embeddings';

using database = new DatabaseSync('listings.sqlite');
const search = new VectorSearch({ database, table: 'listing_vectors' });

search.nearest('listing-42', { k: 10, withinDays: 30 });

To search a table with other column names, make a view that renames the columns, and give the name of the view.

API

• new Collection({ database, model }). The caller opens and closes database. The collection makes its table embedding_document in it. model is an AI SDK embedding model object.
• upsert(documents) stores each document. It calls the model, through embedMany, only for a document whose text or model changed. It stores the new publish date of each document.
• nearest(id, { k, withinDays }) gives at most k neighbours of the document, with the highest similarity first. A neighbour has a publish date at most withinDays days before or after the publish date of the document. Equal similarities sort by id.
• neighbourGraph({ from, to, k, withinDays }) gives an iterator of [id, neighbours] entries, one for each document published from from to to, in the order of the publish dates and then of the ids. The neighbours of each entry are equal to the result of nearest(id, { k, withinDays }). A document outside the range has no entry, but it can be a neighbour of a document in the range. The call reads and decodes each vector one time (ADR 0004). Use it when you need the neighbours of many documents.
• similarity(a, b) gives the cosine similarity of two stored documents.
• query(vector, range?) gives the similarity of a vector of the caller to each document, as { id, similarity } entries. With a date range { from, to }, it gives only the documents published from from to to. The highest similarity is first, and equal similarities sort by id. The call makes the vector a unit vector first. The vector must come from the model of the stored vectors (ADR 0006, ADR 0007).
• fetch(ids) gives a Map from each id to a copy of its stored unit vector, as a Float32Array, in the order of the ids.
• delete(ids) removes the documents. An id that the collection does not store is not an error, so you can delete the same ids again.
• count() gives the number of stored documents.
• new VectorSearch({ database, table }). The caller opens and closes database. table is the name of a table or a view in it, with the columns id and vector, and published_at for each call except a query without a date range. The vector search only reads it. Each call reads the table again, so the table can change between two calls.
• VectorSearch gives nearest, neighbourGraph,…