undefined-ui/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

---

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 Co