# ProjectBEA > A modular AI persona engine. One always-on consciousness that talks out loud, plays Minecraft with other people, and holds conversations on Discord, Telegram and Twitch — remembering who you are between sessions. ProjectBEA runs **Bea**: one always-on consciousness, not a bot per platform. Everything she perceives arrives on a single perception bus and passes a rule-based attention gate, which decides whether an event deserves a thought, a passing note, or nothing at all. What survives reaches one mind that reasons and acts through tools, one turn at a time per channel and several channels in parallel. Everything she says leaves through a single expression sink that drives TTS and the OBS avatar. Every capability beyond that is a plugin skill that can be toggled at runtime: memory (RAG over a diary, person cards and self-lore in one SQLite file, embedded locally), Minecraft (an autonomous agent playing a vanilla server through a custom Fabric mod), Discord (cross-language voice with barge-in and resumption), Telegram, Twitch, donations, stream plan, social and dream. LLM, TTS, STT and OBS all sit behind interfaces, models are configured per role in pools that round-robin and fall back when a provider dies, and almost everything hot-reloads without a restart. A React and FastAPI control room drives the whole thing. 611 tests run with no network access and no API keys. ## Facts - **License**: MIT — https://github.com/emqnuele/projectBEA/blob/main/LICENSE - **Language**: Python 3.10, 3.11, 3.12, with TypeScript for the dashboard and Java for the Minecraft mod - **Repository**: https://github.com/emqnuele/projectBEA - **Surfaces**: Discord, Telegram, Twitch, Minecraft, OBS - **Requires**: an API key from OpenRouter, OpenAI or Groq. There is no offline mode and no local model support today. - **Install**: `curl -LsSf https://raw.githubusercontent.com/emqnuele/projectBEA/main/install.sh | bash`, then `uv run bea --web` - **Author**: Emanuele Faraci — https://emanuelefaraci.com ## Getting started - [ProjectBEA — AI Persona Engine](https://projectbea.emqnuele.dev/docs.md): ProjectBEA is a modular AI persona engine. It runs Bea: one always-on consciousness that talks out loud, plays Minecraft on a vanilla server with other… - [Setup & Installation](https://projectbea.emqnuele.dev/docs/setup.md): You do not need to install Python yourself. uv reads requires-python from pyproject.toml and downloads a matching interpreter automatically. ## Core - [Architecture](https://projectbea.emqnuele.dev/docs/architecture.md): How ProjectBEA is actually put together. Every claim here is anchored to a file so it can be checked against the code rather than trusted. - [Configuration Reference](https://projectbea.emqnuele.dev/docs/configuration.md): Three sources, merged at startup. Secrets are the important row. The environment always wins: if the variable is set and non-empty, the config.json value is… ## Modules - [LLM Modules](https://projectbea.emqnuele.dev/docs/modules/llm.md): The LLM layer is provider-agnostic and tool-aware. The core primitive is LLMClient (src/core/agent/llmclient.py); every model call in the app goes through it. - [TTS Modules](https://projectbea.emqnuele.dev/docs/modules/tts.md): The TTS layer is defined by TTSInterface. Every engine returns a NumPy audio array plus a sample rate; Expression (src/core/expression/voice.py) is what plays… - [STT Module](https://projectbea.emqnuele.dev/docs/modules/stt.md): Transcribes an audio file to text. It is used in three places, all of them entrypoints where audio arrives already decoded as WAV. - [OBS Module](https://projectbea.emqnuele.dev/docs/modules/obs.md): The OBS module connects to OBS Studio via WebSocket and controls two types of sources in real time: Avatar source — swaps the image/video file to reflect… ## Skills - [Skills — the capability layer](https://projectbea.emqnuele.dev/docs/skills/overview.md): A skill is one capability of the single consciousness. There is one loop — the consciousness — and a skill plugs into it by doing any subset of these. - [Discord Skill](https://projectbea.emqnuele.dev/docs/skills/discord.md): Discord is Bea's voice and one of her text platforms. She can sit in a voice call and talk, read and answer text channels, DM people, react, and decide on her… - [Telegram Skill](https://projectbea.emqnuele.dev/docs/skills/telegram.md): Bea reads and answers Telegram — private chats and groups — as one more place where she has conversations. - [Twitch Skill](https://projectbea.emqnuele.dev/docs/skills/twitch.md): Reads a Twitch channel's chat and lets Bea talk to it. Chat is not a conversation she is having — it is the room she is standing in, so she answers it out… - [Minecraft Skill](https://projectbea.emqnuele.dev/docs/skills/minecraft.md): Bea has a body on a Minecraft server. She plays alongside other people: she reads game chat, answers it, recognises the players across sessions, reacts to… - [Memory Skill — long-term recall](https://projectbea.emqnuele.dev/docs/skills/memory.md): At the end of a session Bea writes a diary entry about it. On every turn, the entries that resemble what is happening right now are retrieved and injected… - [Social Memory — who people are](https://projectbea.emqnuele.dev/docs/skills/social.md): Everyone Bea has ever seen gets a tally. Only the people who made themselves matter get a card. - [Dream — sleep, self-lore, consolidation](https://projectbea.emqnuele.dev/docs/skills/dream.md): Three things that belong together because they are all about Bea knowing herself: self-lore — what she has learned about herself, always in her prompt; hot… - [Stream Plan — what she has to get done today](https://projectbea.emqnuele.dev/docs/skills/plan.md): The owner writes what today is supposed to be, from the dashboard. It sits in Bea's prompt until she has worked through it, and she closes the items herself… - [Donations](https://projectbea.emqnuele.dev/docs/skills/donations.md): A donation is the one input that always deserves a reaction. Any provider that can call a webhook — StreamElements, Ko-fi, Streamlabs — posts to POST… - [Monologue — the passage of time](https://projectbea.emqnuele.dev/docs/skills/monologue.md): When nothing has happened for a while, Bea says something anyway — a streamer filling dead air. ## Web - [Web API Reference](https://projectbea.emqnuele.dev/docs/web/api.md): The FastAPI server (src/web/app.py) starts with uv run bea --web. It serves both the REST API and the compiled React frontend from the same origin. - [Frontend — the control room](https://projectbea.emqnuele.dev/docs/web/frontend.md): A React + Vite + Tailwind v4 single-page app, served by the brain from its own origin. It is the control room for one always-on consciousness: what she is… ## Contributing - [Contributing](https://projectbea.emqnuele.dev/docs/contributing.md): uv installs Python for you, so there is no pyenv step and no virtualenv to activate by hand. ## Optional - [Every page in one file](https://projectbea.emqnuele.dev/llms-full.txt): the complete documentation, concatenated. - [The repository](https://github.com/emqnuele/projectBEA): the code these documents describe.