BoxBrain

BoxBrain is an IdentityDB-backed TypeScript framework for creating synthetic personas that behave like human-like DM contacts.

The project is framework-first rather than product-first. The current core library provides:

provider-agnostic text, structured-output, image, conversation-memory, and special-date adapter contracts
ready-made xAI Grok text, structured-output, and image adapters
one IdentityDB memory space per persona
persona initialization from a long freeform persona seed string, with optional supplemental structured hints
LLM-generated biography ingestion into IdentityDB fact drafts
optional profile image generation through an image adapter
schedule generation for day/week/month scopes with optional external special-date context
schedule persistence, listing, and pruning APIs
availability state persistence with schedule/manual/tool overrides
availability snapshots with current + next transition calculation
DM-style conversation orchestration for inbound replies and proactive openings
delegated mandatory/contextual memory retrieval pipelines for conversation turns
optional two-stage conversation memory extraction pipeline for durable inbound/outbound memories
human-like first-reply delay and typing delay utilities
farewell-style refusal flows that can trigger availability-changing tool calls

Still planned:

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

Development

bun install
bun run test
bun run check
bun run build

Source layout

The library is now grouped by domain under src/:

src/core/ — shared adapter, type, and IdentityDB helper contracts
src/persona/ — persona initialization service
src/schedule/ — schedule generation and pruning service
src/availability/ — availability state service
src/conversation/ — DM turn orchestration service
src/memory/ — fact-draft persistence service
src/timing/ — typing/reply timing profile helpers
src/providers/grok/ — Grok API client and adapter bundle

Each domain now exposes a class-based service API in addition to the existing functional helpers so consumers can organize stateful integrations more cleanly.

Conversation memory pipeline

Conversation turns can now optionally run a two-stage durable-memory pipeline:

a classifierModel decides whether each inbound or first-pass outbound message is worth remembering
an extractorModel converts only approved messages into IdentityDB-ready fact drafts
extracted facts are stored back into the persona space with conversation-turn trace metadata

The optional memoryPipeline input is available on both replyToConversation(...) and startConversation(...), so app integrations can enable long-term relationship memory without changing their storage layer.

Release

Tagging vX.Y.Z or X.Y.Z triggers the Gitea npm release workflow under .gitea/workflows/npm-release.yml.

BoxBrain now consumes the published identitydb package from npm at version 0.2.0, and trustedDependencies keeps Bun lifecycle scripts enabled for better-sqlite3 and esbuild during clean installs.

Current status

The repository now contains the framework core for persona initialization, schedule/status management, conversation orchestration, and a ready-made Grok adapter set. See the implementation plan:

docs/plans/2026-05-11-boxbrain-foundation.md

3.5 KiB Raw Blame History