Table of Contents
- Purpose and Architecture
- Existence and design intent
- Core principles
- 1. Framework-first, not app-first
- 2. IdentityDB space = one persona
- 3. Structured generation before persistence
- 4. A persona should have a life outside the chat
- Runtime architecture
- 1. Persona initialization
- 2. Schedule runtime
- 3. Availability runtime
- 4. Conversation runtime
- Stage A: availability check
- Stage B: mandatory memory retrieval
- Stage C: contextual memory retrieval
- Stage D: turn planning
- Stage E: human-like timing
- Stage F: persistence
- 5. Adapter boundary
- Conversation realism rules encoded in the runtime
- What BoxBrain is not
Purpose and Architecture
Existence and design intent
BoxBrain exists to answer a specific question:
What does an LLM runtime need in order to feel less like a chatbot and more like an actual person in a DM thread?
Its answer is: memory alone is not enough.
A believable persona also needs:
- a persistent personal history
- preferences and values that survive across turns
- relationships with named people
- a time-aware schedule
- changing availability
- conversation-specific memory retrieval
- message timing that feels human
This is why BoxBrain is not just a prompt template or a single conversation function. It is a small framework that coordinates multiple model calls and stores their outcomes in IdentityDB.
Core principles
1. Framework-first, not app-first
BoxBrain intentionally stops at the runtime/library layer.
It gives you primitives for:
- persona initialization
- schedule generation
- availability control
- conversation orchestration
- provider adapters
It does not currently ship with its own HTTP server, frontend, or transport product.
2. IdentityDB space = one persona
Each persona is isolated into its own IdentityDB space.
That means:
- biography facts belong to one persona space
- schedule facts belong to that same persona space
- availability facts belong to that same persona space
- conversation history belongs to that same persona space
This is the main boundary that prevents one persona's memories from bleeding into another persona.
3. Structured generation before persistence
BoxBrain does not trust raw free-form LLM output for important state transitions.
It prefers:
- structured biography generation
- structured fact extraction
- structured schedule generation
- structured memory selection
- structured conversation turn planning
This makes the runtime more deterministic, testable, and safer to persist into IdentityDB.
4. A persona should have a life outside the chat
A BoxBrain persona is not assumed to be available all the time.
Instead:
- schedules create time-bound events
- schedule events can create availability windows
- manual or tool-driven overrides can supersede schedule-derived states
- conversations can be blocked or delayed depending on availability
This is the mechanism that makes a persona feel like it has its own life rhythm.
Runtime architecture
1. Persona initialization
Initialization takes a long freeform seed string from the caller.
That single string can contain things like:
- personality
- history
- values
- likes / dislikes
- relationships
displayName still exists as a stable explicit field for runtime identity and space naming, and optional structured hints can still be provided as supplements when useful.
Then BoxBrain:
- asks a structured model to interpret the freeform seed and generate a detailed biography
- asks a structured model to split that biography into IdentityDB-ready facts
- persists those facts into the persona's IdentityDB space
- optionally generates a profile image through an image adapter
The result is a persona profile with a stable id, spaceName, displayName, biography, and optional profile image URL.
2. Schedule runtime
Schedules are generated for a day, week, or month scope.
The schedule generator combines:
- existing persona facts
- recent schedule continuity
- optional external special-date context
- the anchor date and optional timezone
Generated events are stored as persona.schedule facts.
Each event includes:
- title
- optional description
startAtendAtavailabilityMode- optional
availabilityReason kind(routineorspecial)- topics / metadata
Schedule pruning does not mutate old facts directly. Instead, BoxBrain writes persona.schedule.deleted marker facts so the runtime can treat old events as deleted while keeping an append-only fact history.
3. Availability runtime
Availability facts represent whether the persona is:
onlinedo_not_disturboffline
Availability can come from different sources:
schedulemanualtooldefault
default is implicit and resolves to online when no explicit entry applies.
A snapshot query returns:
- the current active availability state at a timestamp
- the next availability transition, if one exists
This gives upstream applications enough information to render presence and decide whether to send or defer a conversation turn.
4. Conversation runtime
A BoxBrain conversation turn is intentionally multi-stage.
Stage A: availability check
Before generating a response, BoxBrain checks the persona's current availability snapshot.
If the persona is offline, the turn is blocked.
Stage B: mandatory memory retrieval
A structured retrieval model chooses memories that must always be considered, especially:
- yesterday / today / tomorrow schedule context
- recent conversation context
- stable persona or counterpart facts
Stage C: contextual memory retrieval
A second structured retrieval model chooses additional relevant memories based on the specific user message or proactive context.
Stage D: turn planning
A response model generates a structured turn plan:
mode: 'reply' | 'refuse'messages: string[]- optional
toolCalls
Stage E: human-like timing
BoxBrain calculates:
- first-reply delay based on availability mode and whether this is the first reply in the active exchange
- typing delay per message based on message length
Stage F: persistence
Inbound and outbound messages are stored as persona.conversation facts.
5. Adapter boundary
BoxBrain separates provider-specific API mechanics from runtime logic.
The framework itself expects abstract adapters for:
- plain text generation
- structured-object generation
- image generation
- special-date retrieval
That means the persona runtime can stay largely unchanged while different model providers are swapped underneath.
Conversation realism rules encoded in the runtime
The current runtime already supports several behaviors that matter for realism:
- first replies can be delayed
- follow-up messages in the same exchange can skip that initial reply delay
- typing time depends on message length
do_not_disturbcan probabilistically fail to reply at allofflineblocks the turn entirely- a refusal plan can still emit a short farewell sequence and trigger a tool-driven availability change
What BoxBrain is not
BoxBrain is not currently:
- a SaaS product
- an HTTP API server
- a complete social simulation world model
- a universal provider SDK
- a frontend chat application
It is the runtime foundation you would build those things on top of.