Skip to content
Back to search

second-brain-os

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/undefined-ui--second-brain-os/badge.svg)](/listings/undefined-ui--second-brain-os)

HTML

<a href="/listings/undefined-ui--second-brain-os"><img src="/api/listings/undefined-ui--second-brain-os/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](docs/02-setup/obsidian-install-and-vault.md) and open the `~/brain` folder you just copied with "Open folder as vault" 2. [Set up Claude Code](docs/02-setup/claude-code-setup.md), in the terminal or the Code tab of the desktop app 3. [Connect over MCP](docs/02-setup/mcp-obsidian.md) if you want the agent to reach the vault from anywhere. Optional, skip it on day one 4. [Get interviewed for your CLAUDE.md](docs/02-setup/claude-md.md) instead of writing it by hand 5. [Set up the two layers](docs/02-setup/vault-structure.md): a wiki for what you know, projects for what you are doing 6. [Scope down to one project](docs/02-setup/project-scoping.md) when you want to ship something 7. Install the [Web Clipper](https://obsidian.md/clipper), clip an article to `raw/`, run `/ingest` 8. [Connect live data](docs/02-setup/live-data.md): calendar, email, chat 9. [Put maintenance on a schedule](docs/06-agents/scheduled-maintenance.md) 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](docs/02-setup/README.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "second-brain-os",
  3. "owner": {
  4. "name": "undefinedKi",
  5. "url": "https://x.com/undefinedKi"
  6. },
  7. "description": "Plugins from the Second Brain OS repo and its agents course.",
  8. "plugins": [
  9. {
  10. "name": "agents-course",
  11. "source": "./plugins/agents-course",
  12. "description": "Tools from the agents course: audit your context, write done as a script, bootstrap your eval suite, and a loop critic agent."
  13. }
  14. ]
  15. }
