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

```bash
bun install
bun run test
bun run check
bun run build
```

## Release

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

BoxBrain now fetches IdentityDB as a remote git dependency through Bun instead of relying on a sibling local checkout, and `trustedDependencies` allows Bun to run the required lifecycle scripts for `identitydb`, `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`