Brain turns the things you watch and read — YouTube talks, podcasts, arXiv papers, Hacker News threads, engineering blogs — into a searchable knowledge base of Markdown notes, then works on top of it: a morning digest, ideas tied to your projects, a weekly reflection, a daily plan, and post drafts. It runs entirely on your machine: notes are plain files, the search index is local, and only the text you choose to analyze goes to the Claude API.
The second interface is a Telegram bot — the same commands from your phone, with voice messages in and out.
Ingests— paste a link, get a structured note: summary, key theses, strong quotes with timestamps, and ideas that connect the material to your own projects. YouTube subtitles when available, local Whisper transcription when not.Scouts— checks your channel subscriptions, searches YouTube by your topics, and pulls arXiv, Hacker News, RSS blogs, Reddit, and podcasts. Every candidate is scored 1–10 against your profile in a single batch call; 8+ is added automatically, 6–7 goes to a suggestions file, the rest is dropped.Answers— semantic search over every note (local embeddings, Russian + English) plus a Claude answer that cites which material it came from.ask
for one-off questions,chat
for a conversation.Thinks— a morning digest with ideas of the day, a weekly reflection across the whole base, a "dream" pass that proposes updates to your interest profile, a radar of topics worth commenting on, and a daily plan that pushes back when you skip fundamentals.Stays private— your notes, profile, and state never leave the machine. Everything personal is gitignored; the code itself carries no personal data (seePersonalization).
git clone https://github.com/mstick3/brain.git ~/brain && cd ~/brain
python3.12 -m venv .venv
.venv/bin/pip install -e .
cp .env.example .env # add your ANTHROPIC_API_KEY
cp profile.example.md profile.md # fill it in — output quality depends on it
.venv/bin/brain add "https://www.youtube.com/watch?v=..."
.venv/bin/brain ask "what did they say about agent memory?"
To call brain
from anywhere:
ln -sf ~/brain/.venv/bin/brain /opt/homebrew/bin/brain
brain add <url> [<url>...] # add a video/podcast (--file urls.txt, --whisper)
brain ask "question" # semantic search + a cited answer
brain chat # conversation with your base (--en for English practice)
brain list # everything in the base
brain reindex # rebuild the index after editing notes by hand
brain follow <channel-url> # subscribe to a YouTube channel
brain follows / unfollow <query>
brain topics add "ai agents" # search topics for the scout
brain discover # run the scout now
brain sources # arXiv / HN / blogs / Reddit: list, add, remove, run
brain podcast add <rss-url> # podcast episodes, transcribed locally
brain daily # morning digest (--force, --resend)
brain ideas # ideas from the last 30 days (--all for everything)
brain reflect # weekly reflection over the whole base
brain dream # proposed profile updates (--apply to accept)
brain radar # topics worth commenting on today
brain post ["topic"] # a post draft in your voice
brain day # today's plan: one main result + 2-3 tasks
brain task "text" / brain tasks # add / show tasks
brain draft "what you need" # draft an email, message, or document outline
brain model # model split and API spend per day
brain lang ru|en # output language
brain youtube connect [browser] # use your YouTube cookies for gated videos
brain telegram test|listen|status
- macOS (the digest uses macOS notifications; the rest is portable) and Python 3.11+
- An
Anthropic API key
ffmpeg
for the Whisper path:brew install ffmpeg
- Optional: a Telegram bot, if you want the digest and the assistant on your phone
Models are split in two tiers, configured in brain/config.py
: a fast one for bulk work (scoring candidates, turning transcripts into notes) and a stronger one for thinking (digest, ideas, reflection, chat, posts). brain model
shows the split, the prices, and what you have spent per day.
The first Whisper run downloads a ~1.5 GB model, and the first search downloads a small local embedding model. Both are cached afterwards.
Data lives in ~/brain
by default. Point it elsewhere with BRAIN_HOME
:
export BRAIN_HOME="$HOME/Documents/brain-data"
.env
holds the secrets:
ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=
Brain was built Russian-first: the system prompts are written in Russian and the default output language is Russian, while transcripts and quotes are always kept in the original language of the source. brain lang en
switches everything Brain writes for you — summaries, theses, ideas, answers, digests — to English. The two optional profile sections the code reads still use their Russian headings (## Мой угол
, ## Приоритет сейчас
); translating the prompt layer is a welcome pull request.
profile.md
is where you live: who you are, your projects, your goals, your blind spots, what you want out of ideas. It is attached to every request, and the quality of everything Brain produces depends on how honestly it is written. Start from profile.example.md
.
Two optional sections are read directly by the code — ## Мой угол
(your angle, used by the radar) and ## Приоритет сейчас
(your current priority, used by the daily plan). Leave them out and those prompts stay generic, deriving what they need from the rest of the profile. No personal detail is hardcoded in the source.
- Create a bot with
@BotFatherand put the token in
.env
asTELEGRAM_BOT_TOKEN
. - Press
Start in your new bot, then runpython scripts/tg_get_chat_id.py
— it waits for your message and writesTELEGRAM_CHAT_ID
into.env
. - Check it:
brain telegram test
. - Run the listener:
brain telegram listen
(or install the launchd job below to keep it alive).
The bot answers only the owner (TELEGRAM_CHAT_ID
); anyone else gets a polite refusal. It gives you menu buttons (digest, ideas, ask, post, dream, day), adds any video link you send, transcribes voice messages locally and can answer with voice, closes tasks (сделано 2
), and records 👍/👎 on ideas and posts so future suggestions drift toward what you actually like.
Templates for all six jobs are in launchd/ — digest, scout, reflection, dream, weekly post draft, and the bot. Install them all:
for f in launchd/*.plist; do
name=$(basename "$f")
sed "s|__BRAIN_HOME__|$HOME/brain|g" "$f" > "$HOME/Library/LaunchAgents/$name"
launchctl bootstrap gui/$(id -u) "$HOME/Library/LaunchAgents/$name"
done
| Job | When | What |
|---|---|---|
com.brain.daily |
||
| daily 06:30 | subscriptions, sources, digest | |
com.brain.discover |
||
| daily 12:00 | scout by topics | |
com.brain.reflect |
||
| Sun 07:00 | weekly reflection | |
com.brain.dream |
||
| Sun 07:30 | proposed profile updates | |
com.brain.post |
||
| Fri 07:00 | weekly post draft | |
com.brain.telegram |
||
| always | the bot (KeepAlive) |
link / feed → transcript or article text → Claude (analysis) → Markdown note in vault/
↓
chunks + local embeddings → index.db (SQLite)
↓
ask · chat · digest · ideas · reflect · dream · radar · day
Notes are plain Markdown with YAML frontmatter — the vault opens as anObsidianvault, and nothing locks your data in.Search is cosine similarity over locally computed multilingual embeddings; no vector service, no data leaving the machine for retrieval.Budget— subscriptions, the scout, and sources add at most 8 items per day (MAX_ADDS_PER_DAY
), so a busy news week cannot run up your bill.Fetching is guarded(brain/net.py
): links coming from third-party feeds are restricted tohttp(s)
, refused for local and private-network addresses, redirect-checked, and size-capped — feed content ends up in prompts and notes, so it is filtered on the way in.State is written atomically(brain/storage.py
): a crash mid-write leaves the previous version intact rather than a truncated file.
~/brain/
├── brain/ # source
├── tests/ # pytest suite
├── launchd/ # scheduling templates
├── vault/ # your notes (gitignored)
├── digest/ dreams/ # generated output (gitignored)
├── index.db # search index (gitignored)
├── profile.md # who you are (gitignored)
└── .env # secrets (gitignored)
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest
115 tests, no network and no API calls. tests/conftest.py
swaps BRAIN_HOME
for a temporary directory before the package is imported, so the suite never touches a real knowledge base.
Issues and pull requests are welcome. Two house rules: no personal data in the code — anything about a specific user belongs in profile.md
— and new logic comes with a test that does not need the network.
MIT © Tygran Nushykian