README.md · README · 493 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Second Brain OS
  2. Guides and resources for AI engineers: a course on building agents, five
  3. handbooks that go deep on one layer each, hands-on projects, and the links worth
  4. your time.
  5. **Read it on the web:** [secondbrainos.dev](https://secondbrainos.dev/) puts
  6. every page, term and tool from this repo on one interactive map.
  7. ## Why this repo?
  8. AI engineering moves fast, and the useful parts are scattered across
  9. whitepapers, engineering blogs and repos. This collects them into one path you
  10. can follow: theory with sources, a build in every module, and a reading list
  11. where every entry has a reason to be here. Here you will find:
  12. - **The agents course:** seven modules from a single prompt to a production agent, covering context, loops, gates, harnesses, evals and production
  13. - **Five handbooks** that go deep on one layer each: knowledge graphs, gates, harnesses, loops and evals
  14. - **A hands-on project:** a second brain, a knowledge base an agent builds and maintains for you in plain markdown
  15. - **A working toolkit:** a Claude Code plugin for the course, plus 18 skills, 72 slash commands and 6 subagents for the project
  16. - **114 vetted resources**, and what landed this month, checked at the source
  17. - **Plain markdown, MIT licensed.** No signup, nothing to install to read it
  18. ## Table of contents
  19. - [Getting started](#getting-started)
  20. - [New this month](#new-this-month)
  21. - [Learn by level](#learn-by-level)
  22. - [🟢 Beginner (30 pages)](#-beginner)
  23. - [🟡 Intermediate (47 pages)](#-intermediate)
  24. - [🔴 Advanced (53 pages)](#-advanced)
  25. - [Toolkit](#toolkit)
  26. - [Resources](#resources)
  27. - [How the second brain works](#how-the-second-brain-works)
  28. - [Contributing](#contributing)
  29. - [License and credit](#license-and-credit)
  30. ---
  31. ## Getting started
  32. 1. **New to building agents:** read [What an agent is](docs/course-0-map/what-an-agent-is.md), then the [agents course](docs/README.md#the-agents-course) in order. Seven modules, three lessons each.
  33. 2. **One layer of your agent is hurting:** open its [handbook](#-advanced). Graphs, gates, harnesses, loops or evals, and every one ends in a build.
  34. 3. **Want a project to practise on:** build the [second brain](docs/01-concepts/what-is-a-second-brain.md), a knowledge base an agent maintains for you. The quickstart is below.
  35. 4. **Staying current:** [New this month](#new-this-month) lists what landed recently, each item checked at its source.
  36. <details>
  37. <summary><b>Second brain quickstart</b></summary>
  38. ```bash
  39. # copy the starter vault, skills, commands, agents and scripts
  40. git clone https://github.com/undefined-ui/second-brain-os.git
  41. cp -r second-brain-os/vault-template ~/brain
  42. mkdir -p ~/brain/.claude
  43. cp -r second-brain-os/skills ~/brain/.claude/skills
  44. cp -r second-brain-os/commands ~/brain/.claude/commands
  45. cp -r second-brain-os/agents ~/brain/.claude/agents
  46. cp -r second-brain-os/scripts ~/brain/scripts
  47. # the folder READMEs are for reading on GitHub, not for the agent
  48. rm ~/brain/.claude/*/README.md ~/brain/scripts/README.md
  49. cd ~/brain && claude
  50. ```
  51. Then follow the nine [Setup](docs/02-setup/README.md) pages in order. The
  52. `scripts/` copy is what lets `/metrics`, `/health` and `/graph-export` run from
  53. inside the vault. On Windows, use `python` where the guide says `python3`.
  54. </details>
  55. ---
  56. ## New this month
  57. What landed in September and October 2026 that changes how you would build any
  58. of this. Checked on 1 November 2026, stars from the GitHub API that day. Notes
  59. on each are in [`resources/`](resources/README.md).
  60. #### Second brain and memory
  61. - [**Basic Memory 1.0**](https://github.com/basicmachines-co/basic-memory/releases/tag/v1.0.0) - A local MCP server whose graph is plain markdown with wikilinks, and it reads and writes Obsidian vaults · 4.4K, AGPL-3.0
  62. - [**ai-memory 3.0**](https://github.com/akitaonrails/ai-memory/releases/tag/v3.0.0) - A git-backed wiki of `.md` files fed by hooks from 20+ agents, now installable as a Claude Code plugin · 14.9K, MIT
  63. - [**agent-memory**](https://github.com/tigerless-labs/agent-memory) - One markdown file per memory under a `MEMORY.md` index, with a search index you can delete and rebuild · 4.3K, MIT
  64. - [**Hindsight 1.0**](https://github.com/vectorize-io/hindsight/releases/tag/v1.0.0) - The database-backed alternative, with knowledge pages it can write out as markdown · 57.7K, MIT
  65. - [**LLM Wikis From First Principles**](https://github.com/decodingai-magazine/llm-wiki-workshop) - A hands-on workshop: three exercises, from a basic `raw/` to `wiki/` setup to a wiki that learns from queries
  66. - [**EvalMem**](https://arxiv.org/abs/2609.22231) - Splits memory failures into not stored, not found and not used; a wiki layer on top gained 2.5 points
  67. #### Graphs and retrieval
  68. - [**Follow the Entities**](https://arxiv.org/abs/2609.37226) - One page per entity, linked to every document that mentions it: more evidence for fewer tokens. The llm-wiki pattern, measured
  69. - [**Context as Infrastructure**](https://arxiv.org/abs/2610.41172) - A grep and BM25 harness with no vector index answered 85% of BrowseComp-Plus; compiled wikis saved tokens, not accuracy
  70. - [**Keep Your Receipts**](https://arxiv.org/abs/2610.17719) - Record the evidence behind every merge and edge, and deleting a retracted source needs no model calls
  71. - [**LiteRAG**](https://arxiv.org/abs/2609.10239) - Graph retrieval without an LLM on every hop: over 100x faster and 99% cheaper than GraphRAG Global and DRIFT
  72. - [**LightRAG 1.5.7**](https://github.com/HKUDS/LightRAG/releases/tag/v1.5.7) - Opt-in graph-first ingestion: build the graph with no embedding calls, add vectors later
  73. - [**Ladybug**](https://github.com/LadybugDB/ladybug) - The maintained continuation of Kuzu, the embedded Cypher database archived in October 2025 · 1.9K, MIT
  74. #### Claude Code and skills
  75. - [**Agent Skills move to the Linux Foundation**](https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation) - Anthropic handed the `SKILL.md` standard to the Agentic AI Foundation on 22 October, so the skills here are a neutral format now
  76. - [**Mods**](https://code.claude.com/docs/en/plugins/mods/overview) - A new plugin part: JS or TS handlers that watch or rewrite tool calls and prompts and draw their own panes
  77. - [**claude plugin eval**](https://code.claude.com/docs/en/plugin-evals) - Runs each case with and without your plugin and fails CI below a threshold
  78. - [**/skill-doctor**](https://code.claude.com/docs/en/skills#find-unused-skills) - What each loaded skill costs in context on every turn, and which ones never fire
  79. - [**AGENTS.md support**](https://code.claude.com/docs/en/memory#agents-md) - Claude Code reads `AGENTS.md` when there is no `CLAUDE.md`, so one file can serve several agents
  80. - [**When to fold subagents into your main loop**](https://claude.com/resources/articles/building-agents-when-to-fold-subagents-into-your-main-agent-loop) - Anthropic's case for one loop with skills over a fleet of subagents, with a migration plan
  81. - [**Elephant-Goldfish Model**](https://github.com/google/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
  82. #### Agent engineering
  83. - [**Harness²**](https://github.com/google-research/harness2) - Google Research tunes the harness, not the weights: prompts, tools and memory edited per task, lessons kept · 21.9K, Apache-2.0
  84. - [**SoL-Pi**](https://github.com/NVlabs/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
  85. - [**CliffCompaction**](https://arxiv.org/abs/2609.26779) - Compaction that only truncates or drops, never summarises a summary; up to 50% cheaper
  86. - [**The Unreliable Progress Bar**](https://arxiv.org/abs/2609.08589) - Models misreport their own progress mid-task, so the runtime should own the stop rule
  87. - [**Building effective agent automations**](https://claude.dev/blog/building-effective-agent-automations/) - Bookmarks, a ledger and a spend cap for an agent that runs on a schedule
  88. - [**Automating eval design and hillclimbing**](https://claude.dev/blog/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](https://hamel.dev/blog/posts/claude-auto-evals/)
  89. - [**Frozen Judges, Moving Agents**](https://arxiv.org/abs/2609.34198) - A fixed LLM judge errs differently on each agent version, so judge-only scores cannot certify an upgrade
  90. - [**OpenAI Decisions API**](https://developers.openai.com/api/docs/guides/decisions) - Typed answers instead of text, generally available on 22 October: the course's gate as an API. [Compared with Jev and others](https://hamel.dev/blog/posts/decision-model-evals/) as cheap judges
  91. - [**How the Claude Code team does code review**](https://claude.dev/blog/solving-code-review-at-anthropic/) - Parallel finders, a voting verifier and a three-round cap took first-round passes from 65% to 78%
  92. ---
  93. ## Learn by level
  94. Every page in the repo, in reading order. The course runs through all three
  95. levels, the second-brain project runs from beginner to intermediate, and the
  96. handbooks are references for when one layer of your agent starts hurting.
  97. ### 🟢 Beginner
  98. 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.
  99. #### [The map](docs/course-0-map/README.md) <sub>course module 0</sub>
  100. - [**What an agent is**](docs/course-0-map/what-an-agent-is.md) - An application that plans and acts toward a goal, not a model
  101. - [**Five layers, one system**](docs/course-0-map/five-layers.md) - Context, loop, gate, harness, evals: the system around the model
  102. - [**Agents or workflows**](docs/course-0-map/agents-or-workflows.md) - If you can write the steps down, build a workflow
  103. #### [Context](docs/course-1-context/README.md) <sub>course module 1</sub>
  104. - [**How models read context**](docs/course-1-context/how-models-read.md) - Attention, caching and why a bigger window is not free
  105. - [**The four places**](docs/course-1-context/the-four-places.md) - System prompt, tools, history, tail: what goes where
  106. - [**Context in practice**](docs/course-1-context/context-practice.md) - Audit and restructure a real agent's context
  107. #### [Concepts](docs/01-concepts/README.md) <sub>second brain 01</sub>
  108. - [**What a second brain actually is**](docs/01-concepts/what-is-a-second-brain.md) - One folder of plain text an agent reads, writes and answers from
  109. - [**The save-for-later paradox**](docs/01-concepts/the-save-for-later-paradox.md) - Why saved links never compound, and what has to change
  110. - [**The LLM wiki pattern**](docs/01-concepts/llm-wiki-pattern.md) - Karpathy's April 2026 gist, the pattern this repo implements
  111. - [**The two layers**](docs/01-concepts/two-layers.md) - A wiki for what you know, projects for what you are doing
  112. - [**Why markdown and plain text**](docs/01-concepts/why-markdown-and-plain-text.md) - Why the file format decides whether the system survives
  113. - [**Zettelkasten, PARA, evergreen notes**](docs/01-concepts/pkm-lineage.md) - The old methods were mostly right; which parts still apply
  114. - [**Wiki vs RAG**](docs/01-concepts/wiki-vs-rag.md) - Why a linked wiki beats a vector database for a personal corpus
  115. - [**What good looks like**](docs/01-concepts/what-good-looks-like.md) - Concrete signs it is working, from week one to month six
  116. #### [Setup](docs/02-setup/README.md) <sub>second brain 02</sub>
  117. - [**Obsidian and your first vault**](docs/02-setup/obsidian-install-and-vault.md) - The storage half: free, local, plain text, with a graph view
  118. - [**Claude Code in the vault**](docs/02-setup/claude-code-setup.md) - Run Claude Code in the vault, in the terminal or the desktop app
  119. - [**MCP for Obsidian**](docs/02-setup/mcp-obsidian.md) - Give the agent a door into Obsidian over MCP. Optional on day one
  120. - [**Writing your CLAUDE.md**](docs/02-setup/claude-md.md) - Get interviewed for the file the agent reads every session
  121. - [**Vault structure**](docs/02-setup/vault-structure.md) - Lay out the wiki and project layers in one folder tree
  122. - [**Project scoping**](docs/02-setup/project-scoping.md) - Scope the agent to one project so quality holds as the vault grows
  123. - [**Live data connectors**](docs/02-setup/live-data.md) - Connect calendar, email and chat so the vault sees what changes
  124. - [**Plugins worth installing**](docs/02-setup/obsidian-plugins.md) - The plugins worth adding, each for one specific problem
  125. - [**Git, sync and backups**](docs/02-setup/git-and-sync.md) - Git, sync and backups that make unattended runs safe
  126. #### [Ingestion](docs/03-ingestion/README.md) <sub>second brain 03</sub>
  127. - [**Web articles**](docs/03-ingestion/web-clipper.md) - Clip articles into raw/ in one click
  128. - [**YouTube and podcasts**](docs/03-ingestion/youtube-transcripts.md) - Turn videos and podcasts into transcripts the agent can file
  129. - [**PDFs, papers and books**](docs/03-ingestion/pdfs-and-books.md) - Get PDFs, papers and books in without garbled text
  130. - [**Chat exports**](docs/03-ingestion/chat-exports.md) - Import your chat history, your richest and most sensitive source
  131. - [**Voice notes and meetings**](docs/03-ingestion/voice-and-meetings.md) - Capture voice notes and meetings away from the desk
  132. - [**Newsletters and email**](docs/03-ingestion/newsletters-and-email.md) - Automate newsletter capture without flooding the wiki
  133. - [**Backfilling years of material**](docs/03-ingestion/bulk-backfill.md) - Import years of bookmarks and downloads in controlled batches
  134. ---
  135. ### 🟡 Intermediate
  136. How an agent loops and decides, and the second brain grown into a graph that maintains itself and answers real questions.
  137. #### [Loop](docs/course-2-loop/README.md) <sub>course module 2</sub>
  138. - [**Loops versus workflows**](docs/course-2-loop/loops-vs-workflows.md) - When the model, not your code, should choose the next step
  139. - [**The four parts of a loop**](docs/course-2-loop/the-four-parts.md) - Goal, an outside checker, a stop rule, a budget
  140. - [**Loop practice: filter, loop, fall back**](docs/course-2-loop/loop-practice.md) - Filter first, loop briefly, fall back: the production pattern
  141. #### [The gate](docs/course-3-gate/README.md) <sub>course module 3</sub>
  142. - [**Cheap Decisions**](docs/course-3-gate/cheap-decisions.md) - Cheap classifiers in front of expensive models
  143. - [**Gates in Practice**](docs/course-3-gate/gates-in-practice.md) - Measuring a gate: how often it is right, and how sure it is
  144. - [**Gate Practice**](docs/course-3-gate/gate-practice.md) - Label a few hundred examples and train a baseline first
  145. #### [Structuring](docs/04-structuring/README.md) <sub>second brain 04</sub>
  146. - [**One page, one idea**](docs/04-structuring/atomic-pages.md) - One idea per page, explained so it stands alone
  147. - [**The four page types**](docs/04-structuring/page-types.md) - Source, concept, entity, synthesis: four types, four jobs
  148. - [**Linking rules**](docs/04-structuring/linking-rules.md) - The rules that turn a folder of files into a graph
  149. - [**Frontmatter schema**](docs/04-structuring/frontmatter-schema.md) - The YAML fields that make the vault queryable
  150. - [**Naming and aliases**](docs/04-structuring/naming-and-aliases.md) - Names and aliases, the keys every wikilink resolves by
  151. - [**Deduplication and merging**](docs/04-structuring/dedupe-and-merge.md) - Find and merge duplicate pages without breaking links
  152. - [**Contradictions and supersession**](docs/04-structuring/contradictions-and-supersession.md) - Record disagreements with dates and sources, never overwrite
  153. - [**index.md and log.md**](docs/04-structuring/index-and-log.md) - The catalog the agent reads first and the log that makes runs auditable
  154. #### [Graphs](docs/05-graphs/README.md) <sub>second brain 05</sub>
  155. - [**Graph basics for a knowledge base**](docs/05-graphs/graph-basics.md) - Your vault is already a graph: what that means in practice
  156. - [**Reading the Obsidian graph view**](docs/05-graphs/obsidian-graph-view.md) - The graph views that actually tell you something
  157. - [**Typed links**](docs/05-graphs/typed-links.md) - Links that say how two pages relate, and when to type them
  158. - [**Graph vs embeddings**](docs/05-graphs/graph-vs-vectors.md) - Why structured links answer what similarity search cannot
  159. - [**GraphRAG and where it fits**](docs/05-graphs/graphrag.md) - What GraphRAG is and why you probably do not need it yet
  160. - [**Exporting the graph**](docs/05-graphs/exporting-your-graph.md) - Get the graph out of Obsidian to compute on it
  161. - [**Graph metrics worth tracking**](docs/05-graphs/metrics.md) - Four numbers, checked monthly, that show whether it works
  162. #### [Agents](docs/06-agents/README.md) <sub>second brain 06</sub>
  163. - [**Agent roles**](docs/06-agents/agent-roles.md) - Ingestor, linker, reviewer: one job per agent
  164. - [**Scheduling**](docs/06-agents/scheduled-maintenance.md) - Scheduled runs that file, link and report while you sleep
  165. - [**Subagents and parallel work**](docs/06-agents/subagents.md) - Subagents with their own context for parallel reading
  166. - [**Hooks**](docs/06-agents/hooks.md) - Hooks for the rules a prompt instruction will eventually forget
  167. - [**Skills and slash commands**](docs/06-agents/skills-and-commands.md) - Skills vs slash commands, and when to use each
  168. - [**Guardrails**](docs/06-agents/safety-and-guardrails.md) - What the agent may touch, and the walls that hold when it is wrong
  169. #### [Retrieval](docs/07-retrieval/README.md) <sub>second brain 07</sub>
  170. - [**Asking the vault**](docs/07-retrieval/asking-questions.md) - Answers grounded in your pages, not the model's memory
  171. - [**Query patterns**](docs/07-retrieval/query-patterns.md) - The questions a vault answers better than a search engine
  172. - [**Search tools**](docs/07-retrieval/search-tools.md) - Grep, ripgrep and Obsidian search: almost always enough
  173. - [**Adding RAG when you need it**](docs/07-retrieval/rag-on-top.md) - The threshold where adding RAG starts to pay
  174. - [**Context budget**](docs/07-retrieval/context-budget.md) - Why reading more pages makes answers worse, and the budget rules
  175. #### [Outputs](docs/08-outputs/README.md) <sub>second brain 08</sub>
  176. - [**Writing from the vault**](docs/08-outputs/writing-from-the-vault.md) - Write from research that is already done, cited and linked
  177. - [**Research reports**](docs/08-outputs/research-reports.md) - Reports for questions the vault cannot answer yet
  178. - [**Publishing and export**](docs/08-outputs/publishing-and-export.md) - Publish the public part of your vault, keep the rest private
  179. - [**Learning from your own vault**](docs/08-outputs/teaching-yourself.md) - Quizzes and review that turn saved pages into things you know
  180. #### [Maintenance](docs/09-maintenance/README.md) <sub>second brain 09</sub>
  181. - [**Linting the vault**](docs/09-maintenance/lint-and-health.md) - Catch broken links, orphans and missing fields before they rot
  182. - [**Review cadence**](docs/09-maintenance/review-cadence.md) - Weekly and monthly reviews that keep you in the loop
  183. - [**Versioning**](docs/09-maintenance/versioning-with-git.md) - Every agent change as a diff you can read and revert
  184. - [**Backups and portability**](docs/09-maintenance/backups-and-portability.md) - The backup mistake almost everyone makes
  185. - [**Privacy**](docs/09-maintenance/privacy-and-secrets.md) - Keep secrets out of pages, prompts and public exports
  186. - [**Scaling past a thousand pages**](docs/09-maintenance/scaling.md) - What strains past a thousand pages, and what to change
  187. #### [Troubleshooting](docs/10-troubleshooting/README.md) <sub>second brain 10</sub>
  188. - [**The failures everyone hits**](docs/10-troubleshooting/common-failures.md) - The failures everyone hits, usually in capture, with fixes
  189. - [**The agent writes garbage**](docs/10-troubleshooting/agent-writes-garbage.md) - Fix pages that are on topic and useless to read
  190. - [**Broken links and orphans**](docs/10-troubleshooting/broken-links.md) - Repair broken links and orphans after agent renames
  191. - [**The vault got too big**](docs/10-troubleshooting/vault-too-big.md) - When answers get slow and vague as the vault grows
  192. - [**FAQ**](docs/10-troubleshooting/faq.md) - MCP, other agents, cost, local models, Notion imports
  193. ---
  194. ### 🔴 Advanced
  195. 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.
  196. #### [Harness](docs/course-4-harness/README.md) <sub>course module 4</sub>
  197. - [**The Office**](docs/course-4-harness/the-office.md) - The model is only as good as the office around it
  198. - [**The Four Rings**](docs/course-4-harness/the-four-rings.md) - Containment, guides, sensors, permissions, built from the outside in
  199. - [**Harness Practice**](docs/course-4-harness/harness-practice.md) - Harden a real coding agent, step by step
  200. #### [Evals](docs/course-5-evals/README.md) <sub>course module 5</sub>
  201. - [**Two Kinds of Checks**](docs/course-5-evals/two-kinds-of-checks.md) - Behavioural checks on traces vs end-to-end grading
  202. - [**Judges and Golden Sets**](docs/course-5-evals/judges-and-golden-sets.md) - LLM judges you can trust and golden sets that include failures
  203. - [**Evals Practice**](docs/course-5-evals/evals-practice.md) - A minimal eval suite in one afternoon
  204. #### [Production](docs/course-6-production/README.md) <sub>course module 6</sub>
  205. - [**From Prototype to Production**](docs/course-6-production/from-prototype.md) - What changes when other people, or a 3am scheduler, depend on it
  206. - [**Operating Agents**](docs/course-6-production/operating-agents.md) - What it is doing, what it costs, what it could break
  207. - [**The Day-One Plan**](docs/course-6-production/day-one-plan.md) - The whole course compressed into one working day
  208. #### [Knowledge graphs](docs/track-graph/README.md) <sub>handbook T1</sub>
  209. - [**Why Knowledge Graphs**](docs/track-graph/why-graphs.md) - Facts arrive connected; a graph keeps the connections
  210. - [**GraphRAG**](docs/track-graph/graphrag.md) - How GraphRAG works and when it earns its cost
  211. - [**Building Graphs with LLMs**](docs/track-graph/building-graphs-with-llms.md) - Entity and relation extraction pipelines with LLMs
  212. - [**Graph Stores**](docs/track-graph/graph-stores.md) - Where the graph should live, from plain text upward
  213. - [**Tools**](docs/track-graph/tools.md) - The graph tooling landscape, September 2026
  214. - [**Build: Extract the Graph**](docs/track-graph/build-extract.md) - Build 1: extract a graph from your vault
  215. - [**Build: Query It**](docs/track-graph/build-query.md) - Build 2: query it
  216. - [**Build: Put It in the Loop**](docs/track-graph/build-use.md) - Build 3: put it in the agent's loop
  217. - [**Resources**](docs/track-graph/resources.md) - Papers, repos and tools, checked September 2026
  218. #### [Jev engineering](docs/track-jev/README.md) <sub>handbook T2</sub>
  219. - [**System One Models**](docs/track-jev/system-one-models.md) - Small models that return typed decisions instead of text
  220. - [**What Jev Is Good For**](docs/track-jev/what-jev-is-good-for.md) - Tasks that reduce to picking an answer from a schema
  221. - [**Jev in an Agent Stack**](docs/track-jev/jev-in-an-agent-stack.md) - Jev next to an LLM, making the small decisions
  222. - [**Getting Started With Jev**](docs/track-jev/getting-started.md) - Access, the API shape and a realistic first project
  223. - [**Build: a Typed Decision Endpoint**](docs/track-jev/build-decision-endpoint.md) - Build 1: a typed decision endpoint
  224. - [**Build: the Confidence-Gated Router**](docs/track-jev/build-router.md) - Build 2: a confidence-gated router
  225. - [**Build: the Jev Swap**](docs/track-jev/build-swap-in-jev.md) - Build 3: swap Jev in behind the same contract
  226. - [**Jev Resources**](docs/track-jev/resources.md) - Links on Jev and System One models
  227. #### [Agent harnesses](docs/track-harness/README.md) <sub>handbook T3</sub>
  228. - [**What a Harness Is**](docs/track-harness/what-a-harness-is.md) - Loop, tools, prompts, permissions: everything around the model
  229. - [**Claude Code as Harness**](docs/track-harness/claude-code-as-harness.md) - Claude Code and the Agent SDK as a reference harness
  230. - [**Context Engineering**](docs/track-harness/context-engineering.md) - What the model sees at each step, and why
  231. - [**Tools and MCP**](docs/track-harness/tools-and-mcp.md) - Tool design and MCP, where agents quietly fail
  232. - [**Harness Landscape**](docs/track-harness/harness-landscape.md) - The harnesses alive in September 2026, one honest take each
  233. - [**Build: the Loop**](docs/track-harness/build-the-loop.md) - Build 1: an agent loop in about seventy lines of Python
  234. - [**Build: Permissions and Context**](docs/track-harness/build-guardrails.md) - Build 2: permissions and context limits
  235. - [**Build: Know When to Graduate**](docs/track-harness/build-graduate.md) - Build 3: when to move to a real framework
  236. - [**Resources**](docs/track-harness/resources.md) - Harness reading, checked September 2026
  237. #### [Loop engineering](docs/track-loop/README.md) <sub>handbook T4</sub>
  238. - [**What Loop Engineering Is**](docs/track-loop/what-loop-engineering-is.md) - The control system that runs an agent
  239. - [**Stop Conditions**](docs/track-loop/stop-conditions.md) - Making a loop stop, and not report success it has not earned
  240. - [**Critics and Verification**](docs/track-loop/critics-and-verification.md) - Judges that verify the work outside the model
  241. - [**Context Hygiene**](docs/track-loop/context-hygiene.md) - Fresh context for every attempt, and why it works
  242. - [**Patterns**](docs/track-loop/patterns.md) - Five loop shapes and their failure modes
  243. - [**Build: the Goal Test**](docs/track-loop/build-goal-test.md) - Build 1: define done as a script
  244. - [**Build: the Critic**](docs/track-loop/build-critic.md) - Build 2: add a critic pass
  245. - [**Build: the Overnight Loop**](docs/track-loop/build-overnight.md) - Build 3: an overnight loop you can trust by morning
  246. - [**Resources**](docs/track-loop/resources.md) - Loop engineering reading
  247. #### [Eval engineering](docs/track-evals/README.md) <sub>handbook T5</sub>
  248. - [**Why Evals**](docs/track-evals/why-evals.md) - Evals are the tests of AI products
  249. - [**Designing Evals**](docs/track-evals/designing-evals.md) - From failure modes to test cases
  250. - [**LLM as Judge**](docs/track-evals/llm-as-judge.md) - When a model grades, and how to check the grader
  251. - [**Agent Evals**](docs/track-evals/agent-evals.md) - Evaluating trajectories, not just final answers
  252. - [**Eval Tooling**](docs/track-evals/tooling.md) - Eval platforms, frameworks and CLIs worth knowing
  253. - [**Build: Read Your Traces**](docs/track-evals/build-traces.md) - Build 1: from traces to a golden set
  254. - [**Build: the Suite**](docs/track-evals/build-suite.md) - Build 2: a runnable suite in one Python file
  255. - [**Build: the Gate**](docs/track-evals/build-ci.md) - Build 3: gate every pull request in GitHub Actions
  256. - [**Eval Resources**](docs/track-evals/resources.md) - A short eval reading list
  257. ---
  258. ## Toolkit
  259. #### [The agents-course plugin](plugins/README.md) <sub>each tool does one module's practice page in your repo</sub>
  260. ```bash
  261. claude plugin marketplace add undefined-ui/second-brain-os
  262. claude plugin install agents-course@second-brain-os
  263. ```
  264. - [**context-audit**](plugins/agents-course/skills/context-audit/SKILL.md) - Measure the four places, find cache killers and window bloat
  265. - [**goal-test**](plugins/agents-course/skills/goal-test/SKILL.md) - Turn a task into a testable done, with the script and a bounded loop
  266. - [**gate-check**](plugins/agents-course/skills/gate-check/SKILL.md) - Find the decisions that do not need the big model
  267. - [**harness-audit**](plugins/agents-course/skills/harness-audit/SKILL.md) - Walk the four rings, state the blast radius, rank the fixes
  268. - [**evals-bootstrap**](plugins/agents-course/skills/evals-bootstrap/SKILL.md) - Mine real failures into cases and generate the trace checker
  269. - [**loop-critic**](plugins/agents-course/agents/loop-critic.md) - An agent that reviews loop results in a clean context
  270. #### [Skills](skills/README.md) <sub>second brain, one per workflow</sub>
  271. - [**second-brain-ingest**](skills/second-brain-ingest/SKILL.md) - Turn raw sources into linked wiki pages
  272. - [**second-brain-backfill**](skills/second-brain-backfill/SKILL.md) - Import a large archive in checkpointed batches
  273. - [**second-brain-chat-import**](skills/second-brain-chat-import/SKILL.md) - Triage an exported chat history, privacy pass first
  274. - [**second-brain-transcript**](skills/second-brain-transcript/SKILL.md) - Clean a raw transcript before it is ingested
  275. - [**second-brain-lint**](skills/second-brain-lint/SKILL.md) - Find and repair broken links, orphans, stubs and bad frontmatter
  276. - [**second-brain-merge**](skills/second-brain-merge/SKILL.md) - Merge duplicate pages, keep every claim, redirect the links
  277. - [**second-brain-rename**](skills/second-brain-rename/SKILL.md) - Rename a page and fix every inbound link
  278. - [**second-brain-graph**](skills/second-brain-graph/SKILL.md) - Report the graph's shape: orphans, hubs, bridges, clusters
  279. - [**second-brain-metrics**](skills/second-brain-metrics/SKILL.md) - Dated health snapshots so trends are visible
  280. - [**second-brain-query**](skills/second-brain-query/SKILL.md) - Answer from the vault's own pages, with citations
  281. - [**second-brain-changed-my-mind**](skills/second-brain-changed-my-mind/SKILL.md) - Trace where your recorded position has shifted
  282. - [**second-brain-report**](skills/second-brain-report/SKILL.md) - Research reports with gaps, citations and disagreements
  283. - [**second-brain-write**](skills/second-brain-write/SKILL.md) - Draft from your concept pages, citations kept
  284. - [**second-brain-quiz**](skills/second-brain-quiz/SKILL.md) - Find out what you saved but never learned
  285. - [**second-brain-review**](skills/second-brain-review/SKILL.md) - The periodic review: what grew, what conflicts, what is open
  286. - [**second-brain-project**](skills/second-brain-project/SKILL.md) - Set up a project pipeline with its own `CLAUDE.md`
  287. - [**second-brain-publish**](skills/second-brain-publish/SKILL.md) - Check what would leak before anything is published
  288. - [**second-brain-privacy**](skills/second-brain-privacy/SKILL.md) - Find credentials and private material in the vault
  289. #### [Subagents](agents/README.md) <sub>second brain, four of them read-only</sub>
  290. - [**ingestor**](agents/ingestor.md) - Processes new material in `raw/` into linked wiki pages
  291. - [**linker**](agents/linker.md) - Finds and adds missing connections between existing pages
  292. - [**researcher**](agents/researcher.md) - Answers a question that spans many pages and flags what is missing. Read-only
  293. - [**reviewer**](agents/reviewer.md) - Writes the periodic review of what the vault learned. Read-only
  294. - [**graph-analyst**](agents/graph-analyst.md) - Reports graph metrics, hubs, bridges and clusters. Read-only
  295. - [**curator**](agents/curator.md) - Proposes what to prune, archive or merge, never acts. Read-only
  296. #### [Slash commands](commands/README.md) <sub>second brain, 72</sub>
  297. Scoped entry points into the skills, in nine groups: ingestion, structuring,
  298. graph, retrieval, maintenance, outputs, projects, safety and setup. Start with
  299. `/ingest`, `/ask`, `/lint` and `/review`.
  300. #### [Scripts](scripts/README.md) <sub>dependency-free Python</sub>
  301. - [**link_check.py**](scripts/link_check.py) - Broken wikilinks, orphan pages, stubs
  302. - [**vault_stats.py**](scripts/vault_stats.py) - Page counts, link density, orphan rate, most-linked pages
  303. - [**graph_export.py**](scripts/graph_export.py) - The wikilink graph as CSV edges or GraphML for Gephi
  304. - [**chat_export_to_md.py**](scripts/chat_export_to_md.py) - A chat history export as per-conversation markdown
  305. #### [Starter vault](vault-template/)
  306. - [**vault-template/**](vault-template/) - `CLAUDE.md` with page contracts and linking rules, the `raw/` to `wiki/` layout, a project pipeline and four page templates
  307. ---
  308. ## Resources
  309. Curated, not comprehensive. The full catalog, filterable, is at
  310. [secondbrainos.dev/resources.html](https://secondbrainos.dev/resources.html),
  311. with notes on every entry in [`resources/`](resources/README.md).
  312. #### Reading lists by topic
  313. - [**Agent harnesses**](docs/track-harness/resources.md) - Harness reading, checked September 2026
  314. - [**Loop engineering**](docs/track-loop/resources.md) - Long-running loops, critics and stop conditions
  315. - [**Eval engineering**](docs/track-evals/resources.md) - A short eval reading list where everything earns its place
  316. - [**Knowledge graphs**](docs/track-graph/resources.md) - Papers, repos and tools, checked September 2026
  317. - [**Jev and System One models**](docs/track-jev/resources.md) - Links on decision models, checked a week after Jev launched
  318. #### Graph, RAG and memory <sub>stars, September 2026</sub>
  319. - [**Graphify**](https://github.com/Graphify-Labs/graphify) - Builds a graph from any folder · 116K
  320. - [**LightRAG**](https://github.com/HKUDS/LightRAG) - Graph RAG with incremental updates · 39K
  321. - [**microsoft/graphrag**](https://github.com/microsoft/graphrag) - The reference GraphRAG implementation · 36K
  322. - [**nano-graphrag**](https://github.com/gusye1234/nano-graphrag) - The same pipeline in readable code · 4.0K
  323. - [**HippoRAG**](https://github.com/OSU-NLP-Group/HippoRAG) - Multi-hop retrieval over a knowledge graph · 4.0K
  324. - [**Awesome-GraphRAG**](https://github.com/DEEP-PolyU/Awesome-GraphRAG) - The landscape in one list · 2.6K
  325. - [**mem0**](https://github.com/mem0ai/mem0) - Memory for agents · 65K
  326. - [**graphiti**](https://github.com/getzep/graphiti) - Temporal knowledge graphs · 31K
  327. - [**cognee**](https://github.com/topoteretes/cognee) - Graph plus vector memory · 31K
  328. - [**awesome-mcp-servers**](https://github.com/punkpeye/awesome-mcp-servers) - An index of MCP servers · 95K
  329. #### Second brain: start here
  330. - [**Karpathy's llm-wiki gist**](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) - The pattern the project builds on, 4 April 2026. Read it first
  331. - [**From Local to Global: GraphRAG**](https://arxiv.org/abs/2404.16130) - Why chunk retrieval fails on questions about a whole corpus
  332. - [**HippoRAG**](https://arxiv.org/abs/2405.14831) - Graph retrieval with personalised PageRank, the closest analogue of an agent walking links
  333. - [**Lost in the Middle**](https://arxiv.org/abs/2307.03172) - The evidence for keeping context small, and the basis for the [context budget](docs/07-retrieval/context-budget.md)
  334. - [**Andy Matuschak's notes**](https://notes.andymatuschak.org) - Evergreen notes, and the strongest argument against delegating the writing
  335. - **How to Take Smart Notes** (Ahrens) and **Building a Second Brain** (Forte) - Zettelkasten and PARA, the methods an agent now does the upkeep for
  336. #### Second brain: Obsidian plugins <sub>installs, September 2026</sub>
  337. - [**Claudian**](https://github.com/yishentu/claudian) - An agent in the editor · 2.0M
  338. - [**Copilot**](https://github.com/logancyang/obsidian-copilot) - An agent in the editor · 1.8M
  339. - [**Smart Connections**](https://github.com/brianpetro/obsidian-smart-connections) - Suggests links · 1.2M
  340. - [**Local REST API with MCP**](https://github.com/coddingtonbear/obsidian-local-rest-api) - MCP access to the vault · 712K
  341. - [**Dataview**](https://github.com/blacksmithgu/obsidian-dataview) - Queries over frontmatter · 4.9M
  342. - [**Templater**](https://github.com/SilentVoid13/Templater) - Templates · 5.5M
  343. - [**Git**](https://github.com/Vinzent03/obsidian-git) - Version control · 3.1M
  344. - [**Importer**](https://github.com/obsidianmd/obsidian-importer) - Migrating in from other apps · 1.6M
  345. - [**Find unlinked files**](https://github.com/Vinzent03/find-unlinked-files) - Broken links and orphans · 225K
  346. - [**Spaced Repetition**](https://github.com/st3v3nmw/obsidian-spaced-repetition) - Flashcards from your notes · 592K
  347. - [**ExcaliBrain**](https://github.com/zsviczian/excalibrain) - A structured mind map · 336K
  348. - [**Juggl**](https://github.com/HEmile/juggl) - An interactive graph · 136K
  349. #### Second brain: other implementations <sub>stars, September 2026</sub>
  350. - [**AgriciDaniel/claude-obsidian**](https://github.com/AgriciDaniel/claude-obsidian) - 16 skills, 3 subagents, role presets · 14.7K
  351. - [**Astro-Han/karpathy-llm-wiki**](https://github.com/Astro-Han/karpathy-llm-wiki) - 1 skill covering ingest, compile, query and lint · 2.2K
  352. - [**ballred/obsidian-claude-pkm**](https://github.com/ballred/obsidian-claude-pkm) - 13 skills, 4 subagents, a full starter kit · 1.9K
  353. - [**coleam00/second-brain-starter**](https://github.com/coleam00/second-brain-starter) - 1 skill that interviews you first · 768
  354. - [**NicholasSpisak/second-brain**](https://github.com/NicholasSpisak/second-brain) - 4 skills with an npm installer · 704
  355. - [**eugeniughelbur/obsidian-second-brain**](https://github.com/eugeniughelbur/obsidian-second-brain) - 47 commands across three agents
  356. - [**micuintus/llm-wiki**](https://github.com/micuintus/llm-wiki) - 1 skill, deliberately minimal
  357. - Where the skill format itself is defined: [anthropics/skills](https://github.com/anthropics/skills), [obra/superpowers](https://github.com/obra/superpowers) and the [awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills) index of 1,000+
  358. #### Second brain: outside Obsidian
  359. [Web Clipper](https://obsidian.md/clipper) for capture,
  360. [Claude Code](https://code.claude.com/docs/en/setup) for maintenance,
  361. [yt-dlp](https://github.com/yt-dlp/yt-dlp) and
  362. [OCRmyPDF](https://github.com/ocrmypdf/OCRmyPDF) for processing,
  363. [ripgrep](https://github.com/BurntSushi/ripgrep),
  364. [NetworkX](https://networkx.org), [Ladybug](https://github.com/LadybugDB/ladybug) and
  365. [Gephi](https://gephi.org) for the graph, and
  366. [Quartz](https://github.com/jackyzha0/quartz) to publish.
  367. ---
  368. ## How the second brain works
  369. ```
  370. you raw/ agent wiki/
  371. ┌───────┐ ┌──────────────┐ ┌────────────┐ ┌──────────────┐
  372. │ clip │ ──────> │ articles │ ───> │ ingest │ ───> │ sources/ │
  373. │ save │ │ transcripts │ │ extract │ │ concepts/ │
  374. │ dump │ │ pdfs │ │ link │ │ entities/ │
  375. └───────┘ │ chat exports │ │ lint │ │ synthesis/ │
  376. └──────────────┘ └────────────┘ └──────────────┘
  377. │ │
  378. │ ask anything │
  379. └─────────────────────┘
  380. ```
  381. Raw material is an archive you never read. The wiki is the artifact: plain
  382. language, one idea per page, densely linked. New sources update existing pages
  383. instead of piling up beside them, which is why the vault gets better as it
  384. grows rather than just bigger. Beside the wiki sits a project layer, one folder
  385. per project with its own `CLAUDE.md`. The wiki holds what you know, the
  386. projects hold what you are doing. [The two layers](docs/01-concepts/two-layers.md)
  387. covers why keeping them apart matters.
  388. Three rules the project rests on:
  389. - **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.
  390. - **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.
  391. - **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](docs/07-retrieval/rag-on-top.md) names the threshold.
  392. ---
  393. ## Contributing
  394. Corrections, resources and real examples are welcome. Read
  395. [CONTRIBUTING.md](CONTRIBUTING.md) first: every factual claim needs a primary
  396. source, and tool listings need a reason to exist.
  397. ## License and credit
  398. MIT licensed. The agents course builds on Google's agent whitepapers. The
  399. second-brain project implements Andrej Karpathy's LLM wiki pattern, published
  400. as a [gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
  401. on 4 April 2026, plus the parts the gist deliberately leaves undefined.
  402. <!-- TODO before publishing:
  403. - add the link to the original article
  404. - screenshots: graph view at 30 days, an example concept page
  405. - social preview image in Settings -> General -->

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.