Source Layout

BoxBrain's implementation is intentionally compact because the project is a framework core, not a full chatbot product.

Root files

Path	Purpose
`README.md`	High-level project overview and quick API examples
`package.json`	Package metadata, Bun scripts, runtime dependencies
`tsconfig.json`	TypeScript configuration
`bun.lock`	Bun lockfile
`.gitea/workflows/ci.yml`	Gitea CI workflow

Path	Purpose
`src/index.ts`	Root barrel export for public APIs
`src/types.ts`	Public TypeScript contracts: memory, schedules, models, messages, debug events
`src/memory.ts`	`InMemoryMemoryStore`, `IdentityDbMemoryStore`, SQLite helper
`src/schedule.ts`	Datetime helpers, deterministic schedule generation, availability derivation
`src/conversation.ts`	Message-history formatting, prompts/instructions, mandatory context assembly
`src/persona.ts`	Main `Persona` class and orchestration pipeline

Path	Covered behavior
`tests/persona.test.ts`	persona creation/loading, initialization facts, debug events
`tests/schedule.test.ts`	daily schedule generation, availability, pruning
`tests/conversation.test.ts`	mandatory context, missing memory marker, stale rewrite, proactive opener
`tests/sleep-memory.test.ts`	objectivized memory extraction and persistence
`tests/memory.test.ts`	fact listing for in-memory and SQLite IdentityDB stores

src/index.ts exports everything from:

export * from './types';
export * from './memory';
export * from './schedule';
export * from './conversation';
export * from './persona';

This means consumers can import framework types and helper functions from boxbrain directly.

src/persona.ts provides constructor overloads:

new Persona(displayName, seedMessage, options)
new Persona(spaceId, options)

Create mode stores a new memory space. Load mode retrieves an existing space. ready() awaits the initialization promise.

src/memory.ts has two concrete stores:

Schedule entries in the IdentityDB store are saved as facts with metadata.scheduleEntry.

src/schedule.ts provides a deterministic default routine:

src/conversation.ts centralizes mandatory context:

src/persona.ts ties the pieces together:

From the repository root:

bun install
bun run test
bun run check
bun run build