BoxBrain Wiki

BoxBrain is a TypeScript framework for building LLM harnesses that make an AI-driven persona feel less like a generic assistant and more like a specific, continuing person.

The framework is intentionally not a messenger bot, UI, or one-provider chatbot product. It supplies the core runtime primitives a host application needs:

isolated persona spaces backed by IdentityDB-compatible memory stores
persona initialization from a freeform seed message
realistic schedule entries and schedule-derived availability
reply and proactive conversation entry points
sleep-time memory extraction into durable facts
debug hooks for observing the framework flow and persona reasoning pipeline

Source of truth: this wiki is written against the framework source tree (src/types.ts, src/memory.ts, src/schedule.ts, src/conversation.ts, src/persona.ts, src/index.ts) at repository commit 49f75af.

Why BoxBrain exists

Most LLM chat integrations feel artificial because every response is generated in isolation: the model is always available, always has the same tone, and often pretends to remember things it has not actually loaded.

BoxBrain exists to design the harness around the illusion of an ongoing person:

A persona has a private memory space. Each persona is initialized into an isolated IdentityDB-style space. Facts about the persona, the user, their relationship, schedules, and durable memories live there.
A persona has time. Schedules and availability make the persona online, busy, or offline depending on what they are supposed to be doing.
A persona can speak first. startConversation supports proactive messages instead of only reactive replies.
A persona forgets unless memory is explicitly retrieved. Mandatory memory retrieval tells the response model what was actually found; if nothing is found, the context explicitly says 기억이 없음.
The host app controls delivery realism. BoxBrain returns outgoing message drafts. The application should add typing indicators, status updates, delays, and delivery policy.

Framework surface

BoxBrain is a framework by design. It provides reusable primitives that a host application composes into a human-like persona experience.

Core primitives:

Persona constructor overloads for creating/loading a persona space
InMemoryMemoryStore
IdentityDbMemoryStore
createSqliteIdentityMemoryStore(filename)
deterministic daily/monthly schedule helpers
schedule-derived availability snapshots
mandatory conversation context assembly
sendMessage, startConversation, and stale-draft rewrite checks
sleepMemory extraction pipeline
debug events

Framework boundaries and default behaviors:

Schedule generation is a deterministic default helper. The framework exposes schedule entries and memory-store contracts so applications can layer their own planning policy around them.
BoxBrain does not send messages itself by design. It returns OutgoingMessageDraft.messages; the host messenger integration owns delivery.
Typing indicators, typing delays, presence display, and notification policy belong to the host app. BoxBrain supplies the draft messages and availability snapshot those policies need.
The IdentityDB-backed store uses IdentityDB facts as its persistence layer. Schedule entries are stored in fact metadata. Because the public IdentityDB API is append-oriented, schedule pruning is represented as a deletion fact at the Persona layer; the in-memory store physically prunes entries.

Reading order

Minimal example

import { Persona, createSqliteIdentityMemoryStore } from 'boxbrain';

const memory = await createSqliteIdentityMemoryStore('.data/mina.sqlite');

const persona = new Persona(
  'Mina',
  'Mina is a careful student who likes quiet cafes and is preparing for exams.',
  {
    memory,
    models: {
      conversation: yourConversationModel,
      memoryExtraction: yourMemoryExtractionModel,
    },
    debug: (event) => console.log(event.name, event.data),
  },
);

const space = await persona.ready();
await persona.createDailySchedule(new Date(), 'Keep a normal study day.');

const availability = await persona.getTodayScheduledAvailability(new Date());
const reply = await persona.sendMessage({
  datetime: new Date(),
  messageHistory: [
    { sender: 'user', time: new Date(), content: 'What are you doing?' },
  ],
});