agent-second-brain: a Telegram voice bot that files your notes into Obsidian

The problem: capture costs more than forgetting

The README opens with an admission that most productivity systems die the same way: you set one up on a Sunday, use it for two weeks, then stop, because maintaining the system is more work than the work itself. Voice memos go unlistened. Ideas drown in chat history. The vault becomes a directory of markdown files that nobody, including its owner, can navigate a month later. That is the specific failure agent-second-brain is aimed at, and it is a capture problem rather than a storage problem.

The intended user is narrow. You keep an Obsidian vault, you already pay for a Claude subscription, and you are willing to run a small Linux host. The README pitches a $5 VPS and states the project runs 24/7 on the subscription you already have, with no per-token API bills. If any of those three conditions is false, the value proposition weakens considerably. Someone who wants a hosted notes app with a phone client is not the audience. Someone who wants a local-first capture layer they can audit is.

How the persistent Claude Code session works

The mechanism is the part worth reading carefully. Since June 15, 2026, according to the README, headless claude -p runs bill against a separate paid Agent SDK credit. Version 3.0 sidesteps that by driving one long-lived interactive Claude Code session inside tmux, the same thing you would run in a terminal. The README states there are no headless calls in the hot path and that a CI guard fails the build if anyone adds one. That guard is the strongest signal in the repository: the billing model is enforced structurally, not by convention.

Data flow is Telegram to vault. A voice note arrives, Deepgram transcribes it in seconds per the project description, and the agent reads the text plus any attached photos, documents, videos, forwarded posts or albums. It then writes into the vault as plain markdown and links the new material into an existing graph. The memory layer is a separate project, autograph, shipped here as a skill and also usable standalone on any Obsidian vault. The README describes typed cards with a type, description, tags and status governed by one schema.json, wiki-links between cards, Ebbinghaus decay across five tiers, automatic MOC indexes, health scoring, link repair and dedup.

Two scheduled pieces sit on top. The agent schedules its own cron jobs from plain language, covering one-shots, intervals and full cron expressions, with no external task manager. At 21:00 local time a nightly pass classifies the day's entries, writes vault cards, updates goals and long-term memory, rebuilds the graph, and sends a daily report. A watchdog recovers a wedged session, and a daily doctor sends a canary report.

Installing agent-second-brain on a fresh VPS

The repository ships bootstrap.sh, setup.sh and upgrade.sh at the top level, plus a docs/vps-setup.md guide. The README advertises a one-command install on a fresh VPS but does not reproduce the command in the excerpt available here, so the honest starting point is the setup guide rather than a guessed incantation. What is documented is configuration. Copy .env.example to .env and fill in the required values:

TELEGRAM_BOT_TOKEN=
DEEPGRAM_API_KEY=
VAULT_PATH=./vault
ALLOWED_USER_IDS=[123456789]
TZ=UTC
CLAUDE_MODEL=
CRON_ENABLED=true

The Telegram token comes from @BotFather. The Deepgram key handles transcription. VAULT_PATH points at your Obsidian vault directory. ALLOWED_USER_IDS is a JSON array of permitted Telegram user IDs, and the README notes that an empty value allows all users, while the first ID also receives health alerts and daily reports. TZ drives systemd timers and reports, so set it to your real zone rather than leaving UTC.

One setting deserves attention before you start. CLAUDE_MODEL is empty by default, which the comment says means the Claude Code default, Opus. For a bot running continuously, the same comment suggests setting it to sonnet to reduce weekly-limit pressure. That is a direct acknowledgement that a 24/7 agent consumes subscription quota, and it is the first thing I would change on a fresh install.

The advanced block is where the operational knobs live. RUNTIME_DIR defaults to ~/.dbrain and the comment states it must be a local filesystem, which matters if you were considering a network mount. BRAIN_SESSION_NAME is empty by default and generated per install. CRON_TICK_SECONDS defaults to 60, CRON_JOB_TIMEOUT to 600, CRON_MAX_CONSECUTIVE_ERRORS to 3, and CRON_RETRY_SECONDS to 300. Those defaults describe a job that runs every minute, times out after ten minutes, and disables itself after three consecutive failures. ALLOW_ALL_USERS is present and the comment labels it a security risk to be left false.

For a first real use, the README's own example is the clearest target: send a voice note describing a call, and the bot replies with a saved confirmation, a link to a project card, and a reminder. Then ask it a question in plain text about something you wrote last week. If the second step returns nothing, the graph is not being written where you think it is, and VAULT_PATH is the first thing to check.

