@kybernesis/brain-storage-sqlite

The default StorageProvider for Cortex — a better-sqlite3 implementation of the persistence seam. It backs the timeline, entity-graph, facts, and sleep subsystems, and bundles the vector store (lazy-loaded from @kybernesis/brain-storage-vec).

Used with @kybernesis/brain-core. It implements the StorageProvider interface from @kybernesis/brain-contracts; you inject it, the kernel calls it.

Install

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

better-sqlite3 (>= 9) is a peer dependency — the host provides it. Add @kybernesis/brain-storage-vec too if you index vectors.

Usage

import { createSqliteStorageProvider } from '@kybernesis/brain-storage-sqlite';
import { setStorageProvider } from '@kybernesis/brain-core';

setStorageProvider(createSqliteStorageProvider());
// brain-core now persists every subsystem to per-tenant SQLite files.

Each TenantContext maps to its own set of SQLite files (timeline, entity-graph, vectors, sleep) under the tenant's paths. Connections are pooled per slug:kind and opened lazily with WAL + synchronous = NORMAL + foreign_keys = ON.

The vector store is lazy

The StorageProvider bundle includes a VectorRepository, but the sqlite-vec native binary lives in @kybernesis/brain-storage-vec. It is imported only on first vector use. If it can't load (missing binary, unsupported platform), vector operations degrade to safe no-ops instead of throwing — and brain-core maps those to its graceful results.

Lifecycle helpers

import { closeWorkspace, closeAll } from '@kybernesis/brain-storage-sqlite';

closeWorkspace(tenant.slug);  // close one tenant's connections
closeAll();                    // close everything (tests, shutdown)

Notes

• ESM-only, TypeScript strict. Native module — see better-sqlite3 for platform/build notes.
• Conformance is proven against @kybernesis/brain-testkit's storage cases.
• Part of Cortex — @kybernesis/brain-*.