p-sw/BoxBrain
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6eb6024e5114381d5c121275f8661c75dbf6466f
BoxBrain/README.md

2.2 KiB
Raw Blame History

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

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.

Because BoxBrain currently consumes IdentityDB through the sibling file:../IdentityDB dependency during active development, the release workflow clones and builds IdentityDB first, then runs BoxBrain install/test/build/publish steps against that prepared sibling checkout.

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