agent-second-brain: a Telegram inbox that files itself into an Obsidian vault

One interactive Claude Code session in tmux, and a CI guard to keep it that way

The architectural decision that shapes everything else is stated as a warning rather than a feature. Since 2026-06-15, headless `claude -p` runs bill against a separate paid Agent SDK credit rather than against a subscription. So v3.0 drives one long-lived interactive Claude Code session instead, the same process a person would run in a terminal, used the way the subscription is meant to be used.

The consequence is a persistent session, and the project keeps it in tmux so it survives a dropped shell. A session that dies takes the assistant with it, which is why the self-healing features exist at all: a watchdog that recovers a wedged session, a daily doctor that sends a pass or fail canary report, and scheduled jobs that disable themselves after repeated failures and say so in the chat rather than failing silently.

Keeping the interactive path is not a convention the project relies on discipline for. A CI guard fails the build if anyone reintroduces a headless call in the hot path. That is the cheapest possible protection against a refactor quietly reintroducing per-request billing, and it is the kind of thing most projects would write in a comment instead.

Telegram is the whole interface, and a note that arrives is a note that gets filed

The premise is that organising is what kills a note system, so the agent does the filing and the human does the talking. The capture side accepts more than text. Voice notes are transcribed through Deepgram, and the stated design target is that capture has to be cheaper than forgetting, with a voice note costing about five seconds of your attention. Photos, documents, videos, forwarded posts, and whole albums go in as well, and the agent reads the files itself and files the takeaways rather than asking you to summarise them first.

The claim attached to that list is that nothing you send is ever silently dropped, which is a stronger promise than most capture tools make and the one worth testing before you trust it. The example exchange in the documentation shows the shape of a result: a voice note about a call becomes a CRM card update linked to a project note, plus a reminder set for a named day and time, and when the reminder fires it carries the context back with it.

A second interaction pattern is retrieval, where you ask what you wrote about something last week, the agent finds and quotes the entries, and you ask for one of them to be turned into a project note with next steps, which it then links to the related client card:

You:  what did I write about the marketing project last week?
Bot:  *finds the entries, quotes them, links the cards*
You:  turn the second idea into a project note with next steps
Bot:  *creates the note, links it to the client and this week's goals*

No commands to memorise, no categories to pick, and no second application to open. The chat is the whole interface.

Memory that decays, with a strength formula and five tiers

The memory layer is a separate project, autograph, shipped inside this one as a skill and usable on its own against any Obsidian vault. Its premise is that storage is not memory. Knowledge weakens on the Ebbinghaus curve, so a card that is never touched fades, and only what resurfaces when it is relevant stays sharp.

The mechanics are specific. Every card carries a type, and the types are note, contact, project, and CRM, along with a description used for retrieval, tags, and a status, all governed by a single `schema.json`. Strength is computed as `1 + ln(access_count)`, so each touch slows further forgetting rather than resetting a clock. The documented half lives are roughly a hundred days for contacts and about twenty-five for dailies, which is the difference between a relationship note and a scratch entry surviving on their own terms.

Cards sit in five tiers, core, active, warm, cold, and archive, and touching a card promotes it back up. There is also a random recall path that occasionally surfaces an archived card next to something current, described as sometimes noise and sometimes the idea you had forgotten. The maintenance side handles orphan detection, broken link repair, deduplication into a `.trash/` directory, MOC index generation, and a hundred point health score.

The agent writes its own cron jobs from plain language

Scheduling is delegated rather than delegated to a service. You say remind me Friday at 3pm, or every weekday at 18:30 check my inbox folder, and the agent translates that into a scheduled job through a cron skill, covering one-shots, intervals, and full cron expressions. The project positions this as removing the need for an external task manager rather than as a scheduling feature of its own.

Alongside that sits the nightly pass, which runs at 21:00 in your configured timezone. It classifies the day's entries, writes vault cards, updates goals and long-term memory, rebuilds the graph, and sends a daily report. Rebuilding the graph as a scheduled step rather than an on-demand one is what makes the decay tiers and the MOC indexes actually reflect the day rather than the last time somebody opened the vault.

