Second Brain: A Local-First Agent Runtime You Install With pip and Drive From Telegram
Second Brain is an agentic framework that acts as an operating system, using local file intelligence, workflow automation, and LLMs to complete tasks and communicate over multiple modalities and messaging platforms.
At a glance
- What is it?
- Second Brain is a Python agent framework that turns a folder on your own machine into the assistant's working memory, then reaches you over Telegram or a web UI. It is a personal automation runtime, not a hosted service, and the README is candid that a fresh install is deliberately small.
- Who is it for?
- Adopt Second Brain if you want an agent that reads and edits files on the machine you already own, and you are comfortable running a Python REPL, a venv, and a bot token you created yourself. Do not adopt it if you need a hosted, multi-tenant service with a published API stability contract, or if you cannot give an LLM process write access to a directory you care about.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem It Solves: An Agent That Can See Your Files
Most agent frameworks assume the interesting context lives behind an API. Second Brain assumes it lives in a directory. The README frames the project as an operating system built on local file intelligence, workflow automation, and LLMs, and the install instructions make the intent concrete: you clone the repository, create a virtual environment, install dependencies, and run `python main.py` on your own machine. The assistant then works against that machine rather than a remote sandbox. The audience is a single technical user who wants an assistant with file read and edit, shell and script running, SQL, web search, and subagents, reachable from a phone. The README is explicit that this is a personal tool: the Docker path is described as the fallback for when the machine is not one you want to install on, such as a server or a NAS, and it notes that a container starts out unable to see your machine. That sentence is the whole design thesis in one line. If your problem is coordinating a fleet of agents across tenants, this is the wrong shape. If your problem is that your notes, PDFs, spreadsheets, and audio files are invisible to every chat assistant you use, this is aimed directly at you.
How It Works: Attachment Parsing, an LLM Loop, and Two Task Triggers
The README documents the architecture as a numbered infographic sequence rather than prose, so the mechanism has to be read off the section titles. The order is: attachment parsing, file parsing, the LLM loop, path-driven tasks, event-driven tasks, conversation runtime, frontends, commands, plugins, and a sandbox plus SDK. Read as a data flow, an inbound message arrives with attachments, those attachments are parsed, and files on disk are parsed into a form the model can consume. The LLM loop then runs tool calls against that parsed material. What makes the design more than a chat wrapper is the split between path-driven and event-driven tasks. Path-driven work is scoped to a location in the filesystem, which is the natural fit for a knowledge base you point the agent at. Event-driven work responds to something happening rather than something being asked, and the repository topics include `cronjob-scheduler`, so scheduled execution is part of the intended surface. The conversation runtime sits above both and is what the frontends talk to. Commands and plugins are the extension points, and the sandbox and SDK section suggests third-party code is expected to run with some isolation. The README does not spell out the sandbox's isolation model, and that is a gap worth noting: the word appears as a heading with no accompanying text in the supplied material, so I cannot tell you whether it is a subprocess boundary, a container, or a permission check.
Installation: venv, requirements.txt, and a Setup Wizard That Picks Your Model
The install is short and the README gives it verbatim. You need Python 3.11 or newer and git. Clone `https://github.com/henrydaum/second-brain`, change into the directory, and run `python -m venv .venv`. Activation differs by platform: `.venv\Scripts\activate` on Windows, `source .venv/bin/activate` on macOS and Linux. Then `pip install -r requirements.txt` and `python main.py`, which drops you into a REPL. The README claims requirements.txt is nearly pure Python, which matters if you have ever tried to install a document-parsing stack and watched it compile native libraries for ten minutes. The Docker alternative is `docker build -t second-brain .` followed by `docker run --rm -it --init -v sb-data:/data second-brain`, with state in the `sb-data` volume. Once inside the REPL, `/setup` runs a wizard with four steps: install the `essentials` bundle, connect a model by pasting an API key, optionally configure Telegram, and optionally install the web UI. The `essentials` bundle is described as containing an LLM backend, file read, edit and search, shell and script running, SQL, web search, subagents, and the Telegram frontend. Telegram needs a bot token from @BotFather and your user ID from @userinfobot. Further capabilities come from `/packages install`, which opens a picker on the web UI under Settings. The `bundle_knowledgebase` bundle is the one to look at for indexing your own files: PDF, Office, images, audio, video, spreadsheets, archives, with OCR, transcription, and embeddings. Note that the README text cuts off mid-sentence in that table, so the full contents of `bundle_knowledgebase` are not confirmable from what I have.
The Benchmark Claim and Why You Should Read the Caveats
The README states that Second Brain performs higher than OpenClaw and Hermes on harness-bench, described as measuring model-harness configuration effects across 106 sandboxed offline agent tasks. It links an evaluation framework at `henrydaum/second-brain-evals` and results at `henrydaum/second-brain-eval-results`. The author also states plainly that the testing was done out of curiosity about how Second Brain would stack up, and that there are a few small caveats documented in those links. That framing is more honest than most benchmark sections in agent repositories, and it is also the reason to treat the number carefully. The metric is about harness configuration effects, which means it is measuring how the surrounding scaffolding interacts with a model, not the raw capability of any model. Self-run evaluations on a benchmark the author selected are a starting signal, not a purchasing decision. If the choice between this and another harness matters to you, the useful move is to open the eval repository, read the caveats, and check whether the 106 tasks resemble your workload. Sandboxed offline tasks are a particular shape: no network, no live APIs, no messy real files. Your knowledge base is the opposite of that.
Where It Fits Badly: Single-User Assumptions and a Thin Sandbox Story
The limitations follow from the strengths. First, this is a personal assistant for one machine. The README's own comparison between the venv path and Docker says the venv path is better for day-to-day use because the assistant is for your machine, and the container is for machines you do not want to install on. There is no discussion of multi-user authentication, per-user isolation, or tenancy. Second, the sandbox is named in the architecture diagram but not explained in the supplied text, so if you plan to run third-party plugins you are trusting a boundary you cannot evaluate from the README alone. Third, the extension model is bundle-based and the README says a fresh install is deliberately small. That is a reasonable default, but it means the out-of-the-box experience is a REPL with file and shell tools, and the knowledge base capability you probably want arrives later via `/packages install`. Fourth, the project has no retrieved releases. There is no version number, changelog, or tagged release in the material I have, which makes upgrade planning harder: you are tracking a default branch. Fifth, an agent with file edit and shell execution pointed at your home directory is a real blast radius. The README does not describe a confirmation step before writes. Whether one exists is something you should check before pointing it at anything you cannot restore from backup.
Second Brain Versus a Hosted Agent Platform
The obvious alternative is a hosted agent product, the kind where you connect a data source through OAuth and the vendor runs the loop. The difference in approach is not a feature list, it is where the files live and who operates the runtime. A hosted platform indexes documents you upload or connect, keeps them in the vendor's storage, and gives you a web interface with someone else's uptime target. Second Brain inverts every one of those. Your files stay on your disk, the loop runs as a Python process you started, and the interface is a Telegram bot or a web UI you installed yourself. That buys you things a hosted product cannot easily offer: the agent can run shell commands and scripts on your machine, it can read a spreadsheet without you exporting it, and no third party holds a copy of your notes. It costs you things a hosted product handles for you: there is no status page, no support contract, and no one else to blame when the process dies. The honest comparison is against a general-purpose coding agent CLI too. Those are typically scoped to a repository and a terminal session. Second Brain's differentiator is the persistence layer underneath: path-driven tasks bound to a folder, event-driven tasks on a scheduler, and a conversation runtime that survives across frontends. If you only ever want an agent inside one repo for twenty minutes, a coding CLI is lighter. If you want an assistant that knows your whole file tree and pings you on Telegram, that is the gap this fills.
Licence, Maintenance, and Upgrade Cost
The licence is MIT, which is permissive: you can use, modify, and redistribute the code, including in commercial settings, provided the copyright notice and permission notice are preserved. That is a statement about the licence text, not legal advice, and if you are embedding this in a product you should have someone qualified read the actual LICENSE file and any third-party dependency licences that `pip install -r requirements.txt` pulls in. On maintenance, the material shows a last push of 2026-09-08 and no retrieved releases. The practical consequence is that there is no pinned version to upgrade from or roll back to. If you deploy this, your upgrade path is `git pull` against `main`, which means every change the author pushes is a change you might absorb. The README does describe `/setup` as re-runnable, which helps: if you skipped Telegram or the web UI the first time, running `/setup` again is the documented way to add them. It does not describe a migration path for the data directory. For the Docker route, state lives in the `sb-data` volume, and the README does not say what happens to that volume across image rebuilds. Before you put anything you care about into it, decide where that volume is backed up, because the documentation does not answer the question for you.
Who Should Install It, and What to Check on Day One
Install it if you are a Python-comfortable individual who wants a local assistant with file access, a scheduler, and a phone interface, and you are willing to run a REPL and manage a venv. The two-minute app install and the `/setup` wizard are the intended path, and the README's own advice is to start there rather than with Docker. Skip it if you need multi-user isolation, a versioned release channel, or a documented sandbox contract before running untrusted plugins. On day one, verify four things in this order. Confirm `python --version` reports 3.11 or higher before you create the venv. Run `/setup` and confirm the `essentials` bundle installs on your platform, since that is where the shell and SQL tools come from. Install `bundle_knowledgebase` via `/packages install` and check that OCR and transcription actually work on one PDF and one audio file, because those are the parts most likely to need system-level dependencies that `requirements.txt` does not cover. Finally, point the agent at a scratch directory before you point it at your real documents, and watch what a file edit does. The README does not document a write-confirmation step, and that is the single behaviour worth confirming by hand before this touches anything you would miss.
Editorial conclusion
Adopt Second Brain if you want an agent that reads and edits files on the machine you already own, and you are comfortable running a Python REPL, a venv, and a bot token you created yourself. Do not adopt it if you need a hosted, multi-tenant service with a published API stability contract, or if you cannot give an LLM process write access to a directory you care about. Verify first: that your Python is 3.11 or newer, that the `essentials` bundle installs cleanly on your platform, and that the Telegram bot token and user ID are scoped to the account you intend. Then read `docs/DOCKER.md` before deciding between the venv path and the `sb-data` volume.
Community notes