vector-cache-lite

Lightweight in-memory vector similarity cache — brute-force cosine-similarity nearest-neighbor search over a small set of vectors, for prototypes, tests, or datasets small enough that a full vector database is overkill.

Install

npm install vector-cache-lite

Quick start

import { VectorCache } from 'vector-cache-lite';

const cache = new VectorCache<{ text: string }>();
cache.upsert({ id: 'chunk-1', vector: embedding1, metadata: { text: chunk1Text } });
cache.upsert({ id: 'chunk-2', vector: embedding2, metadata: { text: chunk2Text } });

const results = cache.search(queryEmbedding, 3); // top 3, sorted by cosine similarity

Why brute-force instead of an ANN index

Approximate nearest-neighbor structures (HNSW, IVF) pay off once you're past a few thousand to tens of thousands of vectors — below that, brute-force cosine similarity is fast enough (and exact, not approximate) without the build complexity of an index. vector-cache-lite is meant for local dev, tests, small RAG demos, or a per-request scratch cache, not for replacing a real vector database at scale.

API

• cosineSimilarity(a, b) — standalone similarity function
• new VectorCache<Metadata>()
• .upsert(entry) — { id, vector, metadata? }
• .search(query, topK?) — returns entries sorted by descending similarity, each with a .score
• .get(id) / .delete(id) / .size() / .clear()

License

MIT