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';

Public API shape

The package root exposes both:

functional helpers for direct use in applications
class-based service entrypoints for clearer domain grouping in stateful integrations

`persona`

`PersonaService`

Class-based entrypoint for persona initialization.

`initializePersona(db, input)`

Creates and persists a new persona runtime profile.

initializePersona(db: IdentityDB, input: InitializePersonaInput): Promise<InitializedPersona>

Important input fields:

displayName: string
seedText?: string
personality?: string
history?: string
values?: string[]
likes?: string[]
dislikes?: string[]
relationships?: PersonaRelationshipInput[]
currentDate?: string
structuredModel: StructuredModelAdapter
imageModel?: ImageModelAdapter
generateProfileImage?: boolean
reuseExistingSpace?: boolean

seedText is the preferred initialization input shape: one long freeform string containing the persona's personality, history, values, preferences, and relationships when available.

`schedule`

`ScheduleService`

Class-based entrypoint for schedule generation, listing, and pruning.

`generateSchedule(db, input)`

Generates and persists schedule events, then derives schedule-backed availability entries.

generateSchedule(
  db: IdentityDB,
  input: GenerateScheduleInput,
): Promise<{ events: BoxBrainScheduleEvent[]; availabilityEntries: BoxBrainAvailabilityEntry[] }>

`listScheduleEvents(db, input)`

Lists persisted schedule events, excluding ones hidden by deletion markers.

listScheduleEvents(db: IdentityDB, input: ListScheduleEventsInput): Promise<BoxBrainScheduleEvent[]>

`pruneExpiredSchedule(db, input)`

Marks schedule events as deleted when they ended before referenceTime minus an optional grace window.

pruneExpiredSchedule(db: IdentityDB, input: PruneExpiredScheduleInput): Promise<SchedulePruneResult>

`pruneScheduleBefore(db, input)`

Marks schedule events as deleted when they start before a cutoff timestamp.

pruneScheduleBefore(db: IdentityDB, input: PruneScheduleBeforeInput): Promise<SchedulePruneResult>

`availability`

`AvailabilityService`

Class-based entrypoint for availability writes, listing, and snapshot queries.

`setAvailabilityStatus(db, input)`

Persists an explicit availability entry.

setAvailabilityStatus(db: IdentityDB, input: SetAvailabilityStatusInput): Promise<BoxBrainAvailabilityEntry>

`listAvailabilityEntries(db, input)`

Lists availability entries in chronological order.

listAvailabilityEntries(db: IdentityDB, input: ListAvailabilityEntriesInput): Promise<BoxBrainAvailabilityEntry[]>

`getAvailabilitySnapshot(db, input)`

Returns the active availability state at a timestamp plus the next transition.

getAvailabilitySnapshot(db: IdentityDB, input: GetAvailabilitySnapshotInput): Promise<BoxBrainAvailabilitySnapshot>

Important types:

type BoxBrainAvailabilityMode = 'online' | 'do_not_disturb' | 'offline';
type BoxBrainAvailabilitySourceType = 'default' | 'schedule' | 'manual' | 'tool';

`conversation`

`ConversationService`

Class-based entrypoint for inbound replies, proactive openings, and entry listing.

`replyToConversation(db, input)`

Persists an inbound message and generates a DM-style response turn. When input.memoryPipeline is provided, the turn can also classify durable inbound/outbound messages and persist extracted IdentityDB facts back into the persona space.

replyToConversation(db: IdentityDB, input: ReplyToConversationInput): Promise<ConversationTurnResult>

`startConversation(db, input)`

Generates a proactive outbound opening turn with no inbound user message. The same optional memoryPipeline can classify and extract durable proactive outbound memories.

startConversation(db: IdentityDB, input: StartConversationInput): Promise<ConversationTurnResult>

`listConversationEntries(db, input)`

Lists stored conversation entries for a persona, optionally filtered by counterpart and time range.

listConversationEntries(db: IdentityDB, input: ListConversationEntriesInput): Promise<BoxBrainConversationEntry[]>

Required model roles for turn generation:

mandatoryMemoryModel: StructuredModelAdapter
contextualMemoryModel: StructuredModelAdapter
responseModel: StructuredModelAdapter

