second-brain-os

Second Brain OS

Guides and resources for AI engineers: a course on building agents, five handbooks that go deep on one layer each, hands-on projects, and the links worth your time.

Read it on the web: secondbrainos.dev puts every page, term and tool from this repo on one interactive map.

Why this repo?

AI engineering moves fast, and the useful parts are scattered across whitepapers, engineering blogs and repos. This collects them into one path you can follow: theory with sources, a build in every module, and a reading list where every entry has a reason to be here. Here you will find:

• The agents course: seven modules from a single prompt to a production agent, covering context, loops, gates, harnesses, evals and production
• Five handbooks that go deep on one layer each: knowledge graphs, gates, harnesses, loops and evals
• A hands-on project: a second brain, a knowledge base an agent builds and maintains for you in plain markdown
• A working toolkit: a Claude Code plugin for the course, plus 18 skills, 72 slash commands and 6 subagents for the project
• 114 vetted resources, and what landed this month, checked at the source
• Plain markdown, MIT licensed. No signup, nothing to install to read it

Table of contents

• Getting started
• New this month
• Learn by level
  • 🟢 Beginner (30 pages)
  • 🟡 Intermediate (47 pages)
  • 🔴 Advanced (53 pages)
• Toolkit
• Resources
• How the second brain works
• Contributing
• License and credit

---

Getting started

1. New to building agents: read What an agent is, then the agents course in order. Seven modules, three lessons each.
2. One layer of your agent is hurting: open its handbook. Graphs, gates, harnesses, loops or evals, and every one ends in a build.
3. Want a project to practise on: build the second brain, a knowledge base an agent maintains for you. The quickstart is below.
4. Staying current: New this month lists what landed recently, each item checked at its source.

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

Then follow the nine Setup pages in order. The scripts/ copy is what lets /metrics, /health and /graph-export run from inside the vault. On Windows, use python where the guide says python3.

---

New this month

What landed in September and October 2026 that changes how you would build any of this. Checked on 1 November 2026, stars from the GitHub API that day. Notes on each are in resources/.

Second brain and memory

• Basic Memory 1.0 - A local MCP server whose graph is plain markdown with wikilinks, and it reads and writes Obsidian vaults · 4.4K, AGPL-3.0
• ai-memory 3.0 - A git-backed wiki of .md files fed by hooks from 20+ agents, now installable as a Claude Code plugin · 14.9K, MIT
• agent-memory - One markdown file per memory under a MEMORY.md index, with a search index you can delete and rebuild · 4.3K, MIT
• Hindsight 1.0 - The database-backed alternative, with knowledge pages it can write out as markdown · 57.7K, MIT
• LLM Wikis From First Principles - A hands-on workshop: three exercises, from a basic raw/ to wiki/ setup to a wiki that learns from queries
• EvalMem - Splits memory failures into not stored, not found and not used; a wiki layer on top gained 2.5 points

Graphs and retrieval

• Follow the Entities - One page per entity, linked to every document that mentions it: more evidence for fewer tokens. The llm-wiki pattern, measured
• Context as Infrastructure - A grep and BM25 harness with no vector index answered 85% of BrowseComp-Plus; compiled wikis saved tokens, not accuracy
• Keep Your Receipts - Record the evidence behind every merge and edge, and deleting a retracted source needs no model calls
• LiteRAG - Graph retrieval without an LLM on every hop: over 100x faster and 99% cheaper than GraphRAG Global and DRIFT
• LightRAG 1.5.7 - Opt-in graph-first ingestion: build the graph with no embedding calls, add vectors later
• Ladybug - The maintained continuation of Kuzu, the embedded Cypher database archived in October 2025 · 1.9K, MIT

Claude Code and skills

• Agent Skills move to the Linux Foundation - Anthropic handed the SKILL.md standard to the Agentic AI Foundation on 22 October, so the skills here are a neutral format now
• Mods - A new plugin part: JS or TS handlers that watch or rewrite tool calls and prompts and draw their own panes
• claude plugin eval - Runs each case with and without your plugin and fails CI below a threshold
• /skill-doctor - What each loaded skill costs in context on every turn, and which ones never fire
• AGENTS.md support - Claude Code reads AGENTS.md when there is no CLAUDE.md, so one file can serve several agents
• When to fold subagents into your main loop - Anthropic's case for one loop with skills over a fleet of subagents, with a migration plan
• Elephant-Goldfish Model - Google's plugin where reviewers with no prior context check a spec; installs in Claude Code, Codex and Antigravity · 9.1K, Apache-2.0

