@kybernesis/brain-storage-vec

The VectorRepository for Cortex — a sqlite-vec implementation of the vector store. It holds the embeddings that power semantic recall.

Used with @kybernesis/brain-core, via @kybernesis/brain-storage-sqlite. The SQLite storage provider lazy-loads this package for its vector store — you don't usually import it directly, you just install it alongside the SQLite provider.

Install

pnpm add @kybernesis/brain-storage-vec @kybernesis/brain-storage-sqlite @kybernesis/brain-core

Peer dependencies (host-provided): better-sqlite3 (>= 9) and sqlite-vec (>= 0.1). This package carries the native sqlite-vec binary, which is why it's split out from the SQLite provider and loaded lazily.

How it fits

You typically never call this directly — wiring the SQLite provider is enough:

import { createSqliteStorageProvider } from '@kybernesis/brain-storage-sqlite';
import { setStorageProvider, indexChunk, semanticSearch } from '@kybernesis/brain-core';
import { createOpenAIEmbedder } from '@kybernesis/brain-embed-openai';
import { setEmbeddingProvider } from '@kybernesis/brain-core';

setStorageProvider(createSqliteStorageProvider());  // lazy-loads brain-storage-vec
setEmbeddingProvider(createOpenAIEmbedder());

await indexChunk(tenant, 'apples are red', { ts: '2026-06-06T09:00:00Z', origin_id: 'a' });
await semanticSearch(tenant, 'fruit colour');

Direct API (advanced)

For tooling or custom providers, the low-level handle is exported:

import { getVectorDb, vectorCount, toFloat32Buffer, closeAllVectorDbs } from '@kybernesis/brain-storage-vec';

The schema (matching KAD's vectors.db): a single chunks vec0 virtual table (embedding float[1536]) plus a chunk_meta table for the searchable fields.

Constraint: 1536 dimensions

The schema is fixed at EMBEDDING_DIM = 1536 (text-embedding-3-small). A different embedding model must emit 1536-dim vectors, or EMBEDDING_DIM and the schema move together and you re-index. Don't mix models within one populated vectors.db — distances across models aren't comparable.

Notes

• ESM-only, TypeScript strict. Native module — needs the sqlite-vec binary for your platform.
• Search is brute-force vec_distance_l2 (port-faithful to KAD) — fine at brain scale.
• Part of Cortex — @kybernesis/brain-*.