Brainstack is a personal, fully self-hosted Telegram bot that records your unstructured audio thoughts, transcribes them using local faster-whisper, and meticulously organizes them into a daily Markdown journal using google-genai. It includes a built-in FastAPI web viewer to securely traverse and edit your digital mind.
Deploying Brainstack to your homelab is natively supported via Docker Compose.
- Clone the repository:
git clone https://github.com/yourusername/brainstack.git cd brainstack - Configure your Environment:
cp .env.example .env # Edit .env with your Telegram token, Gemini API key, and Web Password - Launch the Stack:
docker-compose up -d
The bot will immediately start listening on your private Telegram channel, and your web viewer will be running securely at http://localhost:8000.
Brainstack strictly follows a microservice philosophy:
brainstack-bot: Listens to Telegram audio, transcribes it cleanly, and prompts Gemini to categorize your thoughts into 4 distinct phases (Lineage, Actions, Content Drafts, Psychologist Analysis).brainstack-web: A lightweight FastAPI wrapper serving pure HTML templates, meaning there is zero Javascript bloat when managing your Markdown strings.
Personal Notes and Environment configurations are strictly .dockerignore'd and .gitignore'd to maintain complete data supremacy.
Open-source contributions are welcome! To maintain the strict deterministic logic of the parser, please read CONTRIBUTING.md for information on using the mandated ./scripts/verify.sh test suite before filing Pull Requests.