Agent engineering

• Harness² - Google Research tunes the harness, not the weights: prompts, tools and memory edited per task, lessons kept · 21.9K, Apache-2.0
• SoL-Pi - Four add-ons to the Pi harness that keep its score with 45 to 49 per cent less token traffic · 3.6K, MIT
• CliffCompaction - Compaction that only truncates or drops, never summarises a summary; up to 50% cheaper
• The Unreliable Progress Bar - Models misreport their own progress mid-task, so the runtime should own the stop rule
• Building effective agent automations - Bookmarks, a ledger and a spend cap for an agent that runs on a schedule
• Automating eval design and hillclimbing - Keep a change only if the train and the held-out split both improve. Read with Hamel Husain's critique
• Frozen Judges, Moving Agents - A fixed LLM judge errs differently on each agent version, so judge-only scores cannot certify an upgrade
• OpenAI Decisions API - Typed answers instead of text, generally available on 22 October: the course's gate as an API. Compared with Jev and others as cheap judges
• How the Claude Code team does code review - Parallel finders, a voting verifier and a three-round cap took first-round passes from 65% to 78%

---

Learn by level

Every page in the repo, in reading order. The course runs through all three levels, the second-brain project runs from beginner to intermediate, and the handbooks are references for when one layer of your agent starts hurting.

🟢 Beginner

What an agent is and what it actually sees, then a first project: a knowledge base an agent builds for you. No agent experience needed.

The map course module 0

• What an agent is - An application that plans and acts toward a goal, not a model
• Five layers, one system - Context, loop, gate, harness, evals: the system around the model
• Agents or workflows - If you can write the steps down, build a workflow

Context course module 1

• How models read context - Attention, caching and why a bigger window is not free
• The four places - System prompt, tools, history, tail: what goes where
• Context in practice - Audit and restructure a real agent's context

Concepts second brain 01

• What a second brain actually is - One folder of plain text an agent reads, writes and answers from
• The save-for-later paradox - Why saved links never compound, and what has to change
• The LLM wiki pattern - Karpathy's April 2026 gist, the pattern this repo implements
• The two layers - A wiki for what you know, projects for what you are doing
• Why markdown and plain text - Why the file format decides whether the system survives
• Zettelkasten, PARA, evergreen notes - The old methods were mostly right; which parts still apply
• Wiki vs RAG - Why a linked wiki beats a vector database for a personal corpus
• What good looks like - Concrete signs it is working, from week one to month six

Setup second brain 02

• Obsidian and your first vault - The storage half: free, local, plain text, with a graph view
• Claude Code in the vault - Run Claude Code in the vault, in the terminal or the desktop app
• MCP for Obsidian - Give the agent a door into Obsidian over MCP. Optional on day one
• Writing your CLAUDE.md - Get interviewed for the file the agent reads every session
• Vault structure - Lay out the wiki and project layers in one folder tree
• Project scoping - Scope the agent to one project so quality holds as the vault grows
• Live data connectors - Connect calendar, email and chat so the vault sees what changes
• Plugins worth installing - The plugins worth adding, each for one specific problem
• Git, sync and backups - Git, sync and backups that make unattended runs safe

Ingestion second brain 03

• Web articles - Clip articles into raw/ in one click
• YouTube and podcasts - Turn videos and podcasts into transcripts the agent can file
• PDFs, papers and books - Get PDFs, papers and books in without garbled text
• Chat exports - Import your chat history, your richest and most sensitive source
• Voice notes and meetings - Capture voice notes and meetings away from the desk
• Newsletters and email - Automate newsletter capture without flooding the wiki
• Backfilling years of material - Import years of bookmarks and downloads in controlled batches

---

🟡 Intermediate

How an agent loops and decides, and the second brain grown into a graph that maintains itself and answers real questions.

Loop course module 2

• Loops versus workflows - When the model, not your code, should choose the next step
• The four parts of a loop - Goal, an outside checker, a stop rule, a budget
• Loop practice: filter, loop, fall back - Filter first, loop briefly, fall back: the production pattern

The gate course module 3

• Cheap Decisions - Cheap classifiers in front of expensive models
• Gates in Practice - Measuring a gate: how often it is right, and how sure it is
• Gate Practice - Label a few hundred examples and train a baseline first

Structuring second brain 04

