BoxBrain

BoxBrain is an IdentityDB-backed TypeScript framework for building synthetic personas that feel like real DM contacts.

It is not a finished chatbot product. It is a framework-first runtime library for composing persona memory, schedules, availability, and multi-step LLM orchestration into believable messaging behavior.

What BoxBrain currently provides

provider-agnostic adapter contracts for text, structured-output, image, and special-date retrieval
a ready-made xAI Grok adapter set
one IdentityDB space per persona as the main isolation boundary
persona initialization from a long freeform seed string, with optional supplemental structured hints
biography generation and fact extraction into IdentityDB
optional profile image generation during persona initialization
schedule generation for day, week, and month scopes
schedule persistence, listing, and pruning
availability persistence with schedule/manual/tool overrides
availability snapshots with current and next-transition resolution
DM-style conversation orchestration for inbound replies and proactive openings
optional two-stage memory extraction for durable inbound/outbound conversation facts
human-like first-reply and typing delay helpers

What is still planned

These are not implemented as part of the core library yet:

HTTP/RPC wrappers around the runtime APIs
additional ready-made provider adapter packages beyond Grok
production-focused runtime integrations beyond the in-process core library

Current project status

package/runtime: Bun
language: TypeScript
tests: Vitest
build: tsup
persistence dependency: published identitydb@0.2.0 from npm
release automation: tag-triggered Gitea Actions workflow for npm publishing

Mental model

A BoxBrain persona works like this:

Initialize a persona from a long freeform seed string.
Generate a detailed biography.
Extract biography facts and store them in the persona's IdentityDB space.
Generate schedules anchored to time and optional special-date context.
Derive availability from schedule or explicit overrides.
Run conversations by retrieving memories, planning a turn, and emitting DM-style messages with delays.

Public surface at a glance

The package root currently re-exports:

export * from './core/adapters';
export * from './core/types';
export * from './availability';
export * from './conversation';
export * from './memory';
export * from './persona';
export * from './providers/grok';
export * from './schedule';
export * from './timing';

That means consumers can use both:

functional helpers like initializePersona, generateSchedule, and replyToConversation
class-based entrypoints like PersonaService, ScheduleService, AvailabilityService, ConversationService, FactDraftMemoryStore, TimingProfile, and GrokApiClient

See Getting Started for local setup and API Reference for the current exported runtime surface.