@kybernesis/brain-core

The kernel of the Cortex brain library — timeline, entity-graph, facts, vectors, retrieval, and sleep. This is the package you call; the others are the swappable backends it runs on.

brain-core is programmed against the interfaces in @kybernesis/brain-contracts and has no built-in backend. Wire the provider seams once at startup, then call the kernel methods.

Install

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

Usage

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

setStorageProvider(createSqliteStorageProvider());  // required — persistence
setEmbeddingProvider(createOpenAIEmbedder());        // optional — semantic recall

await addConversationToTimeline(tenant, 'c-1', 'chat.md',
  '2026-06-06T09:00:00Z', undefined, 'Q3 roadmap', /* …turns… */);

await hybridSearch(tenant, 'what did we decide about Q3?');
await getEntityContext(tenant, 'Ada');

Prefer one object per brain? Wrap a tenant once with createLocalBrainProvider — a bound-tenant facade over the same operations, so you don't thread tenant through every call:

import { createLocalBrainProvider } from '@kybernesis/brain-core';

const brain = createLocalBrainProvider(tenant);
await brain.remember({ prompt, response, channel: 'chat' });
await brain.query('what did we decide about Q3?');
await brain.graph();
await brain.stats();

The three seams

The kernel is wired through three module-level setters. Each degrades gracefully when unset.

| Seam | Setter | Provider | Powers | |---|---|---|---| | Storage | setStorageProvider() | brain-storage-sqlite | All persistence (required) | | Embedding | setEmbeddingProvider() | brain-embed-openai | Vector indexing + semantic recall | | LLM | setLLMProvider() | brain-llm-claude | Extraction, contradiction detection, profiles, sleep reasoning |

→ See Architecture — the provider seams.

What it exposes

A flat set of async functions over a TenantContext, grouped by subsystem:

• Timeline — addToTimeline, addConversationToTimeline, queryTimeline, searchTimeline, getRecentActivity, …
• Entity graph — findOrCreateEntity, linkEntities, getEntityContext, mergeEntities, getTypedRelationships, …
• Facts — storeFact, retractFact, reinforceFact, searchFactsFts, factFirstSearch, …
• Vectors — indexChunk, semanticSearch, vectorStats (need the embedding seam).
• Retrieval — hybridSearch, factFirstSearch, formatRecall.
• Sleep — runSleepCycleNow, recoverStaleSleepRuns (background consolidation/reasoning).
• BrainProvider facade — createLocalBrainProvider(t) returns a bound-tenant BrainProvider (Layer-2, ADR-0016): the same operations as one async object, with no TenantContext threaded per call. The high-level seam a future remote provider also implements.

All schemas, field shapes, and constants come from @kybernesis/brain-contracts.

Notes

• ESM-only, TypeScript strict. TenantContext describes where one brain's files live — build it with pathsFor(slug, homeDir) from brain-contracts.
• brain-storage-vec is a peer dependency: the SQLite provider lazy-loads it for the vector store, so install it alongside if you index vectors.
• Part of Cortex — @kybernesis/brain-*.