• One page, one idea - One idea per page, explained so it stands alone
• The four page types - Source, concept, entity, synthesis: four types, four jobs
• Linking rules - The rules that turn a folder of files into a graph
• Frontmatter schema - The YAML fields that make the vault queryable
• Naming and aliases - Names and aliases, the keys every wikilink resolves by
• Deduplication and merging - Find and merge duplicate pages without breaking links
• Contradictions and supersession - Record disagreements with dates and sources, never overwrite
• index.md and log.md - The catalog the agent reads first and the log that makes runs auditable

Graphs second brain 05

• Graph basics for a knowledge base - Your vault is already a graph: what that means in practice
• Reading the Obsidian graph view - The graph views that actually tell you something
• Typed links - Links that say how two pages relate, and when to type them
• Graph vs embeddings - Why structured links answer what similarity search cannot
• GraphRAG and where it fits - What GraphRAG is and why you probably do not need it yet
• Exporting the graph - Get the graph out of Obsidian to compute on it
• Graph metrics worth tracking - Four numbers, checked monthly, that show whether it works

Agents second brain 06

• Agent roles - Ingestor, linker, reviewer: one job per agent
• Scheduling - Scheduled runs that file, link and report while you sleep
• Subagents and parallel work - Subagents with their own context for parallel reading
• Hooks - Hooks for the rules a prompt instruction will eventually forget
• Skills and slash commands - Skills vs slash commands, and when to use each
• Guardrails - What the agent may touch, and the walls that hold when it is wrong

Retrieval second brain 07

• Asking the vault - Answers grounded in your pages, not the model's memory
• Query patterns - The questions a vault answers better than a search engine
• Search tools - Grep, ripgrep and Obsidian search: almost always enough
• Adding RAG when you need it - The threshold where adding RAG starts to pay
• Context budget - Why reading more pages makes answers worse, and the budget rules

Outputs second brain 08

• Writing from the vault - Write from research that is already done, cited and linked
• Research reports - Reports for questions the vault cannot answer yet
• Publishing and export - Publish the public part of your vault, keep the rest private
• Learning from your own vault - Quizzes and review that turn saved pages into things you know

Maintenance second brain 09

• Linting the vault - Catch broken links, orphans and missing fields before they rot
• Review cadence - Weekly and monthly reviews that keep you in the loop
• Versioning - Every agent change as a diff you can read and revert
• Backups and portability - The backup mistake almost everyone makes
• Privacy - Keep secrets out of pages, prompts and public exports
• Scaling past a thousand pages - What strains past a thousand pages, and what to change

Troubleshooting second brain 10

• The failures everyone hits - The failures everyone hits, usually in capture, with fixes
• The agent writes garbage - Fix pages that are on topic and useless to read
• Broken links and orphans - Repair broken links and orphans after agent renames
• The vault got too big - When answers get slow and vague as the vault grows
• FAQ - MCP, other agents, cost, local models, Notion imports

---

🔴 Advanced

Harden, measure and ship agents, then go deep on one layer at a time. Every handbook ends in a build you can finish in an evening.

Harness course module 4

• The Office - The model is only as good as the office around it
• The Four Rings - Containment, guides, sensors, permissions, built from the outside in
• Harness Practice - Harden a real coding agent, step by step

Evals course module 5

• Two Kinds of Checks - Behavioural checks on traces vs end-to-end grading
• Judges and Golden Sets - LLM judges you can trust and golden sets that include failures
• Evals Practice - A minimal eval suite in one afternoon

Production course module 6

• From Prototype to Production - What changes when other people, or a 3am scheduler, depend on it
• Operating Agents - What it is doing, what it costs, what it could break
• The Day-One Plan - The whole course compressed into one working day

Knowledge graphs handbook T1

• Why Knowledge Graphs - Facts arrive connected; a graph keeps the connections
• GraphRAG - How GraphRAG works and when it earns its cost
• Building Graphs with LLMs - Entity and relation extraction pipelines with LLMs
• Graph Stores - Where the graph should live, from plain text upward
• Tools - The graph tooling landscape, September 2026
• Build: Extract the Graph - Build 1: extract a graph from your vault
• Build: Query It - Build 2: query it
• Build: Put It in the Loop - Build 3: put it in the agent's loop
• Resources - Papers, repos and tools, checked September 2026

Jev engineering handbook T2

