Open sourceMIT2935 tests
A modular AI persona engine. One always-on consciousness across Discord, Telegram, Twitch and a vanilla Minecraft server — the same mind in all of them, not a bot per platform.
How it works
Most projects in this space are a question and an answer with an avatar on top. This is the part that is different, so it is the part worth watching.
Everything arrives on one bus.
A Twitch message, your voice in a Discord call, a death in Minecraft, a donation webhook, a note you typed into the dashboard. Every sense wraps what it saw as the same kind of object and pushes it onto a single PerceptionBus. Nothing gets a private channel to her.
src/core/perception/
Every perception gets a priority, none gets dropped.
Annotate, never filter: being addressed by name or answering something she said scores 1.0 unconditionally, past cooldowns and quiet hours, and the whole batch reaches the mind ordered in one frame. Nothing is throttled by dice, parked in a digest, or dropped.
src/core/attention/
One consciousness reasons and acts through tools.
Not one bot per platform: one always-on loop reasoning over one sliding, token-budgeted window — a Telegram DM and a Minecraft death in the same frame. She answers each where it arrived through send_message, or out loud with speak. A line typed while she is still mid-turn goes in at her next step, and an action that takes time runs beside her while she keeps talking.
src/core/mind/
Everything she does leaves through one sink.
speak, send_message, mc_chat, find_block, objective_done. What she says funnels through a single expression layer on the way out: a line is spoken the moment its closing quote arrives, her face and mouth follow the audio, and it all goes down into bea.db on the way to being remembered. One place to look when you want to know what she actually did.
src/core/expression/
Where she lives
Each of these is a Skill: a plugin that can perceive, expose tools, contribute prompt rules and own its own infrastructure. Every one can be switched on or off at runtime from the dashboard — and she can never arm one herself.
Voice calls and text channels. Owns a small Node.js bot for the audio pipeline; she hears you and answers out loud.
Private chats and groups, polled in-process. Every chat lands in the same window, tagged with where it came from — she answers each where it arrived.
Chat read anonymously — no token needed. Volume becomes texture rather than thoughts, and being named still gets through.
A player on a vanilla server. The game’s tools are her own hands: she chops, crafts, builds and fights, reads game chat, and remembers the players she meets there.
Search and read a page, only while you allow it. A slow site never holds her turn: the answer reaches her on its own, in the conversation that asked.
React and FastAPI: a bento overview, the live context window, her memory, today’s plan, and every setting. ⌘K from anywhere.
The Minecraft skill
No second agent, no body taking orders in words. The game is one more place she lives, like the call or the chat: its tools are her hands, the mod handles the reflexes, and she keeps talking while her hands are busy.
The game’s tools are hers, called by the same mind that answers on Discord. 27 take time and run beside her: find_block("log", 16) walks, chops and picks up on its own. The other 10 — a scan, a crafting plan, a line in game chat — answer at once.
Eating, fighting back, fleeing, landing a fall in water, respawning: the mod does them without asking and tells her after. A fight or a death wakes her; a snack does not.
Several actions asked for in one step run in order, the first failure stops the rest, and she hears once, at the end. Mid-action she is asked for a word only when something changed; standing idle for 30 s, she is reminded it is her game.
Every game action she took in one session on a vanilla server, all of them her own decisions. One block is one tool call.
She never places a house block by block. The mod clears what must be empty, places the rest from the ground up, walks where it needs to, and answers with every cell still wrong and every block it ran out of. A cell counts only once the server keeps it.
build_template for houses and shelters, with no spatial reasoning at all.build with layers and ops, for a wall, a floor, a box.build_script for towers, stairs and domes: a few lines run in a sandbox with no imports and no keys, and all that comes back is a list of cells.It runs on BeaCraft, a client-side Fabric mod that simulates input and sends ordinary packets — so the server sees a normal player, nothing is needed server-side, and it works on vanilla. Players who talk to her in game chat get an Author like anyone else, so the roster, the person cards and the attention gate all work in-game with no Minecraft-specific code. How the skill is built.
On stream
Pictures per mood, a 3D model, or your own Live2D: pick one in Settings, with a live preview of what the stream will see. Whichever it is, the mood she chooses for a line drives it, and between lines she is not a statue.
One picture per mood. Drawn by OBS, or by the browser source, where her mouth moves with her voice and she breathes and blinks without anything waiting on OBS.
A VRM in a browser source, on an idle motion with gestures on top. The dashboard fetches a free model in one click, reads its licence, and lets you try it on before it goes on stage.
Your own Live2D model, driven over its API. Her mouth keeps time with her voice over a long line, and an optional setting adds head, eye and blink life without a webcam.
Her captions are a separate choice — an OBS text source, the browser source, or nothing — so any avatar goes with any caption. A semantic picker maps whatever expression she names to the nearest one your model actually has. How the avatar works.
The sliding window
One window holds the whole stream — every platform, every game, one budget of 150k tokens by default and up to 500k. As it fills, a background handoff folds the cold past into a short recap and keeps the ongoing word-for-word. No sessions, no threads, no “sorry, I forgot what we were saying”.
One cycle of the window: it fills toward the trigger, the cold past folds into a bright recap strip, the hot present stays. The live numbers are in the architecture notes.
Sized in tokens, not messages. One ceiling, set in Settings, and the rest follows it: the handoff triggers at four fifths, the hot present is a fifth. At the default that is 120k and 30k.
Everything older than the hot present becomes a short recap reopened as [EARLIER]; the hot present, and every line said while the recap was written, travel over word for word. It runs in the background — the loop never waits on its own memory.
Every perception is annotated with a priority — addressed by name scores 1.0 — and a [WHERE YOU ARE] header keeps platform awareness. Nothing is dropped; the model decides what deserves an answer.
Memory
Not a context window that forgets when the stream ends. Three layers of memory, and all of them live in one SQLite file you can open, inspect, back up or delete.
data/bea.dbWhat happened, in her words, written as she goes. Recall runs over it with local embeddings, so remembering something does not cost an API call.
A tally for everyone she meets, and a card for the ones who turn out to matter. Talk to her enough and you get promoted from a number to a person.
Overnight she sleeps, consolidates the day, and works out things about herself. Those conclusions come back as facts she holds about who she is.
The control room
uv run bea --web opens a React dashboard over a FastAPI backend on port 8000. It checks the brain is actually answering before it lets you in. ⌘K opens the command palette from anywhere.
The API has no authentication, so it binds to 127.0.0.1 unless you say otherwise. The frontend · the API.
Try it in five minutes
The default profile is Solo chat: the dashboard and her voice, one API key, nothing else. No OBS, no Discord bot, no Minecraft server, no virtual audio cable — those are separate profiles you can pick later, or turn on one at a time.
curl -LsSf https://raw.githubusercontent.com/emqnuele/projectBEA/main/install.sh | bashInstalls uv if you do not have it, pulls the dependencies, builds the dashboard, asks you five questions and downloads the two models that run on your own machine. Already cloned it? uv run bea --setup does the same thing.
uv run beaCLI mode
uv run bea --webControl room on :8000
uv run bea --setupRe-run the wizard, safely
uv run bea --updateUpdate, keeping your edits
Pick Local models in the setup and she thinks through Ollama or LM Studio, with her voice and memory already local: nothing you say leaves the room. A key from OpenRouter, OpenAI, Groq, Google AI Studio or Claude gets you bigger models instead, and the two mix.
Her TTS writes to a real audio device, and Docker Desktop cannot pass one through. The container is the right way to run her as a 24/7 bot on a server — Discord, Telegram, Twitch, Minecraft, memory and the dashboard all work. It is the wrong way to stream with OBS. On Linux, uncomment the devices: block in docker-compose.yml.
For whoever stays
Architecture, configuration, every module, and one page per skill. Written next to the code and rendered here from the same source.
Python and React. Read the attention gate, swap an LLM provider, or write your own Skill — the plugin API is a base class and a registry.
The suite runs with no network access and no API keys: every model client, surface and transport is faked. CI runs it on every push.
Use it, fork it, ship something with it. A side project built for fun and learning, and open on purpose.