@kybernesis/brain-contracts

The seam definitions for the Cortex brain library: Zod schemas, provider interfaces, and shared constants. Everything else in the family depends on this package; it depends on nothing else.

This is the package to read if you want to implement your own provider — the interfaces here are the contract your implementation must satisfy.

Install

pnpm add @kybernesis/brain-contracts

What's in it

• Provider interfaces — StorageProvider (and its repositories: timeline, entity-graph, fact, sleep, vector), plus the shapes the kernel injects. The seams a backend must satisfy.
• BrainProvider — the Layer-2, consumer-facing facade interface (ADR-0016): bound-tenant, all-async, coarse-grained brain operations (remember / addNote / query / timeline / entity ops / graph / listEntities / stats / sleep). Implemented locally by createLocalBrainProvider in brain-core; the seam a future remote cloud provider also satisfies. Exported from the package root.
• Zod schemas + types — TimelineEvent, Entity, Fact, sleep types, etc. Canonical field shapes (snake_case to match the wire format), with a guard test enforcing it.
• TenantContext + pathsFor — the per-brain context describing where its SQLite files live. Build one per agent/workspace.
• Constants — EMBEDDING_MODEL (text-embedding-3-small), EMBEDDING_DIM (1536), EMBEDDING_INPUT_CAP (8192), CLAUDE_MODEL_ALIASES.

Subpath exports

Import the whole surface from the root, or cherry-pick for tree-shaking:

import { pathsFor, type TenantContext } from '@kybernesis/brain-contracts';
import { EMBEDDING_DIM } from '@kybernesis/brain-contracts/constants';

Available subpaths: ./tenant, ./constants, ./timeline, ./entity, ./fact, ./sleep, ./logger.

Notes

• ESM-only, TypeScript strict. No runtime dependencies beyond zod.
• Implementing a provider against these interfaces? Validate it with @kybernesis/brain-testkit's runParityHarness / conformance cases.
• Part of Cortex — @kybernesis/brain-*.