• System One Models - Small models that return typed decisions instead of text
• What Jev Is Good For - Tasks that reduce to picking an answer from a schema
• Jev in an Agent Stack - Jev next to an LLM, making the small decisions
• Getting Started With Jev - Access, the API shape and a realistic first project
• Build: a Typed Decision Endpoint - Build 1: a typed decision endpoint
• Build: the Confidence-Gated Router - Build 2: a confidence-gated router
• Build: the Jev Swap - Build 3: swap Jev in behind the same contract
• Jev Resources - Links on Jev and System One models

Agent harnesses handbook T3

• What a Harness Is - Loop, tools, prompts, permissions: everything around the model
• Claude Code as Harness - Claude Code and the Agent SDK as a reference harness
• Context Engineering - What the model sees at each step, and why
• Tools and MCP - Tool design and MCP, where agents quietly fail
• Harness Landscape - The harnesses alive in September 2026, one honest take each
• Build: the Loop - Build 1: an agent loop in about seventy lines of Python
• Build: Permissions and Context - Build 2: permissions and context limits
• Build: Know When to Graduate - Build 3: when to move to a real framework
• Resources - Harness reading, checked September 2026

Loop engineering handbook T4

• What Loop Engineering Is - The control system that runs an agent
• Stop Conditions - Making a loop stop, and not report success it has not earned
• Critics and Verification - Judges that verify the work outside the model
• Context Hygiene - Fresh context for every attempt, and why it works
• Patterns - Five loop shapes and their failure modes
• Build: the Goal Test - Build 1: define done as a script
• Build: the Critic - Build 2: add a critic pass
• Build: the Overnight Loop - Build 3: an overnight loop you can trust by morning
• Resources - Loop engineering reading

Eval engineering handbook T5

• Why Evals - Evals are the tests of AI products
• Designing Evals - From failure modes to test cases
• LLM as Judge - When a model grades, and how to check the grader
• Agent Evals - Evaluating trajectories, not just final answers
• Eval Tooling - Eval platforms, frameworks and CLIs worth knowing
• Build: Read Your Traces - Build 1: from traces to a golden set
• Build: the Suite - Build 2: a runnable suite in one Python file
• Build: the Gate - Build 3: gate every pull request in GitHub Actions
• Eval Resources - A short eval reading list

---

Toolkit

The agents-course plugin each tool does one module's practice page in your repo

claude plugin marketplace add undefined-ui/second-brain-os
claude plugin install agents-course@second-brain-os

• context-audit - Measure the four places, find cache killers and window bloat
• goal-test - Turn a task into a testable done, with the script and a bounded loop
• gate-check - Find the decisions that do not need the big model
• harness-audit - Walk the four rings, state the blast radius, rank the fixes
• evals-bootstrap - Mine real failures into cases and generate the trace checker
• loop-critic - An agent that reviews loop results in a clean context

Skills second brain, one per workflow

• second-brain-ingest - Turn raw sources into linked wiki pages
• second-brain-backfill - Import a large archive in checkpointed batches
• second-brain-chat-import - Triage an exported chat history, privacy pass first
• second-brain-transcript - Clean a raw transcript before it is ingested
• second-brain-lint - Find and repair broken links, orphans, stubs and bad frontmatter
• second-brain-merge - Merge duplicate pages, keep every claim, redirect the links
• second-brain-rename - Rename a page and fix every inbound link
• second-brain-graph - Report the graph's shape: orphans, hubs, bridges, clusters
• second-brain-metrics - Dated health snapshots so trends are visible
• second-brain-query - Answer from the vault's own pages, with citations
• second-brain-changed-my-mind - Trace where your recorded position has shifted
• second-brain-report - Research reports with gaps, citations and disagreements
• second-brain-write - Draft from your concept pages, citations kept
• second-brain-quiz - Find out what you saved but never learned
• second-brain-review - The periodic review: what grew, what conflicts, what is open
• second-brain-project - Set up a project pipeline with its own CLAUDE.md
• second-brain-publish - Check what would leak before anything is published
• second-brain-privacy - Find credentials and private material in the vault

Subagents second brain, four of them read-only

• ingestor - Processes new material in raw/ into linked wiki pages
• linker - Finds and adds missing connections between existing pages
• researcher - Answers a question that spans many pages and flags what is missing. Read-only
• reviewer - Writes the periodic review of what the vault learned. Read-only
• graph-analyst - Reports graph metrics, hubs, bridges and clusters. Read-only
• curator - Proposes what to prune, archive or merge, never acts. Read-only

Slash commands second brain, 72

Scoped entry points into the skills, in nine groups: ingestion, structuring, graph, retrieval, maintenance, outputs, projects, safety and setup. Start with /ingest, /ask, /lint and /review.

