AI Second Brain

A knowledge base that an AI agent builds and maintains for you, in plain
markdown files you own. Everything you read, watch and save gets turned into
linked wiki pages, connected to everything already there, and you can ask it
questions.

This repo is the full version of the guide: the concepts, the setup, the vault
template, the agent skills, the scripts, and the resources. Free, no signup,
nothing to install beyond Obsidian and an agent.

Read it on the web: undefined-ui.github.io/second-brain-os — the full guide with search and navigation, plus every vetted link in one filterable page.

The problem it solves

You save things with the intention of coming back. 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.

Hand that work to an agent and the system stays alive. That is the whole idea.

Quickstart

One evening. Nine steps, each with a full page behind it.

# copy the starter vault, skills, commands and agents
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

# the folder READMEs are for reading on GitHub, not for the agent
rm ~/brain/.claude/*/README.md ~/brain/scripts/README.md

cd ~/brain && claude

The scripts/ copy is what lets /metrics, /health and /graph-export run
scripts/vault_stats.py and friends from inside the vault. On Windows, use
python where this guide says python3: the python3 name usually resolves to
the Microsoft Store stub and does nothing.

1. Install Obsidian and open
   the ~/brain folder you just copied with "Open folder as vault"
2. Set up Claude Code, in the terminal or
   the Code tab of the desktop app
3. Connect over MCP if you want the agent to
   reach the vault from anywhere. Optional, skip it on day one
4. Get interviewed for your CLAUDE.md instead of
   writing it by hand
5. Set up the two layers: a wiki for what
   you know, projects for what you are doing
6. Scope down to one project when you want
   to ship something
7. Install the Web Clipper, clip an article to
   raw/, run /ingest
8. Connect live data: calendar, email, chat
9. Put maintenance on a schedule and
   wake up to a vault that filed itself

Then feed it ten more sources before judging it. The graph is not interesting
at five pages and it is hard to look away from at fifty.

Full walkthrough: Setup.

How it works

   you                    raw/                 agent                 wiki/
 ┌───────┐          ┌──────────────┐      ┌────────────┐      ┌──────────────┐
 │ clip  │  ──────> │ articles     │ ───> │  ingest    │ ───> │ sources/     │
 │ save  │          │ transcripts  │      │  extract   │      │ concepts/    │
 │ dump  │          │ pdfs         │      │  link      │      │ entities/    │
 └───────┘          │ chat exports │      │  lint      │      │ synthesis/   │
                    └──────────────┘      └────────────┘      └──────────────┘
                                                │                     │
                                                │   ask anything      │
                                                └─────────────────────┘

Raw material is an archive you never read. The wiki is the artifact, written in
plain language, one idea per page, densely linked. New sources update existing
pages instead of piling up beside them, which is why 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
wiki holds what you know, the projects hold what you are doing, and they feed
each other. The two layers covers why keeping
them separate matters more than it sounds.

What is in here

The guide

Ten sections, 77 pages, written to be followed rather than skimmed. From the
concept through setup, capture, structure, the graph, automation, retrieval,
publishing, and what to do when each of them breaks.

Compact tracks

Beside the main guide, four compact deep-dives — five or six pages each,
same voice, current as of September 2026:

• Knowledge graphs — GraphRAG, extraction pipelines, stores, and where plain wikilinks are enough (docs/track-graph)
• Jev engineering — building with System One models: typed decisions with confidence scores instead of generated text (docs/track-jev)
• Agent harnesses — the machinery around the model: loops, tools, context engineering, the landscape (docs/track-harness)
• Eval engineering — measurement as the discipline of AI products (docs/track-evals)

Design decisions

This setup is opinionated. The three rules that matter most, and why:

Nothing is ingested until it is linked. A page that lands unconnected is
invisible within a week. Linking is the entire value, so it happens in the same
run or the ingest is not finished.

Contradictions are recorded, never overwritten. When a new source disagrees
with a page, both positions stay, with dates and sources. The history of what
you believed and why is the one thing your vault has that a search engine does
not.

No vector database until you need one. A personal corpus is small and
already structured. Structured pages plus links answer questions that chunk
similarity cannot, at zero infrastructure cost. When RAG earns its
place covers the threshold.

Who this is for

Anyone who reads a lot and retains less than they want to: researchers,
engineers, writers, students, people who watch three hours of technical video a
week and remember none of it.

It is not for team wikis, it is not a Notion replacement, and it will not
organise a vault you never add to.

Portability

Everything here is markdown files, wikilinks and SKILL.md files. It works with
Claude Code, and with any agent that reads files. Obsidian is a viewer for the
graph, not a dependency. If you walk away from every tool named in this repo,
you keep the folder and everything in it.

Learning materials

The source document, and the research behind the design decisions in this guide.

Full notes: reading.md and papers.md.

Tools and plugins

Obsidian plugins ranked by installs from the official community stats, September
2026. The full catalog is in plugins.md and
tools.md.

Outside Obsidian: Web Clipper for capture,
Claude Code for maintenance,
yt-dlp and
OCRmyPDF for processing,
ripgrep,
NetworkX, Kuzu and
Gephi for the graph, and
Quartz to publish.

Skills and other implementations

This repo ships 18 skills, 72 commands, 6 subagents and 4 scripts: one skill
per workflow in the guide, and a command for every scoped version of it you would
actually run.

Other implementations, counted the same way. A repo shipping sixteen skills
counts as sixteen. Stars from the GitHub API, September 2026.

Where the format itself is defined:
anthropics/skills (20 skills),
obra/superpowers (14),
VoltAgent/awesome-agent-skills
(index of 1,000+). Notes on each: skills.md.

Graph, RAG and memory repos

Alternative homes for a vault, from Logseq to AFFiNE, plus RAG frameworks and
AI-native note apps: repositories.md and
tools.md.

Contributing

Corrections, resources and real examples are welcome. Read
CONTRIBUTING.md first: every factual claim needs a primary
source, and tool listings need a reason to exist.

Credit

The LLM wiki pattern is Andrej Karpathy's, published as a
gist on
4 April 2026. This repo is one implementation of it, plus the parts the gist
deliberately leaves undefined.

MIT licensed.