Where agent-second-brain breaks down

The largest constraint is the subscription itself. The whole design exists because headless runs began billing separately, and the workaround is one interactive session. That session is a single point of failure with a watchdog in front of it. If the session wedges in a way the watchdog does not catch, or if your weekly limit is exhausted, capture stops. A per-token API setup has a different failure mode: it keeps working and sends a bill. Neither is strictly better, but the trade is real and the README is upfront about which side it chose.

Memory decay is the second sharp edge. Ebbinghaus decay across five tiers means the graph is designed to forget. That is the stated philosophy, and it is defensible for a personal brain, but it is the wrong property for an archive. If you need every note retained at full strength indefinitely, a system that fades cards and rescores links will fight you, and you would be better served by a plain capture pipeline that writes files and stops.

The single-owner model is the third. ALLOWED_USER_IDS is a list, but the first ID receives alerts and reports, and the security note treats opening the bot to everyone as a risk. There is no described notion of per-user vaults or shared team memory. Running this for a group means everyone writes into one graph with one agent identity.

Finally, the documentation is uneven. The README is long and opinionated about philosophy, and the Russian setup guide is linked as the beginner path, but the English excerpt does not carry a full step-by-step install. Release notes for v3.0.1 through v3.0.3 mention a spinner drift hotfix, fresh-install and timezone fixes, and a login fix, which suggests early v3 installs had rough edges. The last push to the repository was on 2026-08-05, so the code is recent, but a fresh install today should be treated as a v3.0.x install with a short track record.

autograph versus a plain capture pipeline

The closest alternative is not another Telegram bot. It is a minimal pipeline: a transcription service plus a script that appends markdown files to a folder. Tools in that space do one thing, write text, and leave organization to you. The difference in approach is that agent-second-brain refuses to leave organization to you. It classifies, types, links and indexes, and it runs a nightly pass that rewrites the graph structure.

That is a genuine trade. A dumb pipeline never corrupts a link, never decays a card, and never needs a watchdog, because there is nothing to watch. It also produces the exact outcome the README describes as the reason the project exists: a vault nobody can navigate. agent-second-brain bets that automated filing is worth the operational surface, and the autograph engine is the part that carries that bet. The README points readers who only want the memory layer at autograph as a standalone project, which is a reasonable escape hatch. If you want typed cards and decay on an existing vault without the Telegram bot, that is the smaller dependency.

On the model side, the comparison is between an interactive Claude Code session and any headless agent loop. The README's position is that the interactive session is how the subscription is meant to be used. Anyone evaluating this should test that assumption against their own quota before trusting a 24/7 workload to it.

Licence, upgrades and what maintenance costs

The project is MIT licensed, which permits commercial use, modification and redistribution with the licence and copyright notice retained. That is permissive enough that the practical question is not legal but operational: you are running an agent with access to a bot token, a transcription key, and a local vault, on a host you control. Nothing in the licence changes that responsibility.

Upgrades are an explicit path. The repository carries upgrade.sh, and the README has an upgrading section covering v1 and v2 installs, so the maintainer expects existing users to move forward rather than reinstall. Three patch releases landed within a week in June 2026, then v3.0.3 on 2026-06-20, and the last push was 2026-08-05. The cadence is recent but not continuous, and the patch notes describe fixes rather than features. The dependency list is small and pinned with upper bounds: aiogram 3.x, croniter, deepgram-sdk 5.3, httpx, pydantic 2.x and pydantic-settings. Python 3.12 or newer is required, and the build backend is uv_build with the module named d_brain.

The ongoing cost is threefold: the VPS, the Deepgram usage for transcription, and the Claude subscription quota the agent consumes. The README claims zero per-token API bills, which is true only within the subscription's limits. The CLAUDE_MODEL comment about sonnet reducing weekly-limit pressure is the maintainer telling you that a busy bot can hit those limits.

Editorial conclusion

Adopt it if you already run a Claude subscription, keep an Obsidian vault as plain markdown, and want capture to be a voice note rather than a form. Do not adopt it if you need a hosted service, if you refuse to run a tmux session on a VPS, or if your team needs shared multi-user memory, since the allowlist model is built around one owner. Before committing, verify the vault path in .env, confirm the interactive session actually stays alive on your host, and read the autograph skill in vault/ to see what the decay tiers will do to your existing cards.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. smixs/agent-second-brain on GitHub