Scripts dependency-free Python

• link_check.py - Broken wikilinks, orphan pages, stubs
• vault_stats.py - Page counts, link density, orphan rate, most-linked pages
• graph_export.py - The wikilink graph as CSV edges or GraphML for Gephi
• chat_export_to_md.py - A chat history export as per-conversation markdown

Starter vault

• vault-template/ - CLAUDE.md with page contracts and linking rules, the raw/ to wiki/ layout, a project pipeline and four page templates

---

Resources

Curated, not comprehensive. The full catalog, filterable, is at secondbrainos.dev/resources.html, with notes on every entry in resources/.

Reading lists by topic

• Agent harnesses - Harness reading, checked September 2026
• Loop engineering - Long-running loops, critics and stop conditions
• Eval engineering - A short eval reading list where everything earns its place
• Knowledge graphs - Papers, repos and tools, checked September 2026
• Jev and System One models - Links on decision models, checked a week after Jev launched

Graph, RAG and memory stars, September 2026

• Graphify - Builds a graph from any folder · 116K
• LightRAG - Graph RAG with incremental updates · 39K
• microsoft/graphrag - The reference GraphRAG implementation · 36K
• nano-graphrag - The same pipeline in readable code · 4.0K
• HippoRAG - Multi-hop retrieval over a knowledge graph · 4.0K
• Awesome-GraphRAG - The landscape in one list · 2.6K
• mem0 - Memory for agents · 65K
• graphiti - Temporal knowledge graphs · 31K
• cognee - Graph plus vector memory · 31K
• awesome-mcp-servers - An index of MCP servers · 95K

Second brain: start here

• Karpathy's llm-wiki gist - The pattern the project builds on, 4 April 2026. Read it first
• From Local to Global: GraphRAG - Why chunk retrieval fails on questions about a whole corpus
• HippoRAG - Graph retrieval with personalised PageRank, the closest analogue of an agent walking links
• Lost in the Middle - The evidence for keeping context small, and the basis for the context budget
• Andy Matuschak's notes - Evergreen notes, and the strongest argument against delegating the writing
• How to Take Smart Notes (Ahrens) and Building a Second Brain (Forte) - Zettelkasten and PARA, the methods an agent now does the upkeep for

Second brain: Obsidian plugins installs, September 2026

• Claudian - An agent in the editor · 2.0M
• Copilot - An agent in the editor · 1.8M
• Smart Connections - Suggests links · 1.2M
• Local REST API with MCP - MCP access to the vault · 712K
• Dataview - Queries over frontmatter · 4.9M
• Templater - Templates · 5.5M
• Git - Version control · 3.1M
• Importer - Migrating in from other apps · 1.6M
• Find unlinked files - Broken links and orphans · 225K
• Spaced Repetition - Flashcards from your notes · 592K
• ExcaliBrain - A structured mind map · 336K
• Juggl - An interactive graph · 136K

Second brain: other implementations stars, September 2026

• AgriciDaniel/claude-obsidian - 16 skills, 3 subagents, role presets · 14.7K
• Astro-Han/karpathy-llm-wiki - 1 skill covering ingest, compile, query and lint · 2.2K
• ballred/obsidian-claude-pkm - 13 skills, 4 subagents, a full starter kit · 1.9K
• coleam00/second-brain-starter - 1 skill that interviews you first · 768
• NicholasSpisak/second-brain - 4 skills with an npm installer · 704
• eugeniughelbur/obsidian-second-brain - 47 commands across three agents
• micuintus/llm-wiki - 1 skill, deliberately minimal
• Where the skill format itself is defined: anthropics/skills, obra/superpowers and the awesome-agent-skills index of 1,000+

Second brain: outside Obsidian

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

---

How the second brain 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: 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. Beside the wiki sits a project layer, one folder per project with its own CLAUDE.md. The wiki holds what you know, the projects hold what you are doing. The two layers covers why keeping them apart matters.

Three rules the project rests on:

• Nothing is ingested until it is linked. A page that lands unconnected is invisible within a week, so linking happens in the same run or the ingest is not finished.
• Contradictions are recorded, never overwritten. 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. Structured pages plus links answer questions chunk similarity cannot, at zero infrastructure cost. When RAG earns its place names the threshold.

---

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.

License and credit

MIT licensed. The agents course builds on Google's agent whitepapers. The second-brain project implements Andrej Karpathy's LLM wiki pattern, published as a gist on 4 April 2026, plus the parts the gist deliberately leaves undefined.