74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
1. a `classifierModel` decides whether each inbound or first-pass outbound message is worth remembering
|
|
2. an `extractorModel` converts only approved messages into IdentityDB-ready fact drafts
|
|
3. 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`
|