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
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.

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