AI Second Brain: a knowledge base an agent files, links and maintains for you
An AI second brain that maintains itself. Full guide, starter vault, agent skills and scripts for a self-organizing knowledge base in Claude Code and Obsidian.
At a glance
- What is it?
- second-brain-os is a guide, a starter vault, 18 agent skills, 72 slash commands and 6 subagents for building a self-organising knowledge base in plain markdown on top of Obsidian and Claude Code. The design is that raw material is an archive you never read while the wiki is the artefact, and new sources update existing pages rather than piling up beside them.
- Who is it for?
- second-brain-os suits someone who already saves a lot of material and never processes it, and who is willing to spend an evening setting up a vault and then trust an agent with the filing. It is the wrong choice if you want a knowledge base you curate yourself, because the whole premise is that the filing is the part humans stop doing, and a poor fit if you cannot have your notes in plain markdown, since the vault is a directory of files you own rather than a hosted product.
- 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 9 days ago.
- What is it written in?
- Mainly HTML, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 23, 2026, and from our analysis. They are not legal advice.
Editorial analysis
The problem, stated more bluntly than most tools state their problem
The README opens with the observation that is the whole justification. You save things with the intention of coming back, and you never do. Bookmarks, screenshots, read-later queues and half-filled Notion pages accumulate without compounding, because filing and linking them is boring work that humans stop doing after two weeks. The proposed answer is a single sentence. Hand that work to an agent and the system stays alive. That is the whole idea, and everything in the repository is either the guide for doing it or the machinery for it. The repository is the full version of the guide, with the concepts, the setup, the vault template, the agent skills, the scripts and the resources, and the project description says it is an AI second brain that maintains itself. The licence is MIT and the last push to the repository was on 2026-10-14.
Three entrances, and the difference between a path and a reference
The repository holds three things and the README is explicit about how they differ, which is a good sign for a guide of this kind. The second-brain guide is a path you follow once, to build a knowledge base an agent maintains for you, and it is described as 65 pages with a starter vault and 18 skills. The agents course is a path you read in order, seven modules from a single prompt to a production agent, with tools you install in two commands. The handbooks are not a path but references, the full menu of techniques, tools and builds for one layer, and the instruction is to open one when that layer starts hurting. The distinction between a curriculum and a reference is what separates a guide people finish from a pile of documentation, and the handbooks as a lookup layer is what keeps the main path short enough to be finished.
The pipeline diagram, and the two layers underneath it
The How it works section draws the whole architecture as a diagram, and it is worth reading slowly because every arrow is a design decision. You clip, save or dump into raw/, which holds articles, transcripts, PDFs and chat exports. The agent then ingests, extracts, links and lints that material, and writes into wiki/, which holds sources, concepts, entities and synthesis. From there you can ask anything. The principle stated underneath is that raw material is an archive you never read, while the wiki is the artefact, written in plain language, one idea per page, densely linked. New sources update existing pages instead of piling up beside them, which is the stated reason the vault gets better as it grows rather than just bigger. Alongside the wiki sits a project layer, one folder per project, each with its own CLAUDE.md and an Inputs, Process, Outputs, Feedback pipeline.
The quickstart, which is a copy of five directories and one command
The setup is described as one evening and nine steps. The mechanical part is a clone, five copies and a cleanup, because the vault template, the skills, the commands and the agents each go into a different place. The scripts directory is copied into the vault so that the /metrics, /health and /graph-export commands can run the vault_stats.py script and its companions from inside the vault. The folder READMEs are for a human reading on GitHub, so they are removed after copying, since the agent does not need them. Then you change into the vault and start claude. The nine steps that follow are the ones with documentation behind them: install Obsidian and open the folder as a vault, set up Claude Code in the terminal or the Code tab of the desktop app, connect over MCP if you want the agent to reach the vault from anywhere, which is optional and skippable on day one, get interviewed for your CLAUDE.md instead of writing it by hand, set up the two layers, scope down to one project, install the Web Clipper and clip an article to raw/ and run /ingest, connect live data such as calendar, email and chat, and put maintenance on a schedule so you wake up to a vault that filed itself.
git clone https://github.com/undefined-ui/second-brain-os.git
cp -r second-brain-os/vault-template ~/brain
mkdir -p ~/brain/.claude
cp -r second-brain-os/skills ~/brain/.claude/skills
cp -r second-brain-os/commands ~/brain/.claude/commands
cp -r second-brain-os/agents ~/brain/.claude/agents
cp -r second-brain-os/scripts ~/brain/scripts
rm ~/brain/.claude/*/README.md ~/brain/scripts/README.md
cd ~/brain && claudeWhat is actually in the repository, folder by folder
The What is in here table is the inventory. The docs/ directory holds the guide across ten sections from the concept to troubleshooting, the docs/course-* directories hold the seven module agents course, and the docs/track-* directories hold five handbooks on the wider craft, covering graphs, Jev, harnesses, loops and evals. The vault-template/ directory is the starter vault with the wiki structure, the project pipeline, a CLAUDE.md and page templates. The skills/ directory holds 18 agent skills, one per workflow in the guide, and commands/ holds 72 slash commands described as scoped entry points into those skills. The agents/ directory holds 6 subagents, four of them read-only by design, which is a sensible default for a system that writes to your notes. The plugins/ directory holds Claude Code plugins, the course tools installable in two commands, and scripts/ holds dependency-free Python for link checking, stats and graph export. There is also a resources/ directory of tools, repos, papers and reading, and an examples/ directory of real vaults and real output.
The guide sections, and what each one is for
The guide is ten sections and 77 pages, and the README is clear that it is written to be followed rather than skimmed. The concepts section covers what the pattern is and why the old note systems died. Setup covers Obsidian, Claude Code, the CLAUDE.md file, MCP, projects and git. Ingestion covers articles, video, PDFs, chat exports, voice and backfilling. Structuring covers page types, linking rules, schema and contradictions, which is the part that decides whether a vault stays navigable or becomes a pile. Graphs covers what the graph is for. The remaining sections cover automation, retrieval, publishing, and what to do when each of them breaks. The troubleshooting section existing at all is a reasonable sign that the author expected the system to fail in known ways.
The publication: a static site, a CNAME and a searchable resources page
The README points to the guide on the web at secondbrainos.dev, described as the full guide with search and navigation, plus every vetted link in one filterable page at the resources page. The repository top level shows how that site is built. There is an index.html and a tree.html, a CNAME file for the custom domain, a resources.html generated alongside a resources/ directory of source material, an assets/ directory, a .gitattributes file, and a docs/ directory that is both the source of the guide and the content of the site. The primary language is recorded as HTML, which is consistent with the site being a static build of the markdown. The tools/ directory alongside the rest suggests the site and the vault are generated from the same content rather than maintained separately.
Where the project stands and what a reader should take from it
There are no GitHub releases, and the last push was on 2026-10-14 with the repository not archived, so the repository is a moving target rather than a versioned artefact. The topic list is the honest description of what this is: agent-skills, ai-agents, claude, claude-code, knowledge-graph, knowledge-management, mcp, obsidian, personal-knowledge-base and pkm, plus llm and second-brain. The design decision most likely to decide whether the approach works for you is the separation of the two layers, with the wiki holding what you know and the projects holding what you are doing, feeding each other. The README argues that keeping them apart matters more than it sounds, and that is the part of the guide worth reading before the setup steps, because if the separation is wrong the rest of the machinery will still run and the result will still be a filing cabinet.
Editorial conclusion
second-brain-os suits someone who already saves a lot of material and never processes it, and who is willing to spend an evening setting up a vault and then trust an agent with the filing. It is the wrong choice if you want a knowledge base you curate yourself, because the whole premise is that the filing is the part humans stop doing, and a poor fit if you cannot have your notes in plain markdown, since the vault is a directory of files you own rather than a hosted product. Before you start, read the quickstart in order, because the setup depends on Obsidian being pointed at the vault folder and on the skills and commands being copied into the .claude directory before the agent can use them, and note the Windows caveat that python3 usually resolves to the Microsoft Store stub.
Frequently asked questions
What is the AI Second Brain repository?
It is the full version of a guide for building a knowledge base that an AI agent builds and maintains for you in plain markdown files you own, together with a starter vault, 18 agent skills, 72 slash commands, 6 subagents, plugins and dependency-free Python scripts. The licence is MIT and it runs on Obsidian with Claude Code.
How do I install the second brain setup?
Clone the repository, copy the vault-template to a folder of your choice, then copy the skills, commands, agents and scripts directories into the .claude directory and the vault, remove the folder READMEs which are for reading on GitHub rather than for the agent, and start claude in the vault. On Windows, use python where the guide says python3, since the python3 name usually resolves to the Microsoft Store stub.
What is the difference between the wiki layer and the project layer?
The wiki holds what you know, as plain language pages with one idea each, densely linked, and new sources update existing pages rather than piling up beside them. The projects layer holds what you are doing, one folder per project with its own CLAUDE.md and an Inputs, Process, Outputs, Feedback pipeline. The guide argues that keeping the two separate matters more than it sounds.
What comes with the second brain guide?
The docs directory holds the guide across ten sections and 77 pages, from concepts and setup through ingestion, structuring and graphs to automation, retrieval, publishing and troubleshooting. Alongside it are a seven module agents course, five handbooks on graphs, Jev, harnesses, loops and evals, a vault template, 18 skills, 72 slash commands, 6 subagents of which four are read-only by design, plugins installable in two commands, and Python scripts for link checking, stats and graph export.
Does the second brain setup need MCP or a server?
Not on day one. Connecting over MCP so the agent can reach the vault from anywhere is listed as an optional step you can skip, and the README describes the quickstart as one evening with nine steps. The only runtime requirements are Obsidian and an agent, with nothing to install beyond that.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/undefined-ui-second-brain-os)Was this useful?