Open sourceMIT611 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.
curl -LsSf https://raw.githubusercontent.com/emqnuele/projectBEA/main/install.sh | bashHow 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/
A gate decides what is worth a thought.
Three outcomes, and only one of them costs a model call: react, note, or drop. Being addressed by name goes through unconditionally, past cooldowns and quiet hours. Everything else is scored. What is merely noted becomes peripheral awareness — she knows it happened, and can bring it up later without having stopped for it.
src/core/attention/
One consciousness reasons and acts through tools.
Not one bot per platform: one always-on loop that holds the stage — her voice, the game, and whatever her owner just asked for. Written channels run alongside it as scoped conversations, one turn at a time per channel, several channels at once. She can be talking out loud and texting at the same time.
src/core/mind/
Everything she does leaves through one sink.
speak, mc_chat, discord_reply, play_minecraft, objective_done. The tools she calls all funnel through a single expression layer on the way out to TTS and OBS, and 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. One scoped conversation per chat, running alongside whatever else she is doing.
Chat read anonymously — no token needed. Volume becomes texture rather than thoughts, and being named still gets through.
A body on a vanilla server. She plays toward objectives, reads game chat, and remembers the players she meets there.
Avatar swapped by mood over WebSocket, with an animated text bubble for what she is saying. For streaming, run her natively.
React and FastAPI: a bento overview, the live attention gate, her memory, today’s plan, and every setting. ⌘K from anywhere.
The Minecraft skill
She has a body on a vanilla server, and she does not pilot it block by block. She gives it an intention — get a stone pickaxe — and it goes and does that while she carries on with the conversation she was already having.
The goal goes down once. Everything after that happens on the lower lane, on the cheaper model, and the only thing that climbs back up mid-goal is a milestone — a block mined, a tool crafted, a death. Her voice never waits on any of it.
play_minecraft is long_running: it starts the body on a goal and returns immediately, so handing over a task costs her one tool call and no waiting. One goal at a time — a new one replaces the old.
A second loop on the cheap model pool: think, act, observe, up to 24 steps, with a survival guide and a notebook it rewrites as it goes. Working out that a pickaxe needs sticks is not what her good model is for.
Moving and looking are means, not results. Only a craft, a mine, a smelt, an interrupt or a death is worth telling her about mid-goal — and a goal still stuck after 24 steps says so instead of grinding on.
The body is driven by 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, which means the roster, the person cards and the attention gate all work in-game with no Minecraft-specific code. How the skill is built.
The attention gate
Answering every message is what makes an always-on persona expensive and exhausting to watch. She reacts to what concerns her and merely notices the rest — so the room can be loud without the bill or her attention following it up.
Thirty messages arrive. Four become a thought. This is a measured number, not an illustration: test_thirty_messages_a_minute_stay_under_four_model_calls asserts it on every commit.
Addressed by name, spoken to directly, or something her own body reported — a death, damage from a player. These go through unconditionally, past cooldown and quiet hours.
Worth knowing, not worth stopping for. It becomes peripheral awareness she can refer to later, without ever having interrupted what she was doing.
The volume of a busy chat. It still moves the room’s activity level, which is why a loud stream feels loud to her, but no single message of it becomes a thought.
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.
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, then asks you five questions. Already cloned it? make setup does the same thing.
uv run beaCLI mode
uv run bea --webControl room on :8000
uv run bea --setupRe-run the wizard, safely
OpenRouter, OpenAI or Groq. There is no offline mode and no local model support today — if that matters to you, it is worth knowing before you install rather than after.
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.