The configuration surface for all of this is in the environment file, and the defaults are described as sensible. `CRON_ENABLED` defaults to true and turning it false stops the ticker entirely, `CRON_TICK_SECONDS` defaults to 60, `CRON_JOB_TIMEOUT` to 600, `CRON_MAX_CONSECUTIVE_ERRORS` to 3, and `CRON_RETRY_SECONDS` to 300. That last pair of numbers is the auto-disable policy: three consecutive errors and a job switches itself off and tells you.

ALLOWED_USER_IDS left empty opens the bot to everyone

Access control is one JSON array, and its empty state is permissive. `ALLOWED_USER_IDS` is documented as a JSON array of Telegram user IDs allowed to use the bot, where empty means allow all. The advanced section repeats the point in a comment: allow everyone to talk to the bot is a security risk and the flag should be left false. Those are two different defaults for the same behaviour, and the first comment is the one a person editing the file is most likely to act on.

The first ID in the list has an extra job, since it is the one that receives health alerts and daily reports. That is convenient for a single user and wrong for a shared deployment, since the operator and the intended recipient are assumed to be the same person.

The remaining settings are mostly about where state lives. `RUNTIME_DIR` defaults to `~/.dbrain` and is commented as needing a local filesystem, because it holds session locks, logs, and cron state. `BRAIN_SESSION_NAME` is left empty so the tmux session name is generated and persisted per install, and `VAULT_PATH` points at `./vault`. The Telegram token and the Deepgram key are the only two values without a default.

It is Claude Code underneath, so MCP servers and skills drop straight in

The bot is not a wrapper around a model API. It is Claude Code driven through Telegram, and the extension points come with that. Any MCP server can be dropped into `mcp-config.json`, and any skill can be added under `vault/.claude/skills/`, so the capabilities of the assistant are extended by editing files rather than by configuring a plugin marketplace.

That has an architectural consequence worth naming. The vault directory is not only a data store, it is the agent's workspace, and the lint configuration says so explicitly: the bot's lint gate covers `src/` and `tests/` only, and `vault/` is excluded from ruff because the skills in there keep their own style. The two lint scopes are deliberately different, which means code you drop into the vault is not held to the same rules as the code that runs the bot.

The package structure reflects the same split. The distribution is built as the module `d_brain` even though the project is named agent-second-brain, it requires Python 3.12 or newer, and its runtime dependencies are six: aiogram for the bot, croniter for the schedule parsing, the Deepgram SDK for transcription, httpx, and pydantic with pydantic-settings.

Plain markdown is the deliverable, and the process is meant to be disposable

The stated design goal is that deleting the agent tomorrow costs you nothing, because everything lives as plain markdown in your own Obsidian vault on your own server, with no export button and no lock-in. That is the strongest structural claim in the project and the easiest to check: read a card, and it is a file.

The memory layer reinforces it. Deduplication moves superseded material into `.trash/` rather than deleting it, MOC generation rebuilds indexes automatically, and a health score turns vault upkeep into a number instead of a chore. The intent is stated bluntly: you never run vault chores again.

Scale is the other selling point. The project describes itself as one Python process, a handful of modules, and more than 220 tests, small enough to audit in an evening if you are about to hand it your private notes. The release history backs the claim that it is actively reworked rather than abandoned, with v3.0.1 a spinner drift hotfix, v3.0.2 a fresh install and timezone fix, and v3.0.3 a login fix with calmer alerts, all inside the first three weeks of June 2026. The last push to the repository is dated 2026-08-05, and the licence is MIT.

Editorial conclusion

This fits a self-hoster with a VPS, an Obsidian vault, and a Claude subscription who wants capture to be one voice note and filing to happen without them. It does not fit anyone who needs a hosted service, and it does not fit a machine without a persistent tmux session available, since that session is the architecture rather than an implementation detail. Before you install, check three things: that you set TELEGRAM_BOT_TOKEN and DEEPGRAM_API_KEY and understand that the first value in ALLOWED_USER_IDS receives every health alert and daily report, that you read CLAUDE_MODEL before leaving it empty, because the default is the expensive tier for a process that runs all day, and that the runtime directory sits on a local filesystem, which the configuration file calls out explicitly. The last push was 2026-08-05 and the newest release is v3.0.3 from 2026-06-20.

Frequently asked questions

Official sources

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