Optional long-term memory pipeline:

memoryPipeline.classifierModel: StructuredModelAdapter
memoryPipeline.extractorModel: StructuredModelAdapter
memoryPipeline.source?: string

`memory`

`FactDraftMemoryStore`

Class-based entrypoint for persisting extracted fact drafts into IdentityDB.

`persistFactDrafts(db, input)`

Low-level helper for writing BoxBrain fact drafts into IdentityDB.

persistFactDrafts(db: IdentityDB, input: PersistFactDraftsInput): Promise<Fact[]>

`timing`

Constants

ONLINE_AVAILABILITY
DND_AVAILABILITY
OFFLINE_AVAILABILITY

`TimingProfile`

Class-based entrypoint for timing calculations.

`createTypingDelay(message, options?)`

Computes a per-message typing delay based on message length.

createTypingDelay(message: string, options?: TypingDelayOptions): number

Default per-character range:

minimum: 0.05 seconds
maximum: 0.08 seconds

`createReplyDelay(availability, options)`

Computes the initial reply delay for the first message in an exchange.

createReplyDelay(availability: BoxBrainAvailability, options: ReplyDelayOptions): number | null

Behavior summary:

offline -> null
not first reply in exchange -> 0
do_not_disturb -> probabilistic reply or null
online -> short randomized delay

`adapters`

`TextModelAdapter`

interface TextModelAdapter {
  provider: string;
  model: string;
  generateText(request: TextGenerationRequest): Promise<string>;
}

`StructuredModelAdapter`

interface StructuredModelAdapter<TSchema = unknown> {
  provider: string;
  model: string;
  generateObject<TOutput>(request: StructuredGenerationRequest<TSchema>): Promise<TOutput>;
}

`ImageModelAdapter`

interface ImageModelAdapter {
  provider: string;
  model: string;
  generateImage(request: ImageGenerationRequest): Promise<ImageGenerationResult>;
}

`SpecialDateProvider`

interface SpecialDateProvider {
  listSpecialDates(request: SpecialDateRequest): Promise<SpecialDateContext[]>;
}

`grok`

`GrokApiClient`

Class-based xAI runtime client used by the Grok adapter helpers.

`createGrokTextModelAdapter(options)`

Creates a TextModelAdapter that uses xAI chat completions.

`createGrokStructuredModelAdapter(options)`

Creates a StructuredModelAdapter that uses xAI chat completions with response_format configured as JSON object or JSON schema.

`createGrokImageModelAdapter(options)`

Creates an ImageModelAdapter that uses xAI image generation.

`createGrokAdapters(options)`

Convenience bundle creator.

createGrokAdapters(options: GrokAdapterBundleOptions): {
  text: TextModelAdapter;
  structured: StructuredModelAdapter;
  image: ImageModelAdapter;
}

`types`

Selected important domain types include:

type BoxBrainFactDomain =
  | 'persona.biography'
  | 'persona.profile_image'
  | 'persona.schedule'
  | 'persona.schedule.deleted'
  | 'persona.availability'
  | 'persona.conversation'
  | 'persona.relationship'
  | (string & {});

interface BoxBrainPersonaProfile {
  id: string;
  spaceName: string;
  displayName: string;
  profileImageUrl?: string;
}

interface BoxBrainConversationEntry {
  id: string;
  turnId: string;
  direction: 'inbound' | 'outbound';
  text: string;
  occurredAt: string;
  createdAt?: string;
  counterpartId: string;
  counterpartDisplayName?: string;
  proactive: boolean;
  metadata?: JsonValue | null;
}

API Reference

Public API shape

persona

PersonaService

initializePersona(db, input)

schedule

ScheduleService

generateSchedule(db, input)

listScheduleEvents(db, input)

pruneExpiredSchedule(db, input)

pruneScheduleBefore(db, input)

availability

AvailabilityService

setAvailabilityStatus(db, input)

listAvailabilityEntries(db, input)

getAvailabilitySnapshot(db, input)

conversation

ConversationService

replyToConversation(db, input)

startConversation(db, input)

listConversationEntries(db, input)

memory

FactDraftMemoryStore

persistFactDrafts(db, input)

timing