Guides and resources for AI engineers: an agents course, five handbooks, a hands-on second-brain project and a vetted reading list.
JavaScript agent-skillsai-agentsai-engineeringclaudeclaude-codeclaude-skillsknowledge-graphknowledge-managementllmmcpobsidianpersonal-knowledge-basepkmsecond-brain
site: guide and resources pages
undefined-ui195686eec3cc
diff --git a/.gitignore b/.gitignoreindex 04c6899..7f6c26d 100644--- a/.gitignore+++ b/.gitignore@@ -7,3 +7,4 @@ __pycache__/node_modules/*.graphml*.csv+site_data.jsondiff --git a/README.md b/README.mdindex f52f833..127ac91 100644--- a/README.md+++ b/README.md@@ -9,6 +9,8 @@ This repo is the full version of the guide: the concepts, the setup, the vaulttemplate, 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](https://undefined-ui.github.io/second-brain-os/) — the full guide with search and navigation, plus [every vetted link](https://undefined-ui.github.io/second-brain-os/resources.html) in one filterable page.+## The problem it solvesYou save things with the intention of coming back. You never do. Bookmarks,diff --git a/index.html b/index.htmlnew file mode 100644index 0000000..95a730c--- /dev/null+++ b/index.html@@ -0,0 +1,297 @@+<!DOCTYPE html><html lang="en"><head>+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">+<title>Second Brain OS - the guide</title>+<meta name="description" content="A 65-page guide to building a knowledge base your AI agent maintains, in plain markdown you own.">+<style>+:root{+ --paper:#EAEEE9; --card:#F7F9F6; --ink:#15201B; --soft:#4B5A52; --faint:#7C8A82;+ --rule:#D2DACF; --accent:#1F6B52; --accent-bg:#E1EDE5; --num:#8A6B23;+ --w:68ch;+}+*{box-sizing:border-box;margin:0;padding:0}+html{scroll-behavior:smooth}+body{background:var(--paper);color:var(--ink);+ font:17px/1.62 Charter,Georgia,"Iowan Old Style",serif;+ -webkit-font-smoothing:antialiased}+.mono{font-family:ui-monospace,SFMono-Regular,Menlo,"DejaVu Sans Mono",monospace}+a{color:var(--accent);text-decoration:none}+a:hover{text-decoration:underline;text-underline-offset:3px}+:focus-visible{outline:2px solid var(--accent);outline-offset:3px;border-radius:2px}++header{position:sticky;top:0;z-index:40;background:rgba(234,238,233,.94);+ backdrop-filter:blur(8px);border-bottom:1px solid var(--rule)}+.bar{max-width:1500px;margin:0 auto;padding:13px 22px;display:flex;gap:20px;align-items:center}+.brand{font:600 15px/1 ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--ink);letter-spacing:-.01em}+.brand span{color:var(--accent)}+nav{display:flex;gap:18px;font-size:14.5px}+nav a{color:var(--soft)} nav a.on{color:var(--ink);font-weight:600}+.search{margin-left:auto;position:relative}+.search input{font:14px/1 ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--ink);+ background:var(--card);border:1px solid var(--rule);border-radius:3px;+ padding:8px 11px;width:210px}+.search input::placeholder{color:var(--faint)}+.hits{position:absolute;right:0;top:40px;width:430px;max-height:62vh;overflow:auto;+ background:var(--card);border:1px solid var(--rule);border-radius:3px;display:none}+.hits.open{display:block}+.hit{display:block;padding:10px 13px;border-bottom:1px solid var(--rule);color:var(--ink)}+.hit:last-child{border:0}+.hit:hover{background:var(--accent-bg);text-decoration:none}+.hit b{font-weight:600;font-size:15px}+.hit i{display:block;font-style:normal;font-size:12.5px;color:var(--faint);+ font-family:ui-monospace,Menlo,monospace;margin-top:2px}++.wrap{max-width:1500px;margin:0 auto;padding:0 22px;display:grid;+ grid-template-columns:266px minmax(0,1fr) 210px;gap:44px;align-items:start}+@media(max-width:1180px){.wrap{grid-template-columns:240px minmax(0,1fr);gap:34px}.rail{display:none}}+.toc-btn{display:none;font:13px/1 ui-monospace,Menlo,monospace;background:var(--card);+ color:var(--ink);border:1px solid var(--rule);border-radius:3px;padding:8px 12px;cursor:pointer}+@media(max-width:860px){+ .bar{flex-wrap:wrap;gap:12px;padding:11px 16px}+ .brand{white-space:nowrap;font-size:14px}+ nav{gap:14px;font-size:14px}+ .toc-btn{display:block;margin-left:auto}+ nav a[href^="http"]{display:none}+ .search{margin-left:0;order:9;width:100%}+ .search input{width:100%}+ .hits{width:100%;left:0;right:auto}+ .wrap{grid-template-columns:1fr;gap:0;padding:0 16px}+ aside{position:static;height:auto;border-right:0;border-bottom:1px solid var(--rule);+ padding:14px 0 18px;display:none}+ aside.show{display:block}+ main{padding:24px 0 70px}+ body{font-size:16.5px}+}++aside{position:sticky;top:57px;height:calc(100vh - 57px);overflow:auto;+ padding:26px 18px 60px 0;border-right:1px solid var(--rule)}+.sec{margin-bottom:3px}+.sec>button{width:100%;text-align:left;background:none;border:0;cursor:pointer;+ font:600 14px/1.4 Charter,Georgia,serif;color:var(--ink);padding:6px 6px 6px 0;+ display:flex;gap:8px;align-items:baseline}+.sec>button .n{font:11px/1 ui-monospace,Menlo,monospace;color:var(--faint);margin-left:auto}+.sec>button .k{font:11px/1 ui-monospace,Menlo,monospace;color:var(--accent);width:20px}+.sec ol{list-style:none;padding:0 0 6px 28px;display:none}+.sec.open ol{display:block}+.sec ol a{display:block;padding:4px 6px 4px 10px;font-size:14px;color:var(--soft);+ border-left:1px solid var(--rule);line-height:1.35}+.sec ol a:hover{color:var(--ink);border-color:var(--accent);text-decoration:none}+.sec ol a.cur{color:var(--ink);font-weight:600;border-left:2px solid var(--accent);+ background:var(--accent-bg)}++main{padding:34px 0 90px;min-width:0}+.rail{position:sticky;top:80px;padding:38px 0;font-size:13px;color:var(--faint)}+.rail h4{font:11px/1 ui-monospace,Menlo,monospace;color:var(--faint);+ letter-spacing:.08em;margin-bottom:9px;font-weight:600}+.rail a{display:block;color:var(--soft);padding:3px 0;font-size:13px;line-height:1.35}+.rail .grp{margin-bottom:24px}++/* hero */+.hero{max-width:var(--w)}+.hero h1{font:600 clamp(34px,4.6vw,52px)/1.05 Charter,Georgia,serif;letter-spacing:-.025em;margin-bottom:14px}+.hero p{font-size:19px;color:var(--soft);margin-bottom:8px}+.figure{margin:30px 0 34px;background:var(--card);border:1px solid var(--rule);border-radius:4px;+ padding:10px 10px 4px;max-width:820px}+.figure figcaption{font:11.5px/1.5 ui-monospace,Menlo,monospace;color:var(--faint);padding:6px 8px 8px}+svg .edge{stroke:var(--accent);fill:none}+svg .node circle{fill:var(--card);stroke:var(--accent);stroke-width:1.5;cursor:pointer;+ transition:fill .15s}+svg .node:hover circle{fill:var(--accent-bg)}+svg .node text{font:12px ui-monospace,Menlo,monospace;fill:var(--ink);cursor:pointer}+svg .node .cnt{font-size:10px;fill:var(--faint)}+svg .node .idx{font-size:11px;fill:var(--accent);font-weight:600}+.stats{display:flex;flex-wrap:wrap;gap:26px;margin:26px 0 34px;padding-top:20px;border-top:1px solid var(--rule)}+.stat b{display:block;font:600 27px/1 Charter,Georgia,serif;color:var(--num)}+.stat span{font:12px/1.4 ui-monospace,Menlo,monospace;color:var(--faint)}+.seclist{max-width:var(--w)}+.seclist article{padding:16px 0;border-top:1px solid var(--rule)}+.seclist h3{font:600 18px/1.3 Charter,Georgia,serif;margin-bottom:3px}+.seclist p{font-size:15px;color:var(--soft)}+.seclist .pg{font:12px ui-monospace,Menlo,monospace;color:var(--faint);margin-top:5px}++/* article */+article.page{max-width:var(--w)}+.crumb{font:12px ui-monospace,Menlo,monospace;color:var(--faint);margin-bottom:10px}+article.page h1{font:600 clamp(28px,3.4vw,38px)/1.12 Charter,Georgia,serif;+ letter-spacing:-.02em;margin-bottom:22px}+article.page h2{font:600 21px/1.3 Charter,Georgia,serif;margin:34px 0 11px;+ padding-top:16px;border-top:1px solid var(--rule)}+article.page h3{font:600 17px/1.3 Charter,Georgia,serif;margin:22px 0 7px}+article.page p{margin-bottom:15px}+article.page ul,article.page ol{margin:0 0 16px 22px}+article.page li{margin-bottom:7px}+article.page blockquote{border-left:2px solid var(--accent);padding-left:16px;+ color:var(--soft);margin-bottom:16px}+article.page code{font-family:ui-monospace,Menlo,monospace;font-size:.86em;+ background:var(--card);border:1px solid var(--rule);border-radius:3px;padding:1px 5px}+article.page pre{background:var(--card);border:1px solid var(--rule);border-radius:4px;+ padding:14px 16px;overflow:auto;margin-bottom:17px}+article.page pre code{background:none;border:0;padding:0;font-size:13.5px;line-height:1.55}+article.page table{width:100%;border-collapse:collapse;margin-bottom:18px;font-size:14.5px}+article.page th{text-align:left;font-weight:600;padding:7px 10px 7px 0;+ border-bottom:1px solid var(--ink)}+article.page td{padding:8px 10px 8px 0;border-bottom:1px solid var(--rule);vertical-align:top}+article.page a.wiki{color:var(--accent);white-space:normal}+article.page a.wiki::before{content:"[[";color:var(--faint)}+article.page a.wiki::after{content:"]]";color:var(--faint)}+.pager{display:flex;gap:16px;justify-content:space-between;margin-top:46px;+ padding-top:18px;border-top:1px solid var(--rule);font-size:14px}+.pager a{max-width:46%}+.pager .lbl{display:block;font:11px ui-monospace,Menlo,monospace;color:var(--faint)}+.src{margin-top:34px;font:12px ui-monospace,Menlo,monospace;color:var(--faint)}++/* resources */+.rwrap{max-width:1180px;margin:0 auto;padding:34px 22px 90px}+.rwrap h1{font:600 clamp(30px,4vw,44px)/1.08 Charter,Georgia,serif;letter-spacing:-.025em}+.lede{max-width:62ch;color:var(--soft);margin:12px 0 24px;font-size:17px}+.controls{display:flex;flex-wrap:wrap;gap:9px;align-items:center;margin-bottom:8px;+ padding-bottom:18px;border-bottom:1px solid var(--rule)}+.chip{font:13px/1 ui-monospace,Menlo,monospace;background:var(--card);color:var(--soft);+ border:1px solid var(--rule);border-radius:20px;padding:7px 13px;cursor:pointer}+.chip.on{background:var(--accent);border-color:var(--accent);color:#F7F9F6}+.controls input{margin-left:auto;font:14px ui-monospace,Menlo,monospace;+ background:var(--card);border:1px solid var(--rule);border-radius:3px;padding:8px 11px;width:230px}+.count{font:12px ui-monospace,Menlo,monospace;color:var(--faint);padding:14px 0 4px}+.grp-h{font:600 15px/1 ui-monospace,Menlo,monospace;color:var(--faint);+ margin:26px 0 6px;padding-top:14px;border-top:1px solid var(--rule)}+.row{display:grid;grid-template-columns:minmax(180px,260px) 120px 1fr;gap:18px;+ padding:12px 0;border-bottom:1px solid var(--rule);align-items:baseline}+@media(max-width:760px){.row{grid-template-columns:1fr;gap:3px}}+.row .nm{font-weight:600;font-size:16px}+.row .mt{font:13px ui-monospace,Menlo,monospace;color:var(--num)}+.row .ds{color:var(--soft);font-size:15px}+.row .kd{font:11px ui-monospace,Menlo,monospace;color:var(--faint);display:block;margin-top:2px}+footer{border-top:1px solid var(--rule);padding:22px;text-align:center;+ font:12px ui-monospace,Menlo,monospace;color:var(--faint)}+@media(prefers-reduced-motion:reduce){*{transition:none!important;animation:none!important}}+</style></head><body>+<header><div class="bar">+ <a class="brand" href="index.html">[[ second<span>brain</span>os ]]</a>+ <nav>+ <a href="index.html" class="on">Guide</a>+ <a href="resources.html" class="">Resources</a>+ <a href="https://github.com/undefined-ui/second-brain-os">Repo</a>+ </nav>+ <button class="toc-btn" id="toc">Index</button>+ <div class="search"><input id="q" type="search" placeholder="search the guide" autocomplete="off"><div class="hits" id="hits"></div></div>+</div></header>+<template id="hero"><div class="hero"><h1>A knowledge base your agent maintains</h1>+<p>Everything you read, watched and wrote, turned into linked pages and kept current by an agent. Plain markdown on your own machine.</p>+<figure class="figure"><svg viewBox="0 0 800 470" role="img" aria-label="The ten sections of the guide and the links between them"><path class="edge" d="M400,82 Q432,183 576,111" stroke-width="1.22" stroke-opacity="0.47"/><path class="edge" d="M400,82 Q368,227 224,353" stroke-width="1.22" stroke-opacity="0.47"/><path class="edge" d="M400,82 Q451,197 685,186" stroke-width="1.22" stroke-opacity="0.47"/><path class="edge" d="M576,353 Q400,276 224,353" stroke-width="1.22" stroke-opacity="0.47"/><path class="edge" d="M576,353 Q432,281 400,382" stroke-width="1.22" stroke-opacity="0.47"/><path class="edge" d="M685,186 Q420,246 224,353" stroke-width="1.22" stroke-opacity="0.47"/><path class="edge" d="M400,382 Q368,281 224,353" stroke-width="1.22" stroke-opacity="0.47"/><path class="edge" d="M685,278 Q400,249 115,278" stroke-width="1.22" stroke-opacity="0.47"/><path class="edge" d="M685,278 Q400,232 115,186" stroke-width="1.22" stroke-opacity="0.47"/><path class="edge" d="M115,278 Q297,232 115,186" stroke-width="1.22" stroke-opacity="0.47"/><path class="edge" d="M400,82 Q368,183 224,111" stroke-width="1.22" stroke-opacity="0.47"/><path class="edge" d="M115,186 Q317,202 224,111" stroke-width="1.22" stroke-opacity="0.47"/><path class="edge" d="M576,111 Q400,188 224,111" stroke-width="1.22" stroke-opacity="0.47"/><path class="edge" d="M576,111 Q432,237 400,382" stroke-width="1.64" stroke-opacity="0.59"/><path class="edge" d="M576,111 Q380,202 115,186" stroke-width="1.64" stroke-opacity="0.59"/><path class="edge" d="M685,186 Q400,215 115,186" stroke-width="1.64" stroke-opacity="0.59"/><path class="edge" d="M400,382 Q349,251 115,186" stroke-width="1.64" stroke-opacity="0.59"/><path class="edge" d="M685,278 Q420,262 224,353" stroke-width="1.64" stroke-opacity="0.59"/><path class="edge" d="M576,353 Q380,246 115,186" stroke-width="1.64" stroke-opacity="0.59"/><path class="edge" d="M576,353 Q400,232 224,111" stroke-width="1.64" stroke-opacity="0.59"/><path class="edge" d="M400,82 Q432,227 576,353" stroke-width="2.06" stroke-opacity="0.71"/><path class="edge" d="M685,278 Q420,218 224,111" stroke-width="2.06" stroke-opacity="0.71"/><path class="edge" d="M685,186 Q420,202 224,111" stroke-width="2.06" stroke-opacity="0.71"/><g class="node" data-sec="01-concepts"><circle cx="400" cy="82" r="14.0"/><text x="400" y="56" text-anchor="middle">Concepts</text><text class="cnt" x="400" y="69" text-anchor="middle">8 pages</text><text class="idx" x="400" y="86" text-anchor="middle">1</text></g><g class="node" data-sec="02-setup"><circle cx="576" cy="111" r="14.8"/><text x="600" y="84" text-anchor="start">Setup</text><text class="cnt" x="600" y="97" text-anchor="start">9 pages</text><text class="idx" x="576" y="114" text-anchor="middle">2</text></g><g class="node" data-sec="03-ingestion"><circle cx="685" cy="186" r="13.2"/><text x="708" y="191" text-anchor="start">Ingestion</text><text class="cnt" x="708" y="204" text-anchor="start">7 pages</text><text class="idx" x="685" y="189" text-anchor="middle">3</text></g><g class="node" data-sec="04-structuring"><circle cx="685" cy="278" r="14.0"/><text x="708" y="283" text-anchor="start">Structuring</text><text class="cnt" x="708" y="296" text-anchor="start">8 pages</text><text class="idx" x="685" y="282" text-anchor="middle">4</text></g><g class="node" data-sec="05-graphs"><circle cx="576" cy="353" r="13.2"/><text x="599" y="385" text-anchor="start">Graphs</text><text class="cnt" x="599" y="398" text-anchor="start">7 pages</text><text class="idx" x="576" y="357" text-anchor="middle">5</text></g><g class="node" data-sec="06-agents"><circle cx="400" cy="382" r="12.5"/><text x="400" y="412" text-anchor="middle">Agents</text><text class="cnt" x="400" y="426" text-anchor="middle">6 pages</text><text class="idx" x="400" y="386" text-anchor="middle">6</text></g><g class="node" data-sec="07-retrieval"><circle cx="224" cy="353" r="11.8"/><text x="203" y="383" text-anchor="end">Retrieval</text><text class="cnt" x="203" y="396" text-anchor="end">5 pages</text><text class="idx" x="224" y="357" text-anchor="middle">7</text></g><g class="node" data-sec="08-outputs"><circle cx="115" cy="278" r="11.0"/><text x="95" y="283" text-anchor="end">Outputs</text><text class="cnt" x="95" y="296" text-anchor="end">4 pages</text><text class="idx" x="115" y="282" text-anchor="middle">8</text></g><g class="node" data-sec="09-maintenance"><circle cx="115" cy="186" r="12.5"/><text x="93" y="191" text-anchor="end">Maintenance</text><text class="cnt" x="93" y="204" text-anchor="end">6 pages</text><text class="idx" x="115" y="189" text-anchor="middle">9</text></g><g class="node" data-sec="10-troubleshooting"><circle cx="224" cy="111" r="11.8"/><text x="203" y="87" text-anchor="end">Troubleshooting</text><text class="cnt" x="203" y="100" text-anchor="end">5 pages</text><text class="idx" x="224" y="114" text-anchor="middle">10</text></g></svg><figcaption>The ten sections, in reading order, with the 23 places they reference each other. Thicker where they lean on each other hardest. Click one to start there.</figcaption></figure><div class="stats">+ <div class="stat"><b>65</b><span>pages</span></div>+ <div class="stat"><b>10</b><span>sections</span></div>+ <div class="stat"><b>25k</b><span>words</span></div>+ <div class="stat"><b>86</b><span>vetted links</span></div>+ <div class="stat"><b>0</b><span>lock-in</span></div>+</div></div><div class="seclist"><article><h3><a href="#01-concepts/what-is-a-second-brain">Concepts</a></h3><p>Why an LLM-maintained knowledge base beats the note system you abandoned, and what the pattern actually is.</p><div class="pg">8 pages</div></article><article><h3><a href="#02-setup/obsidian-install-and-vault">Setup</a></h3><p>From zero to a vault your agent maintains, in one evening. Follow the pages in order the first time. Nine steps, roughly twenty minutes of typing and however long the interview in step four takes you.</p><div class="pg">9 pages</div></article><article><h3><a href="#03-ingestion/web-clipper">Ingestion</a></h3><p>Getting everything you read, watch and write into <code>raw/</code> with as little friction as possible, then into the wiki without flooding it.</p><div class="pg">7 pages</div></article><article><h3><a href="#04-structuring/atomic-pages">Structuring</a></h3><p>The rules that decide whether your vault becomes a graph or a landfill.</p><div class="pg">8 pages</div></article><article><h3><a href="#05-graphs/graph-basics">Graphs</a></h3><p>The part most second-brain guides skip. They tell you to open the graph view, say it looks like a brain, and move on.</p><div class="pg">7 pages</div></article><article><h3><a href="#06-agents/agent-roles">Agents</a></h3><p>Turning a one-off setup into a system that maintains itself.</p><div class="pg">6 pages</div></article><article><h3><a href="#07-retrieval/asking-questions">Retrieval</a></h3><p>How to actually ask your vault things and get answers worth trusting.</p><div class="pg">5 pages</div></article><article><h3><a href="#08-outputs/writing-from-the-vault">Outputs</a></h3><p>The vault earns its keep when things come out of it.</p><div class="pg">4 pages</div></article><article><h3><a href="#09-maintenance/lint-and-health">Maintenance</a></h3><p>What keeps the thing alive after the novelty wears off.</p><div class="pg">6 pages</div></article><article><h3><a href="#10-troubleshooting/common-failures">Troubleshooting</a></h3><p>Concrete failures, with fixes.</p><div class="pg">5 pages</div></article></div></template>+<div class="wrap">+ <aside id="side"></aside>+ <main id="main"></main>+ <div class="rail" id="rail"></div>+</div>+<footer>Generated from the repository. <a href="https://github.com/undefined-ui/second-brain-os">github.com/undefined-ui/second-brain-os</a></footer>+<script id="data" type="application/json">{"pages": [{"id": "01-concepts/what-is-a-second-brain", "path": "docs/01-concepts/what-is-a-second-brain.md", "section": "01-concepts", "section_title": "Concepts", "title": "What a second brain actually is", "html": "<p>One local folder of plain text that an agent reads and writes, holding what you\nhave read and understood, that you can ask questions.</p>\n<p>That is the whole definition. Everything else in this guide is detail about\nmaking it work.</p>\n<h2 id=\"what-it-is-not\">What it is not</h2>\n<p><strong>Not a prettier notes app.</strong> The point is not organisation. You can organise\nnotes beautifully and still never reopen them.</p>\n<p><strong>Not a chatbot with your PDFs attached.</strong> Attaching documents to a chat gets you\nanswers about those documents in that session. Nothing accumulates, nothing\nconnects, and next week you attach them again.</p>\n<p><strong>Not a memory feature.</strong> Assistants that remember facts about you are useful and\nare a different thing. This is a body of knowledge you own, that outlives any\nparticular tool.</p>\n<h2 id=\"the-three-jobs\">The three jobs</h2>\n<p><strong>Capture.</strong> Everything you read, watch and write down lands in one place with\nnear-zero friction. If capture takes effort, nothing else matters, because there\nwill be nothing to organise.</p>\n<p><strong>Connect.</strong> New material gets linked into what is already there. This is the job\nhumans stop doing after two weeks and the reason every previous note system\nfailed. It is also the entire value: unconnected notes are a folder.</p>\n<p><strong>Answer.</strong> You ask questions across everything at once, and get answers grounded\nin your own sources with citations you can open.</p>\n<h2 id=\"where-the-value-comes-from\">Where the value comes from</h2>\n<p>Not from any single page. A page is a slightly better version of a note you could\nhave written.</p>\n<p>It comes from density. At fifty sources, the vault starts connecting things you\nread months apart. At five hundred, it answers questions you could not have\nanswered yourself, because nobody holds five hundred sources in their head at\nonce.</p>\n<p>That is why the first two weeks feel underwhelming and why most people quit\nbefore the payoff. The system is not broken at thirty pages, it is just\nearly. See <a href=\"what-good-looks-like.md\">what good looks like</a> for a realistic\ntimeline.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"the-save-for-later-paradox.md\">The save-for-later paradox</a></p>", "headings": ["What it is not", "The three jobs", "Where the value comes from", "Next"], "words": 327, "text": "One local folder of plain text that an agent reads and writes, holding what you have read and understood, that you can ask questions. That is the whole definition. Everything else in this guide is detail about making it work. What it is not Not a prettier notes app. The point is not organisation. You can organise notes beautifully and still never reopen them. Not a chatbot with your PDFs attached. Attaching documents to a chat gets you answers about those documents in that session. Nothing accumulates, nothing connects, and next week you attach them again. Not a memory feature. Assistants that remember facts about you are useful and are a different thing. This is a body of knowledge you own, that outlives any particular tool. The three jobs Capture. Everything you read, watch and write down lands in one place with near-zero friction. If capture takes effort, nothing else matters, because there will be nothing to organise. Connect. New material gets linked into what is already there. This is the job humans stop doing after two weeks and the reason every previous note system failed. It is also the entire value: unconnected notes are a folder. Answer. You ask questions across everything at once, and get answers grounded in your own sources with citations you can open. Where the value comes from Not from any single page. A page is a slightly better version of a note you could have written. It comes from density. At fifty sources, the vault starts connecting things you read months apart. At five hundred, it answers questions you could not have answered yourself, because nobody holds five hundred sources in their head at once. That is why the first two weeks feel underwhelming and why most people quit before the payoff. The system is not broken at thirty pages, it is just early. See what good looks like what-good-looks-like.md for a realistic timeline. Next The save-for-later paradox the-save-for-later-paradox.md", "links": [{"to": "01-concepts/what-good-looks-like", "label": "what good looks like"}, {"to": "01-concepts/the-save-for-later-paradox", "label": "The save-for-later paradox"}]}, {"id": "01-concepts/the-save-for-later-paradox", "path": "docs/01-concepts/the-save-for-later-paradox.md", "section": "01-concepts", "section_title": "Concepts", "title": "The save-for-later paradox", "html": "<p>You screenshot the post. You bookmark the article. You save the video to a\nplaylist named \"watch later\" that has four hundred items in it.</p>\n<p>You do not go back. Almost nobody does.</p>\n<h2 id=\"why-saving-fails\">Why saving fails</h2>\n<p>Saving feels like an action, and it discharges the feeling that made you want to\nsave. The intention gets spent at the moment of saving rather than at the moment\nof reading, which is why the queue grows and the reading does not.</p>\n<p>Then retrieval costs more than it is worth. Finding the thing you saved means\nremembering that you saved it, remembering where, and searching wording you no\nlonger recall. Compared to a fresh search, the saved item loses, so you search\nagain and save again.</p>\n<p>And the pile itself becomes a deterrent. Four hundred unread items is not a\nresource, it is a debt you avoid looking at.</p>\n<h2 id=\"what-actually-changes-it\">What actually changes it</h2>\n<p>Not better tagging. Not a better read-later app. Not discipline, which is the\nthing that already failed.</p>\n<p>What changes it is removing the step you keep failing at. If the filing and\nconnecting happen without you, the queue stops being a queue: the material is\nalready processed, already linked, already reachable by asking a question in\nplain language.</p>\n<p>The retrieval cost inverts too. You no longer need to remember that you saved\nsomething, or where. You ask what you know about a topic, and things you had\nforgotten saving come back.</p>\n<h2 id=\"the-honest-limit\">The honest limit</h2>\n<p>The system does not make you read things. It processes what you feed it, and\nwhat you feed it is still your choice.</p>\n<p>What it does is make saving worth doing. That is a smaller claim than most\nsecond-brain pitches make, and it is the one that holds up after a month.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"llm-wiki-pattern.md\">The LLM wiki pattern</a></p>", "headings": ["Why saving fails", "What actually changes it", "The honest limit", "Next"], "words": 305, "text": "You screenshot the post. You bookmark the article. You save the video to a playlist named \"watch later\" that has four hundred items in it. You do not go back. Almost nobody does. Why saving fails Saving feels like an action, and it discharges the feeling that made you want to save. The intention gets spent at the moment of saving rather than at the moment of reading, which is why the queue grows and the reading does not. Then retrieval costs more than it is worth. Finding the thing you saved means remembering that you saved it, remembering where, and searching wording you no longer recall. Compared to a fresh search, the saved item loses, so you search again and save again. And the pile itself becomes a deterrent. Four hundred unread items is not a resource, it is a debt you avoid looking at. What actually changes it Not better tagging. Not a better read-later app. Not discipline, which is the thing that already failed. What changes it is removing the step you keep failing at. If the filing and connecting happen without you, the queue stops being a queue: the material is already processed, already linked, already reachable by asking a question in plain language. The retrieval cost inverts too. You no longer need to remember that you saved something, or where. You ask what you know about a topic, and things you had forgotten saving come back. The honest limit The system does not make you read things. It processes what you feed it, and what you feed it is still your choice. What it does is make saving worth doing. That is a smaller claim than most second-brain pitches make, and it is the one that holds up after a month. Next The LLM wiki pattern llm-wiki-pattern.md", "links": [{"to": "01-concepts/llm-wiki-pattern", "label": "The LLM wiki pattern"}]}, {"id": "01-concepts/llm-wiki-pattern", "path": "docs/01-concepts/llm-wiki-pattern.md", "section": "01-concepts", "section_title": "Concepts", "title": "The LLM wiki pattern", "html": "<p>The specific pattern this guide implements, published by Andrej Karpathy as a\ngist on 2026-04-04.</p>\n<p>The inversion in one sentence: instead of you maintaining notes and occasionally\nasking an AI about them, the AI maintains the wiki and you read it.</p>\n<h2 id=\"what-the-pattern-specifies\">What the pattern specifies</h2>\n<p><strong>The wiki is primary.</strong> Raw sources are an archive you keep and rarely open.\nThe wiki is what you and the agent both work from, written in plain language,\none idea per page, densely linked.</p>\n<p><strong>Compilation, not summarization.</strong> Each new source is integrated into existing\npages rather than added beside them as another summary. A page about a concept\nimproves as sources accumulate; it does not turn into a list of what each source\nsaid.</p>\n<p><strong>Three operations.</strong> Ingest brings new material in. Lint keeps the structure\nsound. Query answers from the wiki. Everything else is variation on those.</p>\n<h2 id=\"why-it-holds-up\">Why it holds up</h2>\n<p>Because it removes the one task that killed every previous system. Linking fifty\nnotes to each other every time you read a paper is genuinely boring work that\nhumans stop doing, and the wiki dies when the maintainer gets tired.</p>\n<p>The other reason is that it needs no infrastructure. Markdown files, wikilinks,\nan agent that can read and write files. No database, no index to keep fresh, no\nservice to depend on.</p>\n<h2 id=\"where-the-gist-stops\">Where the gist stops</h2>\n<p>It describes intent, not implementation. Integrate new sources, lint\nperiodically, treat the wiki as primary.</p>\n<p>The mechanics are left open, which is why every implementation of it differs.\nHow integration handles contradictions, what a page must contain, when lint\nruns, who the wiki is written for. This guide's answers to those are in\n<a href=\"../04-structuring/README.md\">Structuring</a>, and they are opinions, not the\npattern itself.</p>\n<h2 id=\"what-people-build-on-top\">What people build on top</h2>\n<p>The common extensions are a journal layer, a project layer, and scheduled\nautomation. This guide covers the second and third as <a href=\"two-layers.md\">the two\nlayers</a> and <a href=\"../06-agents/README.md\">Agents</a>.</p>\n<p>The pattern also spread quickly because the primitives are ordinary: anyone with\nan agent and a folder can run it, and the implementations are all readable\nmarkdown. See <a href=\"../../resources/skills.md\">resources</a> for the ones worth reading.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"two-layers.md\">The two layers</a></p>", "headings": ["What the pattern specifies", "Why it holds up", "Where the gist stops", "What people build on top", "Next"], "words": 359, "text": "The specific pattern this guide implements, published by Andrej Karpathy as a gist on 2026-04-04. The inversion in one sentence: instead of you maintaining notes and occasionally asking an AI about them, the AI maintains the wiki and you read it. What the pattern specifies The wiki is primary. Raw sources are an archive you keep and rarely open. The wiki is what you and the agent both work from, written in plain language, one idea per page, densely linked. Compilation, not summarization. Each new source is integrated into existing pages rather than added beside them as another summary. A page about a concept improves as sources accumulate; it does not turn into a list of what each source said. Three operations. Ingest brings new material in. Lint keeps the structure sound. Query answers from the wiki. Everything else is variation on those. Why it holds up Because it removes the one task that killed every previous system. Linking fifty notes to each other every time you read a paper is genuinely boring work that humans stop doing, and the wiki dies when the maintainer gets tired. The other reason is that it needs no infrastructure. Markdown files, wikilinks, an agent that can read and write files. No database, no index to keep fresh, no service to depend on. Where the gist stops It describes intent, not implementation. Integrate new sources, lint periodically, treat the wiki as primary. The mechanics are left open, which is why every implementation of it differs. How integration handles contradictions, what a page must contain, when lint runs, who the wiki is written for. This guide's answers to those are in Structuring ../04-structuring/README.md , and they are opinions, not the pattern itself. What people build on top The common extensions are a journal layer, a project layer, and scheduled automation. This guide covers the second and third as the two layers two-layers.md and Agents ../06-agents/README.md . The pattern also spread quickly because the primitives are ordinary: anyone with an agent and a folder can run it, and the implementations are all readable markdown. See resources ../../resources/skills.md for the ones worth reading. Next The two layers two-layers.md", "links": [{"to": "01-concepts/two-layers", "label": "the two\nlayers"}, {"to": "01-concepts/two-layers", "label": "The two layers"}]}, {"id": "01-concepts/two-layers", "path": "docs/01-concepts/two-layers.md", "section": "01-concepts", "section_title": "Concepts", "title": "The two layers", "html": "<p>Most second-brain setups fail because they pick one shape and try to make it do\ntwo jobs.</p>\n<p><strong>The knowledge layer</strong> answers \"what do I know about X\". It is organised by\nidea, it grows forever, and its value is in the links between pages. This is the\nLLM wiki pattern: sources in, concepts out, everything connected.</p>\n<p><strong>The project layer</strong> answers \"what am I doing this week\". It is organised as a\npipeline, inputs to outputs, and most of it goes cold the moment the project\nships.</p>\n<p>They fail differently when merged. A wiki with project folders in it fills up\nwith dead task lists that make every search worse. A project system with\nconceptual notes in it buries the working files under material nobody opens\nwhile working.</p>\n<h2 id=\"how-they-connect\">How they connect</h2>\n<p>Projects consume the knowledge layer and feed it back:</p>\n<pre><code> wiki/concepts \u2500\u2500\u2500\u2500\u2500\u2500> project Inputs/\n \u25b2 \u2502\n \u2502 \u25bc\n ingest what Process/ \u2500\u2500> Outputs/\n you learned \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n</code></pre>\n<p>Work produces material worth keeping. Ingesting your own finished work is the\nstep almost everyone skips, and it is the one that makes the second project in\na domain meaningfully faster than the first.</p>\n<h2 id=\"which-to-build-first\">Which to build first</h2>\n<p>The knowledge layer, if you read a lot and retain little.</p>\n<p>The project layer, if your problem is that you re-explain your situation to a\nchat window every morning.</p>\n<p>Both eventually. See <a href=\"../02-setup/vault-structure.md\">vault structure</a> for the\nlayout that keeps them separate inside one folder.</p>", "headings": ["How they connect", "Which to build first"], "words": 242, "text": "Most second-brain setups fail because they pick one shape and try to make it do two jobs. The knowledge layer answers \"what do I know about X\". It is organised by idea, it grows forever, and its value is in the links between pages. This is the LLM wiki pattern: sources in, concepts out, everything connected. The project layer answers \"what am I doing this week\". It is organised as a pipeline, inputs to outputs, and most of it goes cold the moment the project ships. They fail differently when merged. A wiki with project folders in it fills up with dead task lists that make every search worse. A project system with conceptual notes in it buries the working files under material nobody opens while working. How they connect Projects consume the knowledge layer and feed it back: wiki/concepts \u2500\u2500\u2500\u2500\u2500\u2500 project Inputs/ \u25b2 \u2502 \u2502 \u25bc ingest what Process/ \u2500\u2500 Outputs/ you learned \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 Work produces material worth keeping. Ingesting your own finished work is the step almost everyone skips, and it is the one that makes the second project in a domain meaningfully faster than the first. Which to build first The knowledge layer, if you read a lot and retain little. The project layer, if your problem is that you re-explain your situation to a chat window every morning. Both eventually. See vault structure ../02-setup/vault-structure.md for the layout that keeps them separate inside one folder.", "links": [{"to": "02-setup/vault-structure", "label": "vault structure"}]}, {"id": "01-concepts/why-markdown-and-plain-text", "path": "docs/01-concepts/why-markdown-and-plain-text.md", "section": "01-concepts", "section_title": "Concepts", "title": "Why markdown and plain text", "html": "<p>The format looks like a detail. It decides whether the system works.</p>\n<h2 id=\"agents-handle-files-better-than-apis\">Agents handle files better than APIs</h2>\n<p>An agent reading a folder does what it is best at: reading text and writing text.\nNo schema to learn, no API to call correctly, no failure mode where a request\nhalf-succeeds.</p>\n<p>That reliability compounds over thousands of operations. A pipeline that writes\nmarkdown files fails in ways you can see in a diff; one that writes through an\nAPI fails in ways you find out about later.</p>\n<h2 id=\"portability-is-not-theoretical\">Portability is not theoretical</h2>\n<p>Every previous notes tool people trusted either shut down, changed pricing, or\nmade export deliberately awkward.</p>\n<p>Plain files remove the question. Your vault opens in any text editor, syncs with\nany tool, and works with any agent that reads files. Switch models, switch\neditors, switch operating systems, and the vault is unaffected because it was\nnever in anything.</p>\n<p>This matters more than usual here, because a second brain accumulates value over\nyears. A format that traps you is a format that eventually costs you the whole\nthing.</p>\n<h2 id=\"wikilinks-as-a-graph-format\">Wikilinks as a graph format</h2>\n<p><code>[[Page name]]</code> is a two-character convention that produces a real graph, is\nreadable as text, and survives every tool that does not understand it, because\nin the worst case it is still just words in a sentence.</p>\n<p>You can parse it with a regex, which is what <code>scripts/graph_export.py</code> does. Try\nthat with a proprietary block reference format.</p>\n<h2 id=\"git-works-on-it\">Git works on it</h2>\n<p>Text diffs. That single property is what makes an agent safe to run unattended:\nevery change it makes is reviewable, revertible, and attributable to a run.</p>\n<p>Binary formats and database-backed apps give you no equivalent. You either trust\nthe automation completely or you do not automate.</p>\n<h2 id=\"the-limits\">The limits</h2>\n<p>Plain text is bad at a few things, and pretending otherwise is how people end up\nfrustrated.</p>\n<p><strong>Structured queries at scale.</strong> Dataview covers a lot, but past a few thousand\npages, relational questions want a real database. Export the graph rather than\nabandoning markdown; see <a href=\"../05-graphs/exporting-your-graph.md\">exporting the\ngraph</a>.</p>\n<p><strong>Rich media.</strong> Images live beside the text as files, not in it. Diagrams are\nattachments.</p>\n<p><strong>Concurrent editing.</strong> Two agents writing the same file conflict in the way\nfiles conflict, which is to say badly.</p>\n<p>None of those outweigh portability for a personal vault. All of them are worth\nknowing before you hit them.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"pkm-lineage.md\">Zettelkasten, PARA, evergreen notes</a></p>", "headings": ["Agents handle files better than APIs", "Portability is not theoretical", "Wikilinks as a graph format", "Git works on it", "The limits", "Next"], "words": 403, "text": "The format looks like a detail. It decides whether the system works. Agents handle files better than APIs An agent reading a folder does what it is best at: reading text and writing text. No schema to learn, no API to call correctly, no failure mode where a request half-succeeds. That reliability compounds over thousands of operations. A pipeline that writes markdown files fails in ways you can see in a diff; one that writes through an API fails in ways you find out about later. Portability is not theoretical Every previous notes tool people trusted either shut down, changed pricing, or made export deliberately awkward. Plain files remove the question. Your vault opens in any text editor, syncs with any tool, and works with any agent that reads files. Switch models, switch editors, switch operating systems, and the vault is unaffected because it was never in anything. This matters more than usual here, because a second brain accumulates value over years. A format that traps you is a format that eventually costs you the whole thing. Wikilinks as a graph format Page name is a two-character convention that produces a real graph, is readable as text, and survives every tool that does not understand it, because in the worst case it is still just words in a sentence. You can parse it with a regex, which is what scripts/graph_export.py does. Try that with a proprietary block reference format. Git works on it Text diffs. That single property is what makes an agent safe to run unattended: every change it makes is reviewable, revertible, and attributable to a run. Binary formats and database-backed apps give you no equivalent. You either trust the automation completely or you do not automate. The limits Plain text is bad at a few things, and pretending otherwise is how people end up frustrated. Structured queries at scale. Dataview covers a lot, but past a few thousand pages, relational questions want a real database. Export the graph rather than abandoning markdown; see exporting the graph ../05-graphs/exporting-your-graph.md . Rich media. Images live beside the text as files, not in it. Diagrams are attachments. Concurrent editing. Two agents writing the same file conflict in the way files conflict, which is to say badly. None of those outweigh portability for a personal vault. All of them are worth knowing before you hit them. Next Zettelkasten, PARA, evergreen notes pkm-lineage.md", "links": [{"to": "05-graphs/exporting-your-graph", "label": "exporting the\ngraph"}, {"to": "01-concepts/pkm-lineage", "label": "Zettelkasten, PARA, evergreen notes"}]}, {"id": "01-concepts/pkm-lineage", "path": "docs/01-concepts/pkm-lineage.md", "section": "01-concepts", "section_title": "Concepts", "title": "Zettelkasten, PARA, evergreen notes", "html": "<p>None of this is new. The methods people abandoned were mostly right, and it is\nworth knowing which parts of them still apply, because the good ideas came with a\ncost that has now changed.</p>\n<h2 id=\"zettelkasten\">Zettelkasten</h2>\n<p>Niklas Luhmann's slip-box, popularised for a modern audience by S\u00f6nke Ahrens in\n\"How to Take Smart Notes\". Atomic notes, one idea each, densely cross-referenced,\nwritten in your own words.</p>\n<p><strong>Still right:</strong> atomic notes, dense linking, rewriting in your own words rather\nthan clipping quotes. All three are in this guide's <a href=\"../04-structuring/README.md\">structuring\nrules</a>.</p>\n<p><strong>The cost:</strong> every link was manual. Reading one paper meant deciding where it\nconnected among hundreds of existing notes, which is real cognitive work and the\nreason most slip-boxes die in month three.</p>\n<h2 id=\"para\">PARA</h2>\n<p>Tiago Forte's system from \"Building a Second Brain\": Projects, Areas, Resources,\nArchive. Organise by actionability rather than by subject.</p>\n<p><strong>Still right:</strong> the insight that project material and reference material want\ndifferent structures. That is exactly <a href=\"two-layers.md\">the two layers</a>, arrived at\nfrom a different direction.</p>\n<p><strong>The cost:</strong> constant filing decisions, and the fact that actionability changes,\nso the same note moves between categories over time.</p>\n<h2 id=\"evergreen-notes\">Evergreen notes</h2>\n<p>Andy Matuschak's approach: notes written to be reread and improved over years,\nconcept-oriented, densely linked, developed slowly.</p>\n<p><strong>Still right:</strong> the standard for what a good concept page is. Matuschak's\nargument that notes should be written for your future self, not as a record of\nhaving read something, is the bar this guide's concept pages aim at.</p>\n<p><strong>The counterweight:</strong> his position is that the writing is the thinking, and\ndelegating it means not doing the thinking. That is a real objection to this\nwhole approach and worth sitting with rather than dismissing.</p>\n<h2 id=\"what-changed\">What changed</h2>\n<p>One thing: the maintenance is now delegable.</p>\n<p>Every system above works. Every one of them failed for the same reason, which is\nthat they required a human to do boring linking work forever. An agent doing it\ndoes not get tired in month three.</p>\n<h2 id=\"what-did-not-change\">What did not change</h2>\n<p>You still have to choose what to read. You still have to decide what matters.\nThe agent files and connects; it does not have taste, and a vault fed\nindiscriminately is a well-organised pile.</p>\n<p>And Matuschak's objection stands: understanding comes from writing. The way to\nkeep it is to write the concept pages that matter to you yourself, and let the\nagent handle sources, entities and the linking. That split is a preference this\nguide does not enforce, and it is worth deciding deliberately rather than by\ndefault.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"wiki-vs-rag.md\">Wiki vs RAG</a></p>", "headings": ["Zettelkasten", "PARA", "Evergreen notes", "What changed", "What did not change", "Next"], "words": 427, "text": "None of this is new. The methods people abandoned were mostly right, and it is worth knowing which parts of them still apply, because the good ideas came with a cost that has now changed. Zettelkasten Niklas Luhmann's slip-box, popularised for a modern audience by S\u00f6nke Ahrens in \"How to Take Smart Notes\". Atomic notes, one idea each, densely cross-referenced, written in your own words. Still right: atomic notes, dense linking, rewriting in your own words rather than clipping quotes. All three are in this guide's structuring rules ../04-structuring/README.md . The cost: every link was manual. Reading one paper meant deciding where it connected among hundreds of existing notes, which is real cognitive work and the reason most slip-boxes die in month three. PARA Tiago Forte's system from \"Building a Second Brain\": Projects, Areas, Resources, Archive. Organise by actionability rather than by subject. Still right: the insight that project material and reference material want different structures. That is exactly the two layers two-layers.md , arrived at from a different direction. The cost: constant filing decisions, and the fact that actionability changes, so the same note moves between categories over time. Evergreen notes Andy Matuschak's approach: notes written to be reread and improved over years, concept-oriented, densely linked, developed slowly. Still right: the standard for what a good concept page is. Matuschak's argument that notes should be written for your future self, not as a record of having read something, is the bar this guide's concept pages aim at. The counterweight: his position is that the writing is the thinking, and delegating it means not doing the thinking. That is a real objection to this whole approach and worth sitting with rather than dismissing. What changed One thing: the maintenance is now delegable. Every system above works. Every one of them failed for the same reason, which is that they required a human to do boring linking work forever. An agent doing it does not get tired in month three. What did not change You still have to choose what to read. You still have to decide what matters. The agent files and connects; it does not have taste, and a vault fed indiscriminately is a well-organised pile. And Matuschak's objection stands: understanding comes from writing. The way to keep it is to write the concept pages that matter to you yourself, and let the agent handle sources, entities and the linking. That split is a preference this guide does not enforce, and it is worth deciding deliberately rather than by default. Next Wiki vs RAG wiki-vs-rag.md", "links": [{"to": "01-concepts/two-layers", "label": "the two layers"}, {"to": "01-concepts/wiki-vs-rag", "label": "Wiki vs RAG"}]}, {"id": "01-concepts/wiki-vs-rag", "path": "docs/01-concepts/wiki-vs-rag.md", "section": "01-concepts", "section_title": "Concepts", "title": "Wiki vs RAG", "html": "<p>The default advice for asking questions of your own documents is to embed them\nin a vector database. This guide does something else, and the reason is\nstructural rather than a preference about tools.</p>\n<h2 id=\"the-two-approaches\">The two approaches</h2>\n<p><strong>RAG</strong> stores your documents as chunks with embeddings. A question retrieves the\nmost similar chunks and the model answers from them. Nothing is written; the\ncorpus stays as it was.</p>\n<p><strong>A wiki</strong> processes documents once, into pages an agent wrote and linked.\nQuestions are answered by navigating those pages. The corpus is transformed and\nkeeps improving.</p>\n<p>The difference is where the work happens. RAG does it at query time, every time,\nfrom scratch. A wiki does it once, at ingest, and the result is reused.</p>\n<h2 id=\"what-that-buys\">What that buys</h2>\n<p><strong>Understanding accumulates.</strong> The tenth source about a topic improves the page\nthe first nine built. In RAG, the tenth document is just another chunk, and\nnothing gets better as the corpus grows, only larger.</p>\n<p><strong>Contradictions are visible.</strong> Two documents disagreeing produce two chunks that\nmay never be retrieved together. On a page, the disagreement is written down,\ndated, and unavoidable.</p>\n<p><strong>Answers are checkable.</strong> The page cites sources you can open. Retrieved chunks\nare fragments without the reasoning that connected them.</p>\n<p><strong>No infrastructure.</strong> No index, no re-embedding, no drift between the store and\nthe files.</p>\n<h2 id=\"what-it-costs\">What it costs</h2>\n<p><strong>Ingest is expensive.</strong> Writing and linking pages costs model time up front,\nwhere RAG's ingest is nearly free.</p>\n<p><strong>Quality depends on the ingest.</strong> A bad page contract produces a bad vault, and\nyou find out later. RAG's failures are at query time and are more visible.</p>\n<p><strong>Recall depends on linking.</strong> A page nobody linked is a page the graph cannot\nreach. RAG will find it by similarity regardless.</p>\n<h2 id=\"the-honest-position\">The honest position</h2>\n<p>This trade is right for a personal, curated corpus of a few thousand pages and\nwrong for a million documents nobody organised.</p>\n<p>Which is to say it is right for a second brain and wrong for a search product,\nand most advice about RAG is written for the second case. See <a href=\"../07-retrieval/rag-on-top.md\">adding RAG when\nyou need it</a> for the threshold where the answer\nflips, and <a href=\"../05-graphs/graph-vs-vectors.md\">graph vs embeddings</a> for the\nretrieval mechanics.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"what-good-looks-like.md\">What good looks like</a></p>", "headings": ["The two approaches", "What that buys", "What it costs", "The honest position", "Next"], "words": 375, "text": "The default advice for asking questions of your own documents is to embed them in a vector database. This guide does something else, and the reason is structural rather than a preference about tools. The two approaches RAG stores your documents as chunks with embeddings. A question retrieves the most similar chunks and the model answers from them. Nothing is written; the corpus stays as it was. A wiki processes documents once, into pages an agent wrote and linked. Questions are answered by navigating those pages. The corpus is transformed and keeps improving. The difference is where the work happens. RAG does it at query time, every time, from scratch. A wiki does it once, at ingest, and the result is reused. What that buys Understanding accumulates. The tenth source about a topic improves the page the first nine built. In RAG, the tenth document is just another chunk, and nothing gets better as the corpus grows, only larger. Contradictions are visible. Two documents disagreeing produce two chunks that may never be retrieved together. On a page, the disagreement is written down, dated, and unavoidable. Answers are checkable. The page cites sources you can open. Retrieved chunks are fragments without the reasoning that connected them. No infrastructure. No index, no re-embedding, no drift between the store and the files. What it costs Ingest is expensive. Writing and linking pages costs model time up front, where RAG's ingest is nearly free. Quality depends on the ingest. A bad page contract produces a bad vault, and you find out later. RAG's failures are at query time and are more visible. Recall depends on linking. A page nobody linked is a page the graph cannot reach. RAG will find it by similarity regardless. The honest position This trade is right for a personal, curated corpus of a few thousand pages and wrong for a million documents nobody organised. Which is to say it is right for a second brain and wrong for a search product, and most advice about RAG is written for the second case. See adding RAG when you need it ../07-retrieval/rag-on-top.md for the threshold where the answer flips, and graph vs embeddings ../05-graphs/graph-vs-vectors.md for the retrieval mechanics. Next What good looks like what-good-looks-like.md", "links": [{"to": "07-retrieval/rag-on-top", "label": "adding RAG when\nyou need it"}, {"to": "05-graphs/graph-vs-vectors", "label": "graph vs embeddings"}, {"to": "01-concepts/what-good-looks-like", "label": "What good looks like"}]}, {"id": "01-concepts/what-good-looks-like", "path": "docs/01-concepts/what-good-looks-like.md", "section": "01-concepts", "section_title": "Concepts", "title": "What good looks like", "html": "<p>Concrete criteria, so you can tell whether yours is working rather than guessing.</p>\n<h2 id=\"the-test\">The test</h2>\n<p>Ask it something you half-remember reading about, months ago, that you cannot\nname precisely.</p>\n<p>If it comes back with the idea, the sources, and two related things you had\nforgotten, it works. If it returns nothing, or returns a general explanation that\ncould have come from any model, it does not.</p>\n<h2 id=\"signals-of-health\">Signals of health</h2>\n<p><strong>You reach for it before searching the web.</strong> The strongest signal, and it\nhappens on its own once the vault is dense enough.</p>\n<p><strong>Answers cite pages you can open,</strong> and the pages say what the answer said.</p>\n<p><strong>The graph has clusters you did not plan.</strong> Evidence it is tracking what you\nactually pay attention to rather than what you told it to.</p>\n<p><strong>New sources mostly update existing pages</strong> rather than creating new ones. That\nmeans the vault has the concepts already and is deepening rather than sprawling.</p>\n<p><strong>It contradicts you occasionally,</strong> because you have material on both sides of\nsomething.</p>\n<h2 id=\"signals-of-trouble\">Signals of trouble</h2>\n<p><strong>Orphan rate climbing.</strong> Ingestion has stopped linking. See\n<a href=\"../05-graphs/metrics.md\">metrics</a>.</p>\n<p><strong>Pages that read as summaries</strong> rather than explanations. The page contract in\n<code>CLAUDE.md</code> needs tightening.</p>\n<p><strong>Concept pages untouched for months while sources keep arriving.</strong> New material\nis landing in new pages instead of updating existing ones, which produces four\npages about one thing.</p>\n<p><strong>You stopped opening it.</strong> The honest one. Usually means capture broke, not that\nthe idea failed.</p>\n<h2 id=\"a-realistic-timeline\">A realistic timeline</h2>\n<p><strong>Week one.</strong> Setup, ten or twenty sources. Feels like a folder with extra steps.\nThis is normal and it is where most people quit.</p>\n<p><strong>Week two to four.</strong> Fifty to a hundred sources. First moment of the vault\nconnecting two things you read weeks apart. This is when it starts being worth\nthe setup.</p>\n<p><strong>Month three.</strong> A few hundred pages. It answers questions faster than you could\nby rereading, and it surfaces things you had forgotten saving.</p>\n<p><strong>Month six.</strong> It knows things you do not remember learning. That is the state\neveryone describes as the payoff, and it is real, and it takes six months of\nfeeding it.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"../02-setup/README.md\">Setup</a>.</p>", "headings": ["The test", "Signals of health", "Signals of trouble", "A realistic timeline", "Next"], "words": 358, "text": "Concrete criteria, so you can tell whether yours is working rather than guessing. The test Ask it something you half-remember reading about, months ago, that you cannot name precisely. If it comes back with the idea, the sources, and two related things you had forgotten, it works. If it returns nothing, or returns a general explanation that could have come from any model, it does not. Signals of health You reach for it before searching the web. The strongest signal, and it happens on its own once the vault is dense enough. Answers cite pages you can open, and the pages say what the answer said. The graph has clusters you did not plan. Evidence it is tracking what you actually pay attention to rather than what you told it to. New sources mostly update existing pages rather than creating new ones. That means the vault has the concepts already and is deepening rather than sprawling. It contradicts you occasionally, because you have material on both sides of something. Signals of trouble Orphan rate climbing. Ingestion has stopped linking. See metrics ../05-graphs/metrics.md . Pages that read as summaries rather than explanations. The page contract in CLAUDE.md needs tightening. Concept pages untouched for months while sources keep arriving. New material is landing in new pages instead of updating existing ones, which produces four pages about one thing. You stopped opening it. The honest one. Usually means capture broke, not that the idea failed. A realistic timeline Week one. Setup, ten or twenty sources. Feels like a folder with extra steps. This is normal and it is where most people quit. Week two to four. Fifty to a hundred sources. First moment of the vault connecting two things you read weeks apart. This is when it starts being worth the setup. Month three. A few hundred pages. It answers questions faster than you could by rereading, and it surfaces things you had forgotten saving. Month six. It knows things you do not remember learning. That is the state everyone describes as the payoff, and it is real, and it takes six months of feeding it. Next Setup ../02-setup/README.md .", "links": [{"to": "05-graphs/metrics", "label": "metrics"}]}, {"id": "02-setup/obsidian-install-and-vault", "path": "docs/02-setup/obsidian-install-and-vault.md", "section": "02-setup", "section_title": "Setup", "title": "Obsidian and your first vault", "html": "<p>Obsidian is the storage half of the system. It is free, it keeps everything as\nplain text files on your own machine, and it renders the links between notes as\na graph. Nothing here is stored in a company's cloud, and the files stay\nreadable in any text editor if you ever walk away from the app.</p>\n<h2 id=\"install\">Install</h2>\n<p>Download from <a href=\"https://obsidian.md\">obsidian.md</a> and install it.</p>\n<p>On the welcome screen, click <strong>Create new vault</strong>. Name it something short you\nwill type often, <code>brain</code> works. Pick a folder on your machine and click\n<strong>Create</strong>.</p>\n<p>That folder is now your second brain. Everything the agent writes lands there\nas markdown files.</p>\n<h2 id=\"make-one-note-by-hand\">Make one note by hand</h2>\n<p>Do this once before automating anything, so the mechanic is not abstract.</p>\n<p>Click the new-note icon, type a sentence, then type <code>[[goals]]</code>. The bracketed\nword becomes a link to a page called <code>goals</code>, whether or not that page exists\nyet. Click it and Obsidian creates the page.</p>\n<p>That is the entire data model: notes pointing at notes. Everything the agent\ndoes later is this, at volume, without you doing it.</p>\n<h2 id=\"where-to-put-the-vault\">Where to put the vault</h2>\n<p>Somewhere with a stable path you can type from a terminal. Avoid a folder your\ncloud sync client rewrites aggressively, because an agent writing files while a\nsync client rewrites them produces conflict copies that are genuinely painful\nto untangle. See <a href=\"git-and-sync.md\">git and sync</a> for the options that work.</p>\n<p>Avoid spaces in the folder name. You will be pasting this path into commands.</p>\n<h2 id=\"settings-worth-changing-now\">Settings worth changing now</h2>\n<ul>\n<li><strong>Files and links \u2192 New link format:</strong> relative path or shortest path,\n consistently. Mixed link formats are the most common cause of broken links\n after a rename.</li>\n<li><strong>Files and links \u2192 Automatically update internal links:</strong> on.</li>\n<li><strong>Editor \u2192 Show frontmatter:</strong> on. You want to see the metadata the agent\n writes, at least for the first weeks.</li>\n</ul>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"claude-code-setup.md\">Claude Code in the vault</a></p>", "headings": ["Install", "Make one note by hand", "Where to put the vault", "Settings worth changing now", "Next"], "words": 324, "text": "Obsidian is the storage half of the system. It is free, it keeps everything as plain text files on your own machine, and it renders the links between notes as a graph. Nothing here is stored in a company's cloud, and the files stay readable in any text editor if you ever walk away from the app. Install Download from obsidian.md https://obsidian.md and install it. On the welcome screen, click Create new vault . Name it something short you will type often, brain works. Pick a folder on your machine and click Create . That folder is now your second brain. Everything the agent writes lands there as markdown files. Make one note by hand Do this once before automating anything, so the mechanic is not abstract. Click the new-note icon, type a sentence, then type goals . The bracketed word becomes a link to a page called goals , whether or not that page exists yet. Click it and Obsidian creates the page. That is the entire data model: notes pointing at notes. Everything the agent does later is this, at volume, without you doing it. Where to put the vault Somewhere with a stable path you can type from a terminal. Avoid a folder your cloud sync client rewrites aggressively, because an agent writing files while a sync client rewrites them produces conflict copies that are genuinely painful to untangle. See git and sync git-and-sync.md for the options that work. Avoid spaces in the folder name. You will be pasting this path into commands. Settings worth changing now - Files and links \u2192 New link format: relative path or shortest path, consistently. Mixed link formats are the most common cause of broken links after a rename. - Files and links \u2192 Automatically update internal links: on. - Editor \u2192 Show frontmatter: on. You want to see the metadata the agent writes, at least for the first weeks. Next Claude Code in the vault claude-code-setup.md", "links": [{"to": "02-setup/git-and-sync", "label": "git and sync"}, {"to": "02-setup/claude-code-setup", "label": "Claude Code in the vault"}]}, {"id": "02-setup/claude-code-setup", "path": "docs/02-setup/claude-code-setup.md", "section": "02-setup", "section_title": "Setup", "title": "Claude Code in the vault", "html": "<p>Claude Code is the half that reads and writes. Two ways to run it, and the\nchoice only affects where you type, not what happens.</p>\n<h2 id=\"option-a-the-desktop-app\">Option A: the desktop app</h2>\n<p>Download Claude Desktop from <a href=\"https://claude.com/download\">claude.com/download</a>\nand sign in. The app has a <strong>Code</strong> tab, which is Claude Code without a\nterminal. If you have never used a command line, start here.</p>\n<h2 id=\"option-b-the-terminal\">Option B: the terminal</h2>\n<p>Install Claude Code and run <code>claude</code> from inside the vault folder:</p>\n<pre><code class=\"language-bash\">cd ~/brain\nclaude\n</code></pre>\n<p>Started this way, the agent reads and writes the vault directly through the\nfilesystem, with no plugin and no MCP server involved. This is the simplest\npossible setup and it is enough for everything in the ingestion, structuring\nand retrieval sections of this guide.</p>\n<p>Installation instructions for each platform are in the <a href=\"https://code.claude.com/docs/en/setup\">official setup\ndocs</a>.</p>\n<h2 id=\"option-c-inside-obsidian\">Option C: inside Obsidian</h2>\n<p>Community plugins now embed the agent in the editor, and they are heavily used:\n<a href=\"https://github.com/yishentu/claudian\">Claudian</a> sits above two million installs\nand <a href=\"https://github.com/logancyang/obsidian-copilot\">Copilot</a> is close behind.\nBoth run Claude Code, Codex or a local agent in a pane next to your notes.</p>\n<p>Worth knowing about because it removes the window switching entirely. Worth\nbeing careful with for the same reason this guide keeps ingestion on a\nschedule: an agent in the editor invites ad-hoc edits that never make it into\n<code>log.md</code>, and an unlogged vault is one you cannot audit.</p>\n<p>A reasonable split is the plugin for conversation and drafting, the terminal or\na scheduled task for anything that writes wiki pages.</p>\n<h2 id=\"plan-requirement\">Plan requirement</h2>\n<p>Claude Code needs a paid account: Pro, Max, Team, Enterprise, or a Console\naccount billed per token. The free Claude.ai plan does not include Claude Code\naccess, per Anthropic's own setup documentation. If the Code tab prompts you to\nupgrade, that is why.</p>\n<h2 id=\"filesystem-or-mcp\">Filesystem or MCP</h2>\n<p>Both work. The difference is narrow and worth knowing before you pick:</p>\n<table>\n<thead>\n<tr>\n<th></th>\n<th>Filesystem</th>\n<th>MCP</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>Setup</td>\n<td>none, just <code>cd</code> into the vault</td>\n<td>plugin plus a config command</td>\n</tr>\n<tr>\n<td>Obsidian open</td>\n<td>not required</td>\n<td>required, the plugin serves the API</td>\n</tr>\n<tr>\n<td>Scope</td>\n<td>whatever folder you started in</td>\n<td>the whole vault, from anywhere</td>\n</tr>\n<tr>\n<td>Failure mode</td>\n<td>none to speak of</td>\n<td>plugin off, app closed, wrong port</td>\n</tr>\n</tbody>\n</table>\n<p>Start on the filesystem. Move to <a href=\"mcp-obsidian.md\">MCP</a> when you want the agent\nto reach the vault from sessions that are not running inside it, which mostly\nmatters once you add scheduled tasks.</p>\n<h2 id=\"first-run\">First run</h2>\n<p>Point it at the structure before asking for anything else:</p>\n<pre><code>Read CLAUDE.md and wiki/index.md, then tell me what this vault currently\ncontains and what is missing.\n</code></pre>\n<p>The answer tells you immediately whether the agent understood its instructions.\nIf it starts inventing a structure you did not ask for, your <code>CLAUDE.md</code> is too\nvague. See <a href=\"claude-md.md\">writing your CLAUDE.md</a>.</p>\n<h2 id=\"permissions\">Permissions</h2>\n<p>The agent will ask before editing files. Grant it write access to the vault and\nnothing else. Do not grant blanket shell access on a folder that holds anything\nyou cannot lose, and read <a href=\"../06-agents/safety-and-guardrails.md\">guardrails</a>\nbefore you automate anything on a schedule.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"mcp-obsidian.md\">MCP for Obsidian</a></p>", "headings": ["Option A: the desktop app", "Option B: the terminal", "Option C: inside Obsidian", "Plan requirement", "Filesystem or MCP", "First run", "Permissions", "Next"], "words": 527, "text": "Claude Code is the half that reads and writes. Two ways to run it, and the choice only affects where you type, not what happens. Option A: the desktop app Download Claude Desktop from claude.com/download https://claude.com/download and sign in. The app has a Code tab, which is Claude Code without a terminal. If you have never used a command line, start here. Option B: the terminal Install Claude Code and run claude from inside the vault folder: bash cd ~/brain claude Started this way, the agent reads and writes the vault directly through the filesystem, with no plugin and no MCP server involved. This is the simplest possible setup and it is enough for everything in the ingestion, structuring and retrieval sections of this guide. Installation instructions for each platform are in the official setup docs https://code.claude.com/docs/en/setup . Option C: inside Obsidian Community plugins now embed the agent in the editor, and they are heavily used: Claudian https://github.com/yishentu/claudian sits above two million installs and Copilot https://github.com/logancyang/obsidian-copilot is close behind. Both run Claude Code, Codex or a local agent in a pane next to your notes. Worth knowing about because it removes the window switching entirely. Worth being careful with for the same reason this guide keeps ingestion on a schedule: an agent in the editor invites ad-hoc edits that never make it into log.md , and an unlogged vault is one you cannot audit. A reasonable split is the plugin for conversation and drafting, the terminal or a scheduled task for anything that writes wiki pages. Plan requirement Claude Code needs a paid account: Pro, Max, Team, Enterprise, or a Console account billed per token. The free Claude.ai plan does not include Claude Code access, per Anthropic's own setup documentation. If the Code tab prompts you to upgrade, that is why. Filesystem or MCP Both work. The difference is narrow and worth knowing before you pick: | | Filesystem | MCP | |---|---|---| | Setup | none, just cd into the vault | plugin plus a config command | | Obsidian open | not required | required, the plugin serves the API | | Scope | whatever folder you started in | the whole vault, from anywhere | | Failure mode | none to speak of | plugin off, app closed, wrong port | Start on the filesystem. Move to MCP mcp-obsidian.md when you want the agent to reach the vault from sessions that are not running inside it, which mostly matters once you add scheduled tasks. First run Point it at the structure before asking for anything else: Read CLAUDE.md and wiki/index.md, then tell me what this vault currently contains and what is missing. The answer tells you immediately whether the agent understood its instructions. If it starts inventing a structure you did not ask for, your CLAUDE.md is too vague. See writing your CLAUDE.md claude-md.md . Permissions The agent will ask before editing files. Grant it write access to the vault and nothing else. Do not grant blanket shell access on a folder that holds anything you cannot lose, and read guardrails ../06-agents/safety-and-guardrails.md before you automate anything on a schedule. Next MCP for Obsidian mcp-obsidian.md", "links": [{"to": "02-setup/mcp-obsidian", "label": "MCP"}, {"to": "02-setup/claude-md", "label": "writing your CLAUDE.md"}, {"to": "06-agents/safety-and-guardrails", "label": "guardrails"}, {"to": "02-setup/mcp-obsidian", "label": "MCP for Obsidian"}]}, {"id": "02-setup/mcp-obsidian", "path": "docs/02-setup/mcp-obsidian.md", "section": "02-setup", "section_title": "Setup", "title": "MCP for Obsidian", "html": "<p>MCP is the standard way Claude talks to other applications. For a vault, it\nadds a door into Obsidian itself rather than into the folder underneath, which\nmeans the agent can work with the vault from any session, not only one started\ninside that directory.</p>\n<p>You do not need this to start. Add it when you want scheduled tasks, or when\nyou are working from the desktop app rather than a terminal in the vault.</p>\n<h2 id=\"two-routes\">Two routes</h2>\n<p>The <a href=\"https://github.com/coddingtonbear/obsidian-local-rest-api\">Local REST API\nplugin</a> now ships a\nbuilt-in MCP server at <code>/mcp/</code>, so a separate server is no longer required.\nCheck its README first: if the built-in server covers what you need, skip\nstraight to registering it with your client and ignore step 2 below.</p>\n<p>The third-party route described here, <code>mcp-obsidian</code> over the plugin's REST API,\nis still the most widely documented and is what most guides describe. Both end\nup in the same place.</p>\n<h2 id=\"step-1-enable-the-plugin\">Step 1: enable the plugin</h2>\n<p>In Obsidian: <strong>Settings</strong> (gear, bottom left) \u2192 <strong>Community plugins</strong> \u2192 <strong>Turn\non community plugins</strong> \u2192 <strong>Browse</strong> \u2192 search <code>Local REST API</code> \u2192 <strong>Install</strong> \u2192\n<strong>Enable</strong>.</p>\n<p>Open the plugin's settings. There is an <strong>API Key</strong>, a long string of letters\nand numbers. Copy it.</p>\n<p>Obsidian displays the key with the word <code>Bearer</code> in front of it. That word is\nnot part of the key. Copy only the string after it. This is the single most\ncommon reason the connection fails on the first try.</p>\n<h2 id=\"step-2-register-the-server\">Step 2: register the server</h2>\n<p>In the Claude Code tab or terminal, with your key pasted in place of\n<code>PASTE-YOUR-KEY-HERE</code>:</p>\n<pre><code class=\"language-bash\">claude mcp add-json obsidian-vault '{\n "type": "stdio",\n "command": "uvx",\n "args": ["mcp-obsidian"],\n "env": {\n "OBSIDIAN_API_KEY": "PASTE-YOUR-KEY-HERE",\n "OBSIDIAN_HOST": "127.0.0.1",\n "OBSIDIAN_PORT": "27124"\n }\n}'\n</code></pre>\n<p><code>uvx</code> runs the server without a permanent install. If the command is not found,\ninstall <code>uv</code> first.</p>\n<h2 id=\"step-3-test-it\">Step 3: test it</h2>\n<pre><code>List every file in my Obsidian vault.\n</code></pre>\n<p>If the agent reads your notes back, the connection works.</p>\n<h2 id=\"when-it-does-not-work\">When it does not work</h2>\n<ul>\n<li><strong>Obsidian is closed.</strong> The plugin serves the API from inside the app, so the\n connection only exists while Obsidian is running.</li>\n<li><strong><code>Bearer</code> in the key.</strong> Strip it.</li>\n<li><strong>Wrong port.</strong> Check the port shown in the plugin settings against the value\n in your config. The default is 27124.</li>\n<li><strong>Plugin disabled.</strong> Community plugins get turned off when restricted mode is\n re-enabled after an update.</li>\n</ul>\n<h2 id=\"do-you-need-this-at-all\">Do you need this at all</h2>\n<p>One maintained fork of <code>mcp-obsidian</code> was archived with the reasoning that\nrouting through a REST plugin adds complexity when a vault is just markdown\nfiles on disk. That is the same argument this guide makes for starting on the\nfilesystem, and it is worth taking seriously: MCP earns its place when you need\nthe vault reachable from sessions not running inside it, and not before.</p>\n<h2 id=\"security\">Security</h2>\n<p>This opens a local HTTP server with a key that grants full read and write access\nto your notes. Keep it on <code>127.0.0.1</code>, never expose the port, and treat the key\nlike a password. If you paste it anywhere public, rotate it in the plugin\nsettings.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"claude-md.md\">Writing your CLAUDE.md</a></p>", "headings": ["Two routes", "Step 1: enable the plugin", "Step 2: register the server", "Step 3: test it", "When it does not work", "Do you need this at all", "Security", "Next"], "words": 525, "text": "MCP is the standard way Claude talks to other applications. For a vault, it adds a door into Obsidian itself rather than into the folder underneath, which means the agent can work with the vault from any session, not only one started inside that directory. You do not need this to start. Add it when you want scheduled tasks, or when you are working from the desktop app rather than a terminal in the vault. Two routes The Local REST API plugin https://github.com/coddingtonbear/obsidian-local-rest-api now ships a built-in MCP server at /mcp/ , so a separate server is no longer required. Check its README first: if the built-in server covers what you need, skip straight to registering it with your client and ignore step 2 below. The third-party route described here, mcp-obsidian over the plugin's REST API, is still the most widely documented and is what most guides describe. Both end up in the same place. Step 1: enable the plugin In Obsidian: Settings gear, bottom left \u2192 Community plugins \u2192 Turn on community plugins \u2192 Browse \u2192 search Local REST API \u2192 Install \u2192 Enable . Open the plugin's settings. There is an API Key , a long string of letters and numbers. Copy it. Obsidian displays the key with the word Bearer in front of it. That word is not part of the key. Copy only the string after it. This is the single most common reason the connection fails on the first try. Step 2: register the server In the Claude Code tab or terminal, with your key pasted in place of PASTE-YOUR-KEY-HERE : bash claude mcp add-json obsidian-vault '{ \"type\": \"stdio\", \"command\": \"uvx\", \"args\": \"mcp-obsidian\" , \"env\": { \"OBSIDIAN_API_KEY\": \"PASTE-YOUR-KEY-HERE\", \"OBSIDIAN_HOST\": \"127.0.0.1\", \"OBSIDIAN_PORT\": \"27124\" } }' uvx runs the server without a permanent install. If the command is not found, install uv first. Step 3: test it List every file in my Obsidian vault. If the agent reads your notes back, the connection works. When it does not work - Obsidian is closed. The plugin serves the API from inside the app, so the connection only exists while Obsidian is running. - Bearer in the key. Strip it. - Wrong port. Check the port shown in the plugin settings against the value in your config. The default is 27124. - Plugin disabled. Community plugins get turned off when restricted mode is re-enabled after an update. Do you need this at all One maintained fork of mcp-obsidian was archived with the reasoning that routing through a REST plugin adds complexity when a vault is just markdown files on disk. That is the same argument this guide makes for starting on the filesystem, and it is worth taking seriously: MCP earns its place when you need the vault reachable from sessions not running inside it, and not before. Security This opens a local HTTP server with a key that grants full read and write access to your notes. Keep it on 127.0.0.1 , never expose the port, and treat the key like a password. If you paste it anywhere public, rotate it in the plugin settings. Next Writing your CLAUDE.md claude-md.md", "links": [{"to": "02-setup/claude-md", "label": "Writing your CLAUDE.md"}]}, {"id": "02-setup/claude-md", "path": "docs/02-setup/claude-md.md", "section": "02-setup", "section_title": "Setup", "title": "Writing your CLAUDE.md", "html": "<p><code>CLAUDE.md</code> at the vault root is the file the agent reads at the start of every\nsession. It is the difference between an assistant that knows your situation and\none you brief from scratch every time.</p>\n<p>An empty vault with a good <code>CLAUDE.md</code> is more useful than a full vault without\none, because context about you shapes every page the agent writes afterwards.</p>\n<h2 id=\"do-not-type-it-get-interviewed\">Do not type it, get interviewed</h2>\n<p>Writing this file cold produces a thin, generic version. Answering questions\nproduces a specific one. Paste this into the agent:</p>\n<pre><code>You are setting up my second brain. Interview me ONE question at a time to\nbuild my profile. Ask about: who I am and what I do, my goals for this year,\nhow I want you to talk to me, my strengths and weaknesses, and my current\nprojects. Wait for each answer before the next question. When finished, write\neverything into CLAUDE.md at the vault root, structured with headers.\n</code></pre>\n<p>Answer as if briefing a co-founder on their first day. Vague answers produce a\nvague file, and every session inherits it.</p>\n<h2 id=\"what-belongs-in-it\">What belongs in it</h2>\n<ul>\n<li><strong>Who you are and what you work on.</strong> Enough that a stranger could act on it.</li>\n<li><strong>Goals with a horizon.</strong> This year, this quarter. Undated goals age badly.</li>\n<li><strong>How to talk to you.</strong> Length, tone, how much pushback you want.</li>\n<li><strong>Your strengths and weak spots.</strong> This is what lets the agent know when to\n challenge you rather than agree.</li>\n<li><strong>Current projects,</strong> one line each, linked to their folders.</li>\n<li><strong>The vault's own rules:</strong> folder layout, page contracts, linking rules. The\n version in <a href=\"../../vault-template/CLAUDE.md\"><code>vault-template/CLAUDE.md</code></a> is a\n working starting point.</li>\n</ul>\n<h2 id=\"what-does-not-belong-in-it\">What does not belong in it</h2>\n<ul>\n<li>Anything that changes weekly. That goes in the project files.</li>\n<li>Long explanations of things the model already knows.</li>\n<li>Credentials of any kind.</li>\n<li>Aspirational statements you will not act on. The agent takes them literally.</li>\n</ul>\n<h2 id=\"two-levels\">Two levels</h2>\n<p>The root <code>CLAUDE.md</code> is the strategy layer: who you are, what you are aiming\nat, how the vault works. Each project folder gets its own <code>CLAUDE.md</code> covering\nthat project only. When you open a project as its own vault, the agent reads\njust that one and stops carrying your entire life into every task. See\n<a href=\"project-scoping.md\">project scoping</a>.</p>\n<h2 id=\"iterate-on-it\">Iterate on it</h2>\n<p>When the agent does something wrong twice, that is a <code>CLAUDE.md</code> problem, not a\nprompting problem. Add the rule, with the reason attached, because a rule\nwithout a reason gets applied too literally in the cases you did not anticipate.</p>\n<p>Re-read the file monthly. Goals move, projects close, and a stale profile\nquietly degrades everything the agent writes.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"vault-structure.md\">Vault structure</a></p>", "headings": ["Do not type it, get interviewed", "What belongs in it", "What does not belong in it", "Two levels", "Iterate on it", "Next"], "words": 451, "text": "CLAUDE.md at the vault root is the file the agent reads at the start of every session. It is the difference between an assistant that knows your situation and one you brief from scratch every time. An empty vault with a good CLAUDE.md is more useful than a full vault without one, because context about you shapes every page the agent writes afterwards. Do not type it, get interviewed Writing this file cold produces a thin, generic version. Answering questions produces a specific one. Paste this into the agent: You are setting up my second brain. Interview me ONE question at a time to build my profile. Ask about: who I am and what I do, my goals for this year, how I want you to talk to me, my strengths and weaknesses, and my current projects. Wait for each answer before the next question. When finished, write everything into CLAUDE.md at the vault root, structured with headers. Answer as if briefing a co-founder on their first day. Vague answers produce a vague file, and every session inherits it. What belongs in it - Who you are and what you work on. Enough that a stranger could act on it. - Goals with a horizon. This year, this quarter. Undated goals age badly. - How to talk to you. Length, tone, how much pushback you want. - Your strengths and weak spots. This is what lets the agent know when to challenge you rather than agree. - Current projects, one line each, linked to their folders. - The vault's own rules: folder layout, page contracts, linking rules. The version in vault-template/CLAUDE.md ../../vault-template/CLAUDE.md is a working starting point. What does not belong in it - Anything that changes weekly. That goes in the project files. - Long explanations of things the model already knows. - Credentials of any kind. - Aspirational statements you will not act on. The agent takes them literally. Two levels The root CLAUDE.md is the strategy layer: who you are, what you are aiming at, how the vault works. Each project folder gets its own CLAUDE.md covering that project only. When you open a project as its own vault, the agent reads just that one and stops carrying your entire life into every task. See project scoping project-scoping.md . Iterate on it When the agent does something wrong twice, that is a CLAUDE.md problem, not a prompting problem. Add the rule, with the reason attached, because a rule without a reason gets applied too literally in the cases you did not anticipate. Re-read the file monthly. Goals move, projects close, and a stale profile quietly degrades everything the agent writes. Next Vault structure vault-structure.md", "links": [{"to": "02-setup/project-scoping", "label": "project scoping"}, {"to": "02-setup/vault-structure", "label": "Vault structure"}]}, {"id": "02-setup/vault-structure", "path": "docs/02-setup/vault-structure.md", "section": "02-setup", "section_title": "Setup", "title": "Vault structure", "html": "<p>The vault does two different jobs, and they want different shapes. Keeping them\nin one folder tree while keeping the shapes separate is what makes the system\nhold up past the first month.</p>\n<p><strong>The knowledge layer</strong> is what you have read and understood. It grows forever\nand it is organised by idea.</p>\n<p><strong>The project layer</strong> is what you are working on now. It is organised by\npipeline and most of it goes cold when the project ships.</p>\n<pre><code>brain/\n CLAUDE.md who you are, how the vault works\n raw/ source material, never edited after it lands\n assets/\n wiki/ the knowledge layer\n sources/ one page per ingested item\n entities/ people, organisations, products, tools\n concepts/ ideas, methods, frameworks\n synthesis/ comparisons, themes, open questions\n index.md catalog of every page\n log.md what the agent did, chronologically\n projects/ the project layer\n youtube-channel/\n CLAUDE.md this project only\n Inputs/ ideas, briefs, raw material\n Process/ work in progress\n Outputs/ finished work\n Feedback/ results, metrics, what happened\n output/ generated reports and drafts\n</code></pre>\n<h2 id=\"why-the-split\">Why the split</h2>\n<p>A project pipeline answers \"what am I doing this week\". A wiki answers \"what do\nI know about X\". Force one structure to do both and you get either a knowledge\nbase full of dead task folders, or projects buried under conceptual pages\nnobody opens while working.</p>\n<p>They connect through links. A project page links to the concepts it depends on;\nconcept pages accumulate references from the projects that used them. That is\nwhere the compounding shows up: the second time you start a project in a domain,\nthe knowledge layer already has it.</p>\n<h2 id=\"set-the-projects-up-by-asking\">Set the projects up by asking</h2>\n<pre><code>Create a project folder in my vault called youtube-channel. Inside it, create\nfour folders: Inputs, Process, Outputs, Feedback. Then write a CLAUDE.md inside\nthat project folder describing what this project is, its one goal, and your\nspecific role in helping me hit it. Interview me if you need details.\n</code></pre>\n<p>Repeat per area: content, finances, clients. One goal per project, stated in\nthe project's own <code>CLAUDE.md</code>. Projects with three goals produce work that\nserves none of them.</p>\n<h2 id=\"rules-that-keep-it-working\">Rules that keep it working</h2>\n<ul>\n<li><strong>Never edit <code>raw/</code>.</strong> It is the archive. If a source is wrong, replace the\n file and re-ingest, so it stays a faithful record of what you actually saved.</li>\n<li><strong>Do not nest deeply.</strong> Folders four levels down stop getting opened. The\n graph is the navigation, not the tree.</li>\n<li><strong>Everything the agent generates for outside use goes to <code>output/</code> or the\n project's <code>Outputs/</code>,</strong> never loose in the vault root.</li>\n</ul>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"project-scoping.md\">Project scoping</a></p>", "headings": ["Why the split", "Set the projects up by asking", "Rules that keep it working", "Next"], "words": 426, "text": "The vault does two different jobs, and they want different shapes. Keeping them in one folder tree while keeping the shapes separate is what makes the system hold up past the first month. The knowledge layer is what you have read and understood. It grows forever and it is organised by idea. The project layer is what you are working on now. It is organised by pipeline and most of it goes cold when the project ships. brain/ CLAUDE.md who you are, how the vault works raw/ source material, never edited after it lands assets/ wiki/ the knowledge layer sources/ one page per ingested item entities/ people, organisations, products, tools concepts/ ideas, methods, frameworks synthesis/ comparisons, themes, open questions index.md catalog of every page log.md what the agent did, chronologically projects/ the project layer youtube-channel/ CLAUDE.md this project only Inputs/ ideas, briefs, raw material Process/ work in progress Outputs/ finished work Feedback/ results, metrics, what happened output/ generated reports and drafts Why the split A project pipeline answers \"what am I doing this week\". A wiki answers \"what do I know about X\". Force one structure to do both and you get either a knowledge base full of dead task folders, or projects buried under conceptual pages nobody opens while working. They connect through links. A project page links to the concepts it depends on; concept pages accumulate references from the projects that used them. That is where the compounding shows up: the second time you start a project in a domain, the knowledge layer already has it. Set the projects up by asking Create a project folder in my vault called youtube-channel. Inside it, create four folders: Inputs, Process, Outputs, Feedback. Then write a CLAUDE.md inside that project folder describing what this project is, its one goal, and your specific role in helping me hit it. Interview me if you need details. Repeat per area: content, finances, clients. One goal per project, stated in the project's own CLAUDE.md . Projects with three goals produce work that serves none of them. Rules that keep it working - Never edit raw/ . It is the archive. If a source is wrong, replace the file and re-ingest, so it stays a faithful record of what you actually saved. - Do not nest deeply. Folders four levels down stop getting opened. The graph is the navigation, not the tree. - Everything the agent generates for outside use goes to output/ or the project's Outputs/ , never loose in the vault root. Next Project scoping project-scoping.md", "links": [{"to": "02-setup/project-scoping", "label": "Project scoping"}]}, {"id": "02-setup/project-scoping", "path": "docs/02-setup/project-scoping.md", "section": "02-setup", "section_title": "Setup", "title": "Project scoping", "html": "<p>This is the step that most setups skip and then wonder why output quality drops\nas the vault grows.</p>\n<p>When the agent is pointed at the whole vault, every task competes with\neverything you have ever saved. It reads a root <code>CLAUDE.md</code> covering your entire\nlife, plus whatever else it decides is relevant. Answers get broader and\nshallower.</p>\n<p>When it is pointed at one project, it reads that project's <code>CLAUDE.md</code>, sees\nthat project's files, and does the job in front of it.</p>\n<h2 id=\"how-to-scope\">How to scope</h2>\n<p>In Obsidian, click the vault name in the bottom left, then:</p>\n<p><strong>Manage vaults \u2192 Open folder as a vault \u2192 pick your project folder \u2192 Trust</strong></p>\n<p>From a terminal, the same thing is just:</p>\n<pre><code class=\"language-bash\">cd ~/brain/projects/youtube-channel\nclaude\n</code></pre>\n<p>The agent now reads only that project's instructions.</p>\n<h2 id=\"when-to-use-which\">When to use which</h2>\n<p><strong>The full vault</strong> for anything that spans domains: planning, review, asking\nwhat you know about a topic, weekly maintenance, ingestion. The knowledge layer\nis the whole point of a wide view.</p>\n<p><strong>A single project</strong> for producing anything: drafting, building, analysing this\nweek's numbers. Narrow context, one goal, no drift.</p>\n<p>The rough rule: the full vault plans, a single project ships.</p>\n<h2 id=\"passing-knowledge-into-a-project\">Passing knowledge into a project</h2>\n<p>Scoping down cuts the agent off from the wiki, which is usually what you want\nand occasionally not. Two ways to bridge it:</p>\n<ul>\n<li>Link the relevant concept pages from the project's <code>CLAUDE.md</code>, and copy the\n handful that genuinely matter into the project's <code>Inputs/</code>.</li>\n<li>Or run the research question against the full vault first, save the answer\n into the project's <code>Inputs/</code>, then scope down and work.</li>\n</ul>\n<p>The second is better. It keeps the decision about what matters with you, which\nis the part you should not be delegating.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"live-data.md\">Live data connectors</a></p>", "headings": ["How to scope", "When to use which", "Passing knowledge into a project", "Next"], "words": 298, "text": "This is the step that most setups skip and then wonder why output quality drops as the vault grows. When the agent is pointed at the whole vault, every task competes with everything you have ever saved. It reads a root CLAUDE.md covering your entire life, plus whatever else it decides is relevant. Answers get broader and shallower. When it is pointed at one project, it reads that project's CLAUDE.md , sees that project's files, and does the job in front of it. How to scope In Obsidian, click the vault name in the bottom left, then: Manage vaults \u2192 Open folder as a vault \u2192 pick your project folder \u2192 Trust From a terminal, the same thing is just: bash cd ~/brain/projects/youtube-channel claude The agent now reads only that project's instructions. When to use which The full vault for anything that spans domains: planning, review, asking what you know about a topic, weekly maintenance, ingestion. The knowledge layer is the whole point of a wide view. A single project for producing anything: drafting, building, analysing this week's numbers. Narrow context, one goal, no drift. The rough rule: the full vault plans, a single project ships. Passing knowledge into a project Scoping down cuts the agent off from the wiki, which is usually what you want and occasionally not. Two ways to bridge it: - Link the relevant concept pages from the project's CLAUDE.md , and copy the handful that genuinely matter into the project's Inputs/ . - Or run the research question against the full vault first, save the answer into the project's Inputs/ , then scope down and work. The second is better. It keeps the decision about what matters with you, which is the part you should not be delegating. Next Live data connectors live-data.md", "links": [{"to": "02-setup/live-data", "label": "Live data connectors"}]}, {"id": "02-setup/live-data", "path": "docs/02-setup/live-data.md", "section": "02-setup", "section_title": "Setup", "title": "Live data connectors", "html": "<p>Static notes are half a brain. The other half is what is changing: your\ncalendar, your inbox, the channels where decisions actually get made.</p>\n<p>MCP connects those the same way it connects Obsidian.</p>\n<h2 id=\"calendar\">Calendar</h2>\n<pre><code class=\"language-bash\">claude mcp add google-workspace uvx workspace-mcp --tools calendar\n</code></pre>\n<p>An OAuth sign-in opens in the browser. Grant read access.</p>\n<p>Then the vault can act on it:</p>\n<pre><code>Read my calendar for today, log what I committed to in each meeting into my\ntasks project, and flag anything without a clear next step.\n</code></pre>\n<p>Email, Slack and Notion connect through their own MCP servers, registered the\nsame way.</p>\n<h2 id=\"grant-read-not-write\">Grant read, not write</h2>\n<p>Give every connector the narrowest scope that does the job, and prefer read-only\nwherever the option exists. The brain should read your data, not delete it or\nsend things on your behalf.</p>\n<h2 id=\"the-rule-that-matters-most\">The rule that matters most</h2>\n<p><strong>Keys, not prompts.</strong></p>\n<p>Telling an agent \"do not delete this\" is a suggestion. It is not a safety\nsetting. If the agent technically can delete a file, empty a folder or send an\nemail, then one day, in some context you did not predict, it will.</p>\n<p>Control what is possible at the permission level: read-only tokens, scoped keys,\nseparate credentials per connector. Then the instruction in your <code>CLAUDE.md</code> is\na preference on top of a boundary, rather than the only thing standing between\nyour inbox and a bad run.</p>\n<p>This applies to your own vault too. See\n<a href=\"../06-agents/safety-and-guardrails.md\">guardrails</a>.</p>\n<h2 id=\"what-is-worth-connecting\">What is worth connecting</h2>\n<p>Connect the sources where decisions and commitments live: calendar first, then\nwhichever of email or chat you actually use for work.</p>\n<p>Skip the ones that produce volume without signal. A connector that floods the\nvault with notifications makes every future query worse, because the agent has\nto read past all of it.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"obsidian-plugins.md\">Plugins worth installing</a></p>", "headings": ["Calendar", "Grant read, not write", "The rule that matters most", "What is worth connecting", "Next"], "words": 306, "text": "Static notes are half a brain. The other half is what is changing: your calendar, your inbox, the channels where decisions actually get made. MCP connects those the same way it connects Obsidian. Calendar bash claude mcp add google-workspace uvx workspace-mcp --tools calendar An OAuth sign-in opens in the browser. Grant read access. Then the vault can act on it: Read my calendar for today, log what I committed to in each meeting into my tasks project, and flag anything without a clear next step. Email, Slack and Notion connect through their own MCP servers, registered the same way. Grant read, not write Give every connector the narrowest scope that does the job, and prefer read-only wherever the option exists. The brain should read your data, not delete it or send things on your behalf. The rule that matters most Keys, not prompts. Telling an agent \"do not delete this\" is a suggestion. It is not a safety setting. If the agent technically can delete a file, empty a folder or send an email, then one day, in some context you did not predict, it will. Control what is possible at the permission level: read-only tokens, scoped keys, separate credentials per connector. Then the instruction in your CLAUDE.md is a preference on top of a boundary, rather than the only thing standing between your inbox and a bad run. This applies to your own vault too. See guardrails ../06-agents/safety-and-guardrails.md . What is worth connecting Connect the sources where decisions and commitments live: calendar first, then whichever of email or chat you actually use for work. Skip the ones that produce volume without signal. A connector that floods the vault with notifications makes every future query worse, because the agent has to read past all of it. Next Plugins worth installing obsidian-plugins.md", "links": [{"to": "06-agents/safety-and-guardrails", "label": "guardrails"}, {"to": "02-setup/obsidian-plugins", "label": "Plugins worth installing"}]}, {"id": "02-setup/obsidian-plugins", "path": "docs/02-setup/obsidian-plugins.md", "section": "02-setup", "section_title": "Setup", "title": "Plugins worth installing", "html": "<p>Obsidian works fine with none of these. Add them when you hit the specific\nproblem each one solves.</p>\n<h2 id=\"local-rest-api\">Local REST API</h2>\n<p>Required only for the <a href=\"mcp-obsidian.md\">MCP path</a>. Serves your vault over a\nlocal HTTP API so the agent can reach it while Obsidian is open, from any\nsession.</p>\n<h2 id=\"dataview\">Dataview</h2>\n<p>Queries over frontmatter, rendered inside a note. Worth it once you have enough\npages to want dashboards:</p>\n<pre><code>```dataview\nTABLE updated, tags\nFROM "wiki/concepts"\nWHERE updated < date(today) - dur(90 days)\nSORT updated ASC\n```\n</code></pre>\n<p>That one lists concept pages nobody has touched in three months, which is the\nmost useful review query in the vault.</p>\n<h2 id=\"templater\">Templater</h2>\n<p>Templates with variables and dates, for the page shapes in\n<a href=\"../../vault-template/templates/\"><code>vault-template/templates/</code></a>. Useful for the\nnotes you write by hand. The agent does not need it, it writes frontmatter\ndirectly.</p>\n<h2 id=\"worth-adding-later\">Worth adding later</h2>\n<ul>\n<li><strong><a href=\"https://github.com/Vinzent03/obsidian-git\">Git</a></strong>, the third most installed\n plugin in the catalog. Commits from inside Obsidian, which pairs with\n <a href=\"../09-maintenance/versioning-with-git.md\">versioning</a>.</li>\n<li><strong><a href=\"https://github.com/obsidianmd/obsidian-importer\">Importer</a></strong>, official,\n pulls in Notion, Evernote, Roam, Bear and Apple Notes. The first step if you\n are migrating an existing pile.</li>\n<li><strong><a href=\"https://github.com/Vinzent03/find-unlinked-files\">Find orphaned files and broken links</a></strong>,\n the same checks as <a href=\"../09-maintenance/lint-and-health.md\">lint</a> without leaving\n the app.</li>\n<li><strong><a href=\"https://github.com/scambier/obsidian-omnisearch\">Omnisearch</a></strong> for better\n full-text search, including inside PDFs.</li>\n</ul>\n<p>Full ranked list with install counts:\n<a href=\"../../resources/plugins.md\">resources/plugins.md</a>.</p>\n<h2 id=\"what-to-avoid\">What to avoid</h2>\n<p>Plugins that rewrite files in the background. Anything that auto-formats,\nauto-sorts frontmatter, or renames on a schedule will fight the agent, and you\nwill spend an evening working out which of the two mangled a page.</p>\n<p>Also avoid heavy graph or dashboard plugins until you have material worth\nlooking at. An empty vault with fifteen plugins is a procrastination artifact,\nnot a system.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"git-and-sync.md\">Git, sync and backups</a></p>", "headings": ["Local REST API", "Dataview", "Templater", "Worth adding later", "What to avoid", "Next"], "words": 288, "text": "Obsidian works fine with none of these. Add them when you hit the specific problem each one solves. Local REST API Required only for the MCP path mcp-obsidian.md . Serves your vault over a local HTTP API so the agent can reach it while Obsidian is open, from any session. Dataview Queries over frontmatter, rendered inside a note. Worth it once you have enough pages to want dashboards: dataview TABLE updated, tags FROM \"wiki/concepts\" WHERE updated < date today - dur 90 days SORT updated ASC That one lists concept pages nobody has touched in three months, which is the most useful review query in the vault. Templater Templates with variables and dates, for the page shapes in vault-template/templates/ ../../vault-template/templates/ . Useful for the notes you write by hand. The agent does not need it, it writes frontmatter directly. Worth adding later - Git https://github.com/Vinzent03/obsidian-git , the third most installed plugin in the catalog. Commits from inside Obsidian, which pairs with versioning ../09-maintenance/versioning-with-git.md . - Importer https://github.com/obsidianmd/obsidian-importer , official, pulls in Notion, Evernote, Roam, Bear and Apple Notes. The first step if you are migrating an existing pile. - Find orphaned files and broken links https://github.com/Vinzent03/find-unlinked-files , the same checks as lint ../09-maintenance/lint-and-health.md without leaving the app. - Omnisearch https://github.com/scambier/obsidian-omnisearch for better full-text search, including inside PDFs. Full ranked list with install counts: resources/plugins.md ../../resources/plugins.md . What to avoid Plugins that rewrite files in the background. Anything that auto-formats, auto-sorts frontmatter, or renames on a schedule will fight the agent, and you will spend an evening working out which of the two mangled a page. Also avoid heavy graph or dashboard plugins until you have material worth looking at. An empty vault with fifteen plugins is a procrastination artifact, not a system. Next Git, sync and backups git-and-sync.md", "links": [{"to": "02-setup/mcp-obsidian", "label": "MCP path"}, {"to": "09-maintenance/versioning-with-git", "label": "versioning"}, {"to": "09-maintenance/lint-and-health", "label": "lint"}, {"to": "02-setup/git-and-sync", "label": "Git, sync and backups"}]}, {"id": "02-setup/git-and-sync", "path": "docs/02-setup/git-and-sync.md", "section": "02-setup", "section_title": "Setup", "title": "Git, sync and backups", "html": "<p>A vault is a folder of text files, which makes it close to an ideal git\nrepository, and git is what makes an agent safe to run unattended.</p>\n<p>Without version control, a bad run is a mystery. With it, every change the agent\nmade is a diff you can read and revert in one command.</p>\n<pre><code class=\"language-bash\">cd ~/brain\ngit init\ngit add .\ngit commit -m "initial vault"\n</code></pre>\n<h2 id=\"what-to-ignore\">What to ignore</h2>\n<pre><code>.obsidian/workspace*\n.obsidian/cache\n.DS_Store\n.trash/\n</code></pre>\n<p>Commit the rest of <code>.obsidian/</code>, so your plugin list and settings travel with\nthe vault. Never commit API keys; the Local REST API key lives in plugin data,\nso check what <code>.obsidian/plugins/</code> contains before the first push.</p>\n<p>If any part of the vault is private, keep the remote private. A second brain is\none of the highest-signal documents about a person that exists.</p>\n<h2 id=\"commit-around-agent-runs\">Commit around agent runs</h2>\n<p>Commit before a big ingest and after it. Then a bad batch is\n<code>git checkout .</code> rather than an afternoon of manual repair. Scheduled tasks\nshould commit their own work with a message naming the run, so the history stays\nreadable months later.</p>\n<h2 id=\"sync-across-machines\">Sync across machines</h2>\n<ul>\n<li><strong>Git remote:</strong> free, versioned, works everywhere, needs a pull and push\n habit.</li>\n<li><strong>Obsidian Sync:</strong> paid, end-to-end encrypted, handles mobile properly.</li>\n<li><strong>Generic cloud drives:</strong> work, with a caveat. A sync client rewriting files\n while an agent writes them produces conflict copies. If you go this route,\n keep long-running agent work to one machine.</li>\n</ul>\n<h2 id=\"backups\">Backups</h2>\n<p>Sync is not backup. Sync propagates a bad delete to every device.</p>\n<p>Keep one copy that is not connected to the sync path: a periodic archive to\nexternal storage or a separate remote. Test a restore once, before you need it.\nThe failure mode you are protecting against is not disk death, it is an\nautomation that quietly rewrote two hundred pages three weeks ago.</p>\n<h2 id=\"next\">Next</h2>\n<p>The vault is set up. Go to <a href=\"../03-ingestion/README.md\">Ingestion</a> to start\nfeeding it, or <a href=\"../04-structuring/README.md\">Structuring</a> for the rules that\ndecide what the pages look like.</p>", "headings": ["What to ignore", "Commit around agent runs", "Sync across machines", "Backups", "Next"], "words": 342, "text": "A vault is a folder of text files, which makes it close to an ideal git repository, and git is what makes an agent safe to run unattended. Without version control, a bad run is a mystery. With it, every change the agent made is a diff you can read and revert in one command. bash cd ~/brain git init git add . git commit -m \"initial vault\" What to ignore .obsidian/workspace .obsidian/cache .DS_Store .trash/ Commit the rest of .obsidian/ , so your plugin list and settings travel with the vault. Never commit API keys; the Local REST API key lives in plugin data, so check what .obsidian/plugins/ contains before the first push. If any part of the vault is private, keep the remote private. A second brain is one of the highest-signal documents about a person that exists. Commit around agent runs Commit before a big ingest and after it. Then a bad batch is git checkout . rather than an afternoon of manual repair. Scheduled tasks should commit their own work with a message naming the run, so the history stays readable months later. Sync across machines - Git remote: free, versioned, works everywhere, needs a pull and push habit. - Obsidian Sync: paid, end-to-end encrypted, handles mobile properly. - Generic cloud drives: work, with a caveat. A sync client rewriting files while an agent writes them produces conflict copies. If you go this route, keep long-running agent work to one machine. Backups Sync is not backup. Sync propagates a bad delete to every device. Keep one copy that is not connected to the sync path: a periodic archive to external storage or a separate remote. Test a restore once, before you need it. The failure mode you are protecting against is not disk death, it is an automation that quietly rewrote two hundred pages three weeks ago. Next The vault is set up. Go to Ingestion ../03-ingestion/README.md to start feeding it, or Structuring ../04-structuring/README.md for the rules that decide what the pages look like.", "links": []}, {"id": "03-ingestion/web-clipper", "path": "docs/03-ingestion/web-clipper.md", "section": "03-ingestion", "section_title": "Ingestion", "title": "Web articles", "html": "<p>Articles are the bulk of what most people save, and the browser is where the\ndecision to save happens. Anything that requires switching windows loses.</p>\n<h2 id=\"obsidian-web-clipper\">Obsidian Web Clipper</h2>\n<p>The <a href=\"https://obsidian.md/clipper\">official extension</a> from the Obsidian team.\nChrome, Firefox, Safari, Edge, Brave and Arc. It extracts the readable content\nof a page using Mozilla Readability, the same engine behind Firefox Reader View,\nand saves it as markdown straight into your vault.</p>\n<p>Install it, open the settings, and set the destination folder to <code>raw/</code>.</p>\n<h2 id=\"template\">Template</h2>\n<p>The default template saves the page body. Add frontmatter so the agent knows\nwhat it is holding without re-reading the whole file:</p>\n<pre><code>---\ntitle: {{title}}\nsource: {{url}}\nauthor: {{author}}\npublished: {{published}}\nclipped: {{date}}\ntype: article\n---\n\n{{content}}\n</code></pre>\n<p><code>{{author}}</code> and <code>{{published}}</code> come back empty on plenty of sites. That is\nfine, an empty field is better than a guessed one, and the agent handles the\ngap by saying the source is undated rather than inventing a date.</p>\n<h2 id=\"what-to-clip\">What to clip</h2>\n<p>Clip what you would want to find again in a year: primary sources, engineering\nposts, papers, documentation, arguments you disagree with and want to answer\nlater.</p>\n<p>Skip news that will be stale in a week, listicles, and anything you are saving\nout of guilt. Every low-value page you ingest costs twice: once at ingest, and\nagain every time the agent reads past it looking for something else.</p>\n<p>The honest test at clip time is whether you can name what you would ask this\nsource later. If you cannot, do not clip it.</p>\n<h2 id=\"awkward-pages\">Awkward pages</h2>\n<ul>\n<li><strong>Paywalls.</strong> The clipper saves what the browser rendered. If you can read it,\n it can save it. If you cannot, it saves the paywall notice, so check before\n moving on.</li>\n<li><strong>Documentation sites.</strong> Clipping page by page is a losing game. Save the\n entry point and let the agent fetch the rest, or clone the docs repo into\n <code>raw/</code> if it is open source.</li>\n<li><strong>Single-page apps and dynamic content.</strong> Readability sometimes returns a\n fragment. Look at the file before ingest.</li>\n<li><strong>Threads and comment sections.</strong> The value is usually in the replies, which\n the clipper drops. Copy the thread manually or screenshot it into\n <code>raw/assets/</code>.</li>\n</ul>\n<h2 id=\"clip-now-ingest-later\">Clip now, ingest later</h2>\n<p>Clipping and ingesting are separate steps on purpose. Clip freely during the\nday, run <code>/ingest</code> in one batch later, because ingesting one source at a time\ngives the agent no chance to spot that three things you saved this week are\nabout the same idea.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"youtube-transcripts.md\">YouTube and podcasts</a></p>", "headings": ["Obsidian Web Clipper", "Template", "What to clip", "Awkward pages", "Clip now, ingest later", "Next"], "words": 423, "text": "Articles are the bulk of what most people save, and the browser is where the decision to save happens. Anything that requires switching windows loses. Obsidian Web Clipper The official extension https://obsidian.md/clipper from the Obsidian team. Chrome, Firefox, Safari, Edge, Brave and Arc. It extracts the readable content of a page using Mozilla Readability, the same engine behind Firefox Reader View, and saves it as markdown straight into your vault. Install it, open the settings, and set the destination folder to raw/ . Template The default template saves the page body. Add frontmatter so the agent knows what it is holding without re-reading the whole file: --- title: {{title}} source: {{url}} author: {{author}} published: {{published}} clipped: {{date}} type: article --- {{content}} {{author}} and {{published}} come back empty on plenty of sites. That is fine, an empty field is better than a guessed one, and the agent handles the gap by saying the source is undated rather than inventing a date. What to clip Clip what you would want to find again in a year: primary sources, engineering posts, papers, documentation, arguments you disagree with and want to answer later. Skip news that will be stale in a week, listicles, and anything you are saving out of guilt. Every low-value page you ingest costs twice: once at ingest, and again every time the agent reads past it looking for something else. The honest test at clip time is whether you can name what you would ask this source later. If you cannot, do not clip it. Awkward pages - Paywalls. The clipper saves what the browser rendered. If you can read it, it can save it. If you cannot, it saves the paywall notice, so check before moving on. - Documentation sites. Clipping page by page is a losing game. Save the entry point and let the agent fetch the rest, or clone the docs repo into raw/ if it is open source. - Single-page apps and dynamic content. Readability sometimes returns a fragment. Look at the file before ingest. - Threads and comment sections. The value is usually in the replies, which the clipper drops. Copy the thread manually or screenshot it into raw/assets/ . Clip now, ingest later Clipping and ingesting are separate steps on purpose. Clip freely during the day, run /ingest in one batch later, because ingesting one source at a time gives the agent no chance to spot that three things you saved this week are about the same idea. Next YouTube and podcasts youtube-transcripts.md", "links": [{"to": "03-ingestion/youtube-transcripts", "label": "YouTube and podcasts"}]}, {"id": "03-ingestion/youtube-transcripts", "path": "docs/03-ingestion/youtube-transcripts.md", "section": "03-ingestion", "section_title": "Ingestion", "title": "YouTube and podcasts", "html": "<p>Video is the highest-volume, lowest-retention source most people have. An hour\nof a conference talk leaves almost nothing behind a week later. Transcripts fix\nthat, and a transcript is just text, which is exactly what the vault wants.</p>\n<h2 id=\"pulling-a-transcript\">Pulling a transcript</h2>\n<p>Most videos have captions, auto-generated or uploaded. Two dependable routes:</p>\n<pre><code class=\"language-bash\"># yt-dlp: subtitles only, no video download\nyt-dlp --write-auto-sub --skip-download --sub-format vtt --sub-lang en URL\n</code></pre>\n<pre><code class=\"language-python\"># youtube-transcript-api, if you want it in a script\nfrom youtube_transcript_api import YouTubeTranscriptApi\nlines = YouTubeTranscriptApi.get_transcript("VIDEO_ID")\n</code></pre>\n<p>Save the result into <code>raw/</code> with frontmatter naming the video, the channel and\nthe URL. Without the URL, a transcript is an anonymous wall of text and the\nagent cannot cite it properly.</p>\n<h2 id=\"keep-the-timestamps\">Keep the timestamps</h2>\n<p>Auto-generated transcripts arrive as timestamped fragments. Strip the\nformatting, keep coarse timestamps every few minutes.</p>\n<p>The reason is retrieval: when the wiki says a claim came from minute 34 of a\ntalk, you can verify it in ten seconds. Without that, checking means rewatching,\nwhich means you will not check.</p>\n<h2 id=\"clean-before-ingest\">Clean before ingest</h2>\n<p>Auto-captions have no punctuation, no speaker labels, and mangle technical\nterms. Have the agent do a pass first:</p>\n<pre><code>Read raw/talk-transcript.md. Add punctuation and paragraph breaks, label\nspeakers where they change, and fix obvious mistranscriptions of technical\nterms. Do not summarise, do not cut anything, and flag anything you could not\nmake sense of.\n</code></pre>\n<p>Do not skip to ingesting the raw caption dump. Concept pages built from\nunpunctuated text come out noticeably worse, because the model spends its\nattention reconstructing sentence boundaries instead of understanding claims.</p>\n<h2 id=\"long-videos\">Long videos</h2>\n<p>A three-hour podcast is not one source. Split it by topic before ingesting,\neither by chapter markers if the uploader added them, or by asking the agent to\npropose split points from the transcript.</p>\n<p>Ingested whole, a long interview produces one bloated source page and two or\nthree vague concepts. Split, it produces the four ideas that were actually in\nit.</p>\n<h2 id=\"podcasts-and-audio\">Podcasts and audio</h2>\n<p>Podcasts rarely ship transcripts. Options, in order of effort: check the show\nnotes, many now publish one; run local transcription with Whisper; or use a\ntranscription service.</p>\n<p>Local transcription is worth setting up if you listen daily. The audio never\nleaves your machine, which matters more for meeting recordings than for\npodcasts.</p>\n<h2 id=\"what-is-worth-transcribing\">What is worth transcribing</h2>\n<p>Talks, lectures, interviews with practitioners, anything with a specific claim\nyou might need later.</p>\n<p>Not tutorials you watched to do a task once, and not anything you would not\nreread as an article. Video feels valuable while watching because it takes an\nhour. That feeling is not a signal about the content.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"pdfs-and-books.md\">PDFs, papers and books</a></p>", "headings": ["Pulling a transcript", "Keep the timestamps", "Clean before ingest", "Long videos", "Podcasts and audio", "What is worth transcribing", "Next"], "words": 448, "text": "Video is the highest-volume, lowest-retention source most people have. An hour of a conference talk leaves almost nothing behind a week later. Transcripts fix that, and a transcript is just text, which is exactly what the vault wants. Pulling a transcript Most videos have captions, auto-generated or uploaded. Two dependable routes: bash yt-dlp: subtitles only, no video download yt-dlp --write-auto-sub --skip-download --sub-format vtt --sub-lang en URL python youtube-transcript-api, if you want it in a script from youtube_transcript_api import YouTubeTranscriptApi lines = YouTubeTranscriptApi.get_transcript \"VIDEO_ID\" Save the result into raw/ with frontmatter naming the video, the channel and the URL. Without the URL, a transcript is an anonymous wall of text and the agent cannot cite it properly. Keep the timestamps Auto-generated transcripts arrive as timestamped fragments. Strip the formatting, keep coarse timestamps every few minutes. The reason is retrieval: when the wiki says a claim came from minute 34 of a talk, you can verify it in ten seconds. Without that, checking means rewatching, which means you will not check. Clean before ingest Auto-captions have no punctuation, no speaker labels, and mangle technical terms. Have the agent do a pass first: Read raw/talk-transcript.md. Add punctuation and paragraph breaks, label speakers where they change, and fix obvious mistranscriptions of technical terms. Do not summarise, do not cut anything, and flag anything you could not make sense of. Do not skip to ingesting the raw caption dump. Concept pages built from unpunctuated text come out noticeably worse, because the model spends its attention reconstructing sentence boundaries instead of understanding claims. Long videos A three-hour podcast is not one source. Split it by topic before ingesting, either by chapter markers if the uploader added them, or by asking the agent to propose split points from the transcript. Ingested whole, a long interview produces one bloated source page and two or three vague concepts. Split, it produces the four ideas that were actually in it. Podcasts and audio Podcasts rarely ship transcripts. Options, in order of effort: check the show notes, many now publish one; run local transcription with Whisper; or use a transcription service. Local transcription is worth setting up if you listen daily. The audio never leaves your machine, which matters more for meeting recordings than for podcasts. What is worth transcribing Talks, lectures, interviews with practitioners, anything with a specific claim you might need later. Not tutorials you watched to do a task once, and not anything you would not reread as an article. Video feels valuable while watching because it takes an hour. That feeling is not a signal about the content. Next PDFs, papers and books pdfs-and-books.md", "links": [{"to": "03-ingestion/pdfs-and-books", "label": "PDFs, papers and books"}]}, {"id": "03-ingestion/pdfs-and-books", "path": "docs/03-ingestion/pdfs-and-books.md", "section": "03-ingestion", "section_title": "Ingestion", "title": "PDFs, papers and books", "html": "<p>PDFs are the format most likely to arrive in your vault as garbage. Two columns\nbecome interleaved lines, tables collapse, footnotes land mid-sentence, and the\nagent quietly builds pages on top of the mess.</p>\n<p>Check extraction quality before ingesting. It takes ten seconds and saves\nrewriting pages later.</p>\n<h2 id=\"extraction\">Extraction</h2>\n<pre><code class=\"language-bash\"># text, layout preserved reasonably well\npdftotext -layout paper.pdf raw/paper.md\n</code></pre>\n<p>For anything structured, <code>pymupdf</code> gives better control and can pull images and\ntables separately. Whatever you use, open the output and read a paragraph from\nthe middle. If the sentences do not flow, fix extraction rather than hoping the\nagent copes.</p>\n<h2 id=\"scanned-documents\">Scanned documents</h2>\n<p>A scan is an image, and text extraction returns nothing or near-nothing. Run OCR\nfirst with <code>ocrmypdf</code>, which adds a text layer without changing the visible\ndocument. Expect errors in proper nouns and numbers, and treat any figure from\nan OCR'd source as needing verification before it goes into a wiki page as\nfact.</p>\n<h2 id=\"papers\">Papers</h2>\n<p>Papers deserve different handling than articles, because the parts you will\nwant later are not spread evenly. Abstract, method, results and limitations\ncarry almost everything.</p>\n<p>A useful ingest instruction:</p>\n<pre><code>This is an academic paper. Build the source page around: the question it asks,\nthe method, the result with its actual numbers, and the limitations the authors\nstate themselves. Record sample sizes. Do not report a finding without the\ncondition it holds under.\n</code></pre>\n<p>That last rule is what keeps a wiki honest. Findings stripped of their\nconditions become confident nonsense two years later.</p>\n<p>Zotero is worth using if you read papers regularly. It handles metadata and\nexports markdown, which lands in <code>raw/</code> cleanly.</p>\n<h2 id=\"books\">Books</h2>\n<p>A full book is too large to ingest as one source and mostly not worth it. What\nis worth it is your highlights.</p>\n<p>Kindle highlights export from the Kindle app or through Readwise, which syncs\ninto Obsidian directly. Highlights arrive as a list of quoted passages, so\ningest them as one source page per book, and let the agent build concept pages\nfrom the ideas rather than from the quotes.</p>\n<p>Keep the quotes short in the wiki and keep the citation. A page that reproduces\nhalf a chapter is a copyright problem and a retrieval problem at the same time.</p>\n<h2 id=\"figures-and-tables\">Figures and tables</h2>\n<p>Text extraction drops both. When a figure carries the argument, screenshot it\ninto <code>raw/assets/</code> and reference it from the source page, so the claim on the\npage has something behind it.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"chat-exports.md\">Chat exports</a></p>", "headings": ["Extraction", "Scanned documents", "Papers", "Books", "Figures and tables", "Next"], "words": 417, "text": "PDFs are the format most likely to arrive in your vault as garbage. Two columns become interleaved lines, tables collapse, footnotes land mid-sentence, and the agent quietly builds pages on top of the mess. Check extraction quality before ingesting. It takes ten seconds and saves rewriting pages later. Extraction bash text, layout preserved reasonably well pdftotext -layout paper.pdf raw/paper.md For anything structured, pymupdf gives better control and can pull images and tables separately. Whatever you use, open the output and read a paragraph from the middle. If the sentences do not flow, fix extraction rather than hoping the agent copes. Scanned documents A scan is an image, and text extraction returns nothing or near-nothing. Run OCR first with ocrmypdf , which adds a text layer without changing the visible document. Expect errors in proper nouns and numbers, and treat any figure from an OCR'd source as needing verification before it goes into a wiki page as fact. Papers Papers deserve different handling than articles, because the parts you will want later are not spread evenly. Abstract, method, results and limitations carry almost everything. A useful ingest instruction: This is an academic paper. Build the source page around: the question it asks, the method, the result with its actual numbers, and the limitations the authors state themselves. Record sample sizes. Do not report a finding without the condition it holds under. That last rule is what keeps a wiki honest. Findings stripped of their conditions become confident nonsense two years later. Zotero is worth using if you read papers regularly. It handles metadata and exports markdown, which lands in raw/ cleanly. Books A full book is too large to ingest as one source and mostly not worth it. What is worth it is your highlights. Kindle highlights export from the Kindle app or through Readwise, which syncs into Obsidian directly. Highlights arrive as a list of quoted passages, so ingest them as one source page per book, and let the agent build concept pages from the ideas rather than from the quotes. Keep the quotes short in the wiki and keep the citation. A page that reproduces half a chapter is a copyright problem and a retrieval problem at the same time. Figures and tables Text extraction drops both. When a figure carries the argument, screenshot it into raw/assets/ and reference it from the source page, so the claim on the page has something behind it. Next Chat exports chat-exports.md", "links": [{"to": "03-ingestion/chat-exports", "label": "Chat exports"}]}, {"id": "03-ingestion/chat-exports", "path": "docs/03-ingestion/chat-exports.md", "section": "03-ingestion", "section_title": "Ingestion", "title": "Chat exports", "html": "<p>Your chat history is the most underrated source you own and the most sensitive.\nYears of problems you worked through, decisions you reasoned about, and\nexplanations tailored to what you did not understand at the time.</p>\n<p>It is also full of things you would not want in a file you might later share.\nRead the privacy section below before running anything here.</p>\n<h2 id=\"exporting\">Exporting</h2>\n<p>Both Claude and ChatGPT export the full history as JSON from account settings.\nThe export arrives by email as a download link, usually within minutes.</p>\n<h2 id=\"converting-to-markdown\">Converting to markdown</h2>\n<p>One JSON blob is not ingestible. Split it into one file per conversation:</p>\n<pre><code class=\"language-bash\">python3 scripts/chat_export_to_md.py conversations.json ./raw --min-words 150\n</code></pre>\n<p>The script is in <a href=\"../../scripts/README.md\"><code>scripts/</code></a>. It handles the common\nexport shapes, writes frontmatter with the title and date, and skips\nconversations shorter than the word threshold.</p>\n<p>Raise <code>--min-words</code> if the output is dominated by one-line exchanges. Most\npeople's history is roughly ninety percent short throwaway questions, and those\nadd nothing but volume.</p>\n<h2 id=\"filter-before-ingesting\">Filter before ingesting</h2>\n<p>Do not ingest the whole export. A thousand conversations produce a thousand\nsource pages and a wiki where everything is faintly connected to everything.</p>\n<p>Sort into three piles:</p>\n<ul>\n<li><strong>Worth ingesting.</strong> Conversations where you worked something out, decided\n something, or got an explanation that landed. These carry your reasoning, not\n just facts.</li>\n<li><strong>Worth keeping, not ingesting.</strong> Leave them in <code>raw/</code> as an archive. The\n agent can search them on demand without every one having a wiki page.</li>\n<li><strong>Delete.</strong> Debugging sessions, one-off lookups, anything you would be\n annoyed to find in a search result.</li>\n</ul>\n<p>Have the agent help with the sort rather than doing it by hand:</p>\n<pre><code>Read the titles and first exchange of every file in raw/chats/. Group them into\nworth-ingesting, archive, and delete, with one line of reasoning each. Do not\nmove or delete anything, just give me the lists.\n</code></pre>\n<h2 id=\"what-makes-these-sources-different\">What makes these sources different</h2>\n<p>A chat log is a record of you thinking, which means the useful extraction is\noften not the answer. It is the question you asked, the thing you had wrong at\nthe start, and what changed your mind.</p>\n<p>Tell the agent so:</p>\n<pre><code>These are my own past conversations. Build pages around what I was trying to\nwork out and what conclusion I reached, not around the assistant's explanations.\nNote where I changed position, and record the date, because my views may have\nmoved since.\n</code></pre>\n<h2 id=\"privacy\">Privacy</h2>\n<p>Chat history contains more about you than any other file in the vault: health,\nmoney, work you cannot discuss, other people's information you happened to\nmention.</p>\n<p>Before ingesting, decide what does not belong in the vault at all and delete\nthose files from <code>raw/</code>. Redaction after the fact is unreliable, because the\nmaterial will already have propagated into concept pages and links.</p>\n<p>If the vault lives in a git repo, keep the remote private. See\n<a href=\"../09-maintenance/privacy-and-secrets.md\">privacy</a>.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"voice-and-meetings.md\">Voice notes and meetings</a></p>", "headings": ["Exporting", "Converting to markdown", "Filter before ingesting", "What makes these sources different", "Privacy", "Next"], "words": 491, "text": "Your chat history is the most underrated source you own and the most sensitive. Years of problems you worked through, decisions you reasoned about, and explanations tailored to what you did not understand at the time. It is also full of things you would not want in a file you might later share. Read the privacy section below before running anything here. Exporting Both Claude and ChatGPT export the full history as JSON from account settings. The export arrives by email as a download link, usually within minutes. Converting to markdown One JSON blob is not ingestible. Split it into one file per conversation: bash python3 scripts/chat_export_to_md.py conversations.json ./raw --min-words 150 The script is in scripts/ ../../scripts/README.md . It handles the common export shapes, writes frontmatter with the title and date, and skips conversations shorter than the word threshold. Raise --min-words if the output is dominated by one-line exchanges. Most people's history is roughly ninety percent short throwaway questions, and those add nothing but volume. Filter before ingesting Do not ingest the whole export. A thousand conversations produce a thousand source pages and a wiki where everything is faintly connected to everything. Sort into three piles: - Worth ingesting. Conversations where you worked something out, decided something, or got an explanation that landed. These carry your reasoning, not just facts. - Worth keeping, not ingesting. Leave them in raw/ as an archive. The agent can search them on demand without every one having a wiki page. - Delete. Debugging sessions, one-off lookups, anything you would be annoyed to find in a search result. Have the agent help with the sort rather than doing it by hand: Read the titles and first exchange of every file in raw/chats/. Group them into worth-ingesting, archive, and delete, with one line of reasoning each. Do not move or delete anything, just give me the lists. What makes these sources different A chat log is a record of you thinking, which means the useful extraction is often not the answer. It is the question you asked, the thing you had wrong at the start, and what changed your mind. Tell the agent so: These are my own past conversations. Build pages around what I was trying to work out and what conclusion I reached, not around the assistant's explanations. Note where I changed position, and record the date, because my views may have moved since. Privacy Chat history contains more about you than any other file in the vault: health, money, work you cannot discuss, other people's information you happened to mention. Before ingesting, decide what does not belong in the vault at all and delete those files from raw/ . Redaction after the fact is unreliable, because the material will already have propagated into concept pages and links. If the vault lives in a git repo, keep the remote private. See privacy ../09-maintenance/privacy-and-secrets.md . Next Voice notes and meetings voice-and-meetings.md", "links": [{"to": "09-maintenance/privacy-and-secrets", "label": "privacy"}, {"to": "03-ingestion/voice-and-meetings", "label": "Voice notes and meetings"}]}, {"id": "03-ingestion/voice-and-meetings", "path": "docs/03-ingestion/voice-and-meetings.md", "section": "03-ingestion", "section_title": "Ingestion", "title": "Voice notes and meetings", "html": "<p>The ideas worth capturing rarely arrive at your desk. Voice is the only capture\nmethod that works while walking, driving or standing in a queue, and it is the\none most vaults never wire up.</p>\n<h2 id=\"capture\">Capture</h2>\n<p>Any recorder app works, as long as the file ends up somewhere the vault can\nreach. The friction to eliminate is the transfer: if getting audio from phone to\nvault takes more than one action, you will stop.</p>\n<p>Simplest reliable setup: record in the phone's default app, share to a cloud\nfolder, and have a scheduled task transcribe anything new into <code>raw/</code>.</p>\n<p>Obsidian's mobile app can record directly into the vault, which removes the\ntransfer entirely if you already sync mobile.</p>\n<h2 id=\"transcription\">Transcription</h2>\n<p>Whisper runs locally and is good enough for a voice note recorded at arm's\nlength. Local matters more here than for other sources, because voice notes\ncarry half-formed thoughts and meeting audio carries other people's words.</p>\n<p>Expect names and technical terms to come out wrong. Correct them at ingest, not\nlater, while you still remember what you said.</p>\n<h2 id=\"voice-notes-are-drafts-not-sources\">Voice notes are drafts, not sources</h2>\n<p>A voice note is you thinking out loud, with false starts and abandoned\nsentences. Ingesting it verbatim produces an incoherent source page.</p>\n<p>Treat the transcript as raw input to a single idea:</p>\n<pre><code>This is a voice note, my own thinking out loud. Extract the actual idea, drop\nthe false starts and repetition, and write it as one short concept page in my\nwords. If there are two unrelated ideas, make two pages. Keep the recording date.\n</code></pre>\n<h2 id=\"meetings\">Meetings</h2>\n<p>Meetings produce three things worth keeping and a great deal that is not: the\ndecisions, the commitments with owners, and the open questions.</p>\n<pre><code>This is a meeting transcript. Extract decisions made, commitments with who owns\neach one, and open questions. Link every person mentioned to their entity page.\nSkip discussion that did not lead anywhere.\n</code></pre>\n<p>Route the commitments into the relevant project's <code>Inputs/</code> rather than the\nwiki. A commitment is work, not knowledge, and it goes stale in a week. The\n<a href=\"../01-concepts/two-layers.md\">two layers</a> page covers why that separation\nmatters.</p>\n<h2 id=\"consent-and-other-people\">Consent and other people</h2>\n<p>Recording other people has legal requirements that vary by jurisdiction, and\nthey are not a formality. Some places require every participant to consent.</p>\n<p>Separately from legality: a meeting transcript contains other people's\nunguarded words. Keep those out of any vault you might share, and think about\nwhether the meeting needs to be in the knowledge layer at all, or whether the\nthree extracted decisions are enough.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"newsletters-and-email.md\">Newsletters and email</a></p>", "headings": ["Capture", "Transcription", "Voice notes are drafts, not sources", "Meetings", "Consent and other people", "Next"], "words": 432, "text": "The ideas worth capturing rarely arrive at your desk. Voice is the only capture method that works while walking, driving or standing in a queue, and it is the one most vaults never wire up. Capture Any recorder app works, as long as the file ends up somewhere the vault can reach. The friction to eliminate is the transfer: if getting audio from phone to vault takes more than one action, you will stop. Simplest reliable setup: record in the phone's default app, share to a cloud folder, and have a scheduled task transcribe anything new into raw/ . Obsidian's mobile app can record directly into the vault, which removes the transfer entirely if you already sync mobile. Transcription Whisper runs locally and is good enough for a voice note recorded at arm's length. Local matters more here than for other sources, because voice notes carry half-formed thoughts and meeting audio carries other people's words. Expect names and technical terms to come out wrong. Correct them at ingest, not later, while you still remember what you said. Voice notes are drafts, not sources A voice note is you thinking out loud, with false starts and abandoned sentences. Ingesting it verbatim produces an incoherent source page. Treat the transcript as raw input to a single idea: This is a voice note, my own thinking out loud. Extract the actual idea, drop the false starts and repetition, and write it as one short concept page in my words. If there are two unrelated ideas, make two pages. Keep the recording date. Meetings Meetings produce three things worth keeping and a great deal that is not: the decisions, the commitments with owners, and the open questions. This is a meeting transcript. Extract decisions made, commitments with who owns each one, and open questions. Link every person mentioned to their entity page. Skip discussion that did not lead anywhere. Route the commitments into the relevant project's Inputs/ rather than the wiki. A commitment is work, not knowledge, and it goes stale in a week. The two layers ../01-concepts/two-layers.md page covers why that separation matters. Consent and other people Recording other people has legal requirements that vary by jurisdiction, and they are not a formality. Some places require every participant to consent. Separately from legality: a meeting transcript contains other people's unguarded words. Keep those out of any vault you might share, and think about whether the meeting needs to be in the knowledge layer at all, or whether the three extracted decisions are enough. Next Newsletters and email newsletters-and-email.md", "links": [{"to": "01-concepts/two-layers", "label": "two layers"}, {"to": "03-ingestion/newsletters-and-email", "label": "Newsletters and email"}]}, {"id": "03-ingestion/newsletters-and-email", "path": "docs/03-ingestion/newsletters-and-email.md", "section": "03-ingestion", "section_title": "Ingestion", "title": "Newsletters and email", "html": "<p>Newsletters are the easiest source to automate and the easiest to over-ingest.\nAutomate the capture, then be strict about what gets a wiki page, because a feed\nthat files itself will happily fill your vault with a hundred pages a month that\nyou never asked for.</p>\n<h2 id=\"a-dedicated-address\">A dedicated address</h2>\n<p>Make an address that exists only for the vault, and resubscribe your newsletters\nto it. That single move separates the material you want to keep from everything\nelse in your inbox, and it means automation never touches your real mail.</p>\n<p>From there, forward that address into <code>raw/</code> with whatever automation you\nalready use. Any rule that can write a file works.</p>\n<h2 id=\"deduplicate\">Deduplicate</h2>\n<p>Newsletters repeat themselves. The same launch appears in four different digests\nin the same week, each with the same facts and a different opening line.</p>\n<p>Ingested straight, you get four source pages saying one thing and a concept page\nciting all four as if that were corroboration. Cross-references between\nnewsletters are not independent confirmation, and a wiki that treats them as\nsuch will overstate how well established something is.</p>\n<p>Instruct the ingest explicitly:</p>\n<pre><code>These are newsletters. Several will cover the same item. Group them by topic\nfirst, write one source page per actual item citing every newsletter that\nmentioned it, and note where they disagree. Do not treat repetition across\nnewsletters as confirmation.\n</code></pre>\n<h2 id=\"what-deserves-a-page\">What deserves a page</h2>\n<p>Newsletters are mostly links with commentary. The commentary is rarely worth a\nconcept page; the thing being linked sometimes is.</p>\n<p>The useful pattern is to let the agent read the digests and hand you a shortlist:</p>\n<pre><code>Read this week's newsletters in raw/newsletters/. List anything worth reading in\nfull, with one line on why. Ingest nothing yet.\n</code></pre>\n<p>Then clip the two or three primary sources properly and ingest those. The\nnewsletter did its job as a filter, and the vault ends up with the actual source\ninstead of a summary of it.</p>\n<h2 id=\"regular-email\">Regular email</h2>\n<p>Most email should not be in a second brain. Threads about scheduling, receipts,\nback and forth about logistics: none of it is knowledge, all of it is volume.</p>\n<p>Worth ingesting: threads where a real decision was made or something was\nexplained properly. Route those in by forwarding to the capture address, one\nthread at a time, deliberately.</p>\n<p>Never wire your whole inbox into <code>raw/</code> on a schedule. It ingests everything\nabout everyone you correspond with, most of it not yours to keep.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"bulk-backfill.md\">Backfilling years of material</a></p>", "headings": ["A dedicated address", "Deduplicate", "What deserves a page", "Regular email", "Next"], "words": 417, "text": "Newsletters are the easiest source to automate and the easiest to over-ingest. Automate the capture, then be strict about what gets a wiki page, because a feed that files itself will happily fill your vault with a hundred pages a month that you never asked for. A dedicated address Make an address that exists only for the vault, and resubscribe your newsletters to it. That single move separates the material you want to keep from everything else in your inbox, and it means automation never touches your real mail. From there, forward that address into raw/ with whatever automation you already use. Any rule that can write a file works. Deduplicate Newsletters repeat themselves. The same launch appears in four different digests in the same week, each with the same facts and a different opening line. Ingested straight, you get four source pages saying one thing and a concept page citing all four as if that were corroboration. Cross-references between newsletters are not independent confirmation, and a wiki that treats them as such will overstate how well established something is. Instruct the ingest explicitly: These are newsletters. Several will cover the same item. Group them by topic first, write one source page per actual item citing every newsletter that mentioned it, and note where they disagree. Do not treat repetition across newsletters as confirmation. What deserves a page Newsletters are mostly links with commentary. The commentary is rarely worth a concept page; the thing being linked sometimes is. The useful pattern is to let the agent read the digests and hand you a shortlist: Read this week's newsletters in raw/newsletters/. List anything worth reading in full, with one line on why. Ingest nothing yet. Then clip the two or three primary sources properly and ingest those. The newsletter did its job as a filter, and the vault ends up with the actual source instead of a summary of it. Regular email Most email should not be in a second brain. Threads about scheduling, receipts, back and forth about logistics: none of it is knowledge, all of it is volume. Worth ingesting: threads where a real decision was made or something was explained properly. Route those in by forwarding to the capture address, one thread at a time, deliberately. Never wire your whole inbox into raw/ on a schedule. It ingests everything about everyone you correspond with, most of it not yours to keep. Next Backfilling years of material bulk-backfill.md", "links": [{"to": "03-ingestion/bulk-backfill", "label": "Backfilling years of material"}]}, {"id": "03-ingestion/bulk-backfill", "path": "docs/03-ingestion/bulk-backfill.md", "section": "03-ingestion", "section_title": "Ingestion", "title": "Backfilling years of material", "html": "<p>At some point you will want to import everything: the bookmark folder, the\ndownloads directory, three years of chat history, the read-later queue with\neight hundred unread items.</p>\n<p>This is the run that goes wrong. It is expensive, it takes hours, and done in\nthe wrong order it produces a wiki that reads like a pile rather than a\nstructure. It is also the run that makes the vault genuinely useful in one\nsitting, so it is worth doing carefully.</p>\n<h2 id=\"order-matters\">Order matters</h2>\n<p>Process oldest first.</p>\n<p>The reason is that later sources should update pages that earlier sources\ncreated. Run it that way and the wiki records how your understanding developed:\nthe early page on a topic, then the correction, then the current position.</p>\n<p>Run it newest first and every old source arrives as a contradiction to be\nreconciled against a page that already has the final answer. The agent spends\nits work reconciling, the history comes out inverted, and you lose the one thing\nthis structure gives you over a search index.</p>\n<h2 id=\"batch-always\">Batch, always</h2>\n<p>Ten sources per batch. After each batch: update <code>index.md</code>, append to <code>log.md</code>,\ncommit, report.</p>\n<pre><code>/backfill raw/archive/2024\n</code></pre>\n<p>The <code>backfill</code> command in <a href=\"../../commands/README.md\"><code>commands/</code></a> works this\nway and stops between batches for a go-ahead.</p>\n<p>Batching exists for three reasons. Cost stays visible while you can still stop.\nQuality stays checkable, so you catch a bad page contract on page ten rather\nthan page four hundred. And a crash costs you one batch instead of the run.</p>\n<h2 id=\"check-the-first-batch-properly\">Check the first batch properly</h2>\n<p>Read every page the first batch produced. All of them.</p>\n<p>This is the moment to catch systematic problems: pages that are summaries rather\nthan explanations, concepts that are too granular, links that are decorative,\nfrontmatter that is wrong. Fix <code>CLAUDE.md</code> and re-run the batch before\ncontinuing.</p>\n<p>A flaw you let through in batch one is a flaw in four hundred pages by the end,\nand fixing it afterwards costs more than the original run.</p>\n<h2 id=\"cost-control\">Cost control</h2>\n<p>Backfilling a thousand sources is a real bill. Ways to keep it sane:</p>\n<ul>\n<li><strong>Filter first.</strong> Most archives are half dead links and things you saved and\n never opened. Have the agent triage titles before ingesting anything.</li>\n<li><strong>Cap the batch size</strong> and watch what the first few cost before scaling.</li>\n<li><strong>Skip the archive tier.</strong> Not everything needs a wiki page; leaving material\n in <code>raw/</code> still leaves it searchable.</li>\n</ul>\n<h2 id=\"dead-links\">Dead links</h2>\n<p>Old bookmark exports are full of pages that no longer exist. Check before\ningesting rather than discovering it halfway:</p>\n<pre><code class=\"language-bash\">python3 -c "import sys,urllib.request as u;[print(l.strip()) for l in sys.stdin]"\n</code></pre>\n<p>For anything valuable that is gone, the Internet Archive usually has a copy.\nClip from there and note in the frontmatter that the original is dead, because a\nsource page whose URL 404s is unverifiable a year later.</p>\n<h2 id=\"resuming\">Resuming</h2>\n<p>Record progress in <code>log.md</code> as you go, one line per batch with the folder and\nrange covered. When the run stops halfway, and it will, you resume from the log\ninstead of guessing which files were done.</p>\n<h2 id=\"after-the-backfill\">After the backfill</h2>\n<p>Run a full lint. A large import always leaves orphans, near-duplicates and\nbroken links.</p>\n<pre><code>/lint\n</code></pre>\n<p>Then run a review to see what the vault now contains, because after a backfill\nit knows things you have forgotten you saved. That moment is the payoff for the\nwhole exercise.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"../04-structuring/README.md\">Structuring</a>, for the rules that decide what all\nthese pages actually look like.</p>", "headings": ["Order matters", "Batch, always", "Check the first batch properly", "Cost control", "Dead links", "Resuming", "After the backfill", "Next"], "words": 583, "text": "At some point you will want to import everything: the bookmark folder, the downloads directory, three years of chat history, the read-later queue with eight hundred unread items. This is the run that goes wrong. It is expensive, it takes hours, and done in the wrong order it produces a wiki that reads like a pile rather than a structure. It is also the run that makes the vault genuinely useful in one sitting, so it is worth doing carefully. Order matters Process oldest first. The reason is that later sources should update pages that earlier sources created. Run it that way and the wiki records how your understanding developed: the early page on a topic, then the correction, then the current position. Run it newest first and every old source arrives as a contradiction to be reconciled against a page that already has the final answer. The agent spends its work reconciling, the history comes out inverted, and you lose the one thing this structure gives you over a search index. Batch, always Ten sources per batch. After each batch: update index.md , append to log.md , commit, report. /backfill raw/archive/2024 The backfill command in commands/ ../../commands/README.md works this way and stops between batches for a go-ahead. Batching exists for three reasons. Cost stays visible while you can still stop. Quality stays checkable, so you catch a bad page contract on page ten rather than page four hundred. And a crash costs you one batch instead of the run. Check the first batch properly Read every page the first batch produced. All of them. This is the moment to catch systematic problems: pages that are summaries rather than explanations, concepts that are too granular, links that are decorative, frontmatter that is wrong. Fix CLAUDE.md and re-run the batch before continuing. A flaw you let through in batch one is a flaw in four hundred pages by the end, and fixing it afterwards costs more than the original run. Cost control Backfilling a thousand sources is a real bill. Ways to keep it sane: - Filter first. Most archives are half dead links and things you saved and never opened. Have the agent triage titles before ingesting anything. - Cap the batch size and watch what the first few cost before scaling. - Skip the archive tier. Not everything needs a wiki page; leaving material in raw/ still leaves it searchable. Dead links Old bookmark exports are full of pages that no longer exist. Check before ingesting rather than discovering it halfway: bash python3 -c \"import sys,urllib.request as u; print l.strip for l in sys.stdin \" For anything valuable that is gone, the Internet Archive usually has a copy. Clip from there and note in the frontmatter that the original is dead, because a source page whose URL 404s is unverifiable a year later. Resuming Record progress in log.md as you go, one line per batch with the folder and range covered. When the run stops halfway, and it will, you resume from the log instead of guessing which files were done. After the backfill Run a full lint. A large import always leaves orphans, near-duplicates and broken links. /lint Then run a review to see what the vault now contains, because after a backfill it knows things you have forgotten you saved. That moment is the payoff for the whole exercise. Next Structuring ../04-structuring/README.md , for the rules that decide what all these pages actually look like.", "links": []}, {"id": "04-structuring/atomic-pages", "path": "docs/04-structuring/atomic-pages.md", "section": "04-structuring", "section_title": "Structuring", "title": "One page, one idea", "html": "<p>A page holds one idea, explained well enough that someone who has never seen the\nsource understands it.</p>\n<p>The rule exists because of how retrieval works. When the agent answers a\nquestion, it pulls in whole pages. A page covering four topics drags three\nirrelevant ones into context every time it is touched. A page covering one gets\nlinked precisely, retrieved precisely, and updated without collateral damage.</p>\n<h2 id=\"what-atomic-means-here\">What atomic means here</h2>\n<p>Not short. A concept page can run several hundred words. Atomic means it has one\nsubject and you could give it an accurate title without using \"and\".</p>\n<p>If the title needs \"and\", or the page has section headings for unrelated\nsubjects, it is two pages.</p>\n<h2 id=\"splitting-a-source\">Splitting a source</h2>\n<p>One article usually yields one to three concepts worth their own page, plus the\nsource page recording what the article itself said.</p>\n<p>The test for whether something deserves a page: can it be explained without\nreferring back to this one source? An idea that only makes sense as \"what this\narticle argued\" belongs inside the source page. An idea that will recur across\nother sources needs its own page, because that is where the other sources will\nattach.</p>\n<h2 id=\"the-failure-in-both-directions\">The failure in both directions</h2>\n<p><strong>Over-splitting</strong> produces ten pages from one article, each a restated\nparagraph, each linking only back to the source. The graph looks dense and says\nnothing. This is the more common failure with agents, because splitting feels\nlike thoroughness.</p>\n<p><strong>Under-splitting</strong> produces source pages that are article summaries and a wiki\nwith no concepts at all. You end up with a searchable archive, which you already\nhad.</p>\n<p>If you are unsure, write fewer pages. Merging later is cheap; untangling a\nhundred fragments is not.</p>\n<h2 id=\"length\">Length</h2>\n<p>A concept page under about eighty words is usually a stub that failed, not a\npage that was efficient. Either the source did not really cover it, or the agent\ngave up. Both are worth catching in a lint pass.</p>\n<p>A page over roughly a thousand words is usually two ideas that grew together.\nRead it and look for the seam.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"page-types.md\">The four page types</a></p>", "headings": ["What atomic means here", "Splitting a source", "The failure in both directions", "Length", "Next"], "words": 356, "text": "A page holds one idea, explained well enough that someone who has never seen the source understands it. The rule exists because of how retrieval works. When the agent answers a question, it pulls in whole pages. A page covering four topics drags three irrelevant ones into context every time it is touched. A page covering one gets linked precisely, retrieved precisely, and updated without collateral damage. What atomic means here Not short. A concept page can run several hundred words. Atomic means it has one subject and you could give it an accurate title without using \"and\". If the title needs \"and\", or the page has section headings for unrelated subjects, it is two pages. Splitting a source One article usually yields one to three concepts worth their own page, plus the source page recording what the article itself said. The test for whether something deserves a page: can it be explained without referring back to this one source? An idea that only makes sense as \"what this article argued\" belongs inside the source page. An idea that will recur across other sources needs its own page, because that is where the other sources will attach. The failure in both directions Over-splitting produces ten pages from one article, each a restated paragraph, each linking only back to the source. The graph looks dense and says nothing. This is the more common failure with agents, because splitting feels like thoroughness. Under-splitting produces source pages that are article summaries and a wiki with no concepts at all. You end up with a searchable archive, which you already had. If you are unsure, write fewer pages. Merging later is cheap; untangling a hundred fragments is not. Length A concept page under about eighty words is usually a stub that failed, not a page that was efficient. Either the source did not really cover it, or the agent gave up. Both are worth catching in a lint pass. A page over roughly a thousand words is usually two ideas that grew together. Read it and look for the seam. Next The four page types page-types.md", "links": [{"to": "04-structuring/page-types", "label": "The four page types"}]}, {"id": "04-structuring/page-types", "path": "docs/04-structuring/page-types.md", "section": "04-structuring", "section_title": "Structuring", "title": "The four page types", "html": "<p>Four types, each with a job. Every page declares its type in frontmatter, which\nis what lets you query the vault by shape rather than reading everything.</p>\n<h2 id=\"sources\">Sources</h2>\n<p>One page per ingested item. What this article, video, paper or conversation\nsaid.</p>\n<p>Records claims as claims: this source says X, with the URL, author and date\nattached. It does not evaluate. It does not merge in what other sources think.</p>\n<p>Source pages are the audit trail. When a concept page says something surprising,\nthe source pages behind it are how you check whether it was ever true.</p>\n<h2 id=\"entities\">Entities</h2>\n<p>People, organisations, products, tools. What it is, why it appears in your\nvault, and everything that mentions it.</p>\n<p>Entity pages are cheap to create and pay off in a way that is not obvious until\nthe vault is large. They become the natural join points: three unrelated sources\nthat all mention the same company suddenly connect through it, and that\nconnection is often the thing worth noticing.</p>\n<p>Do not write biographies. An entity page holds what is relevant to your vault,\nnot what Wikipedia holds.</p>\n<h2 id=\"concepts\">Concepts</h2>\n<p>Ideas, methods, frameworks, arguments. These are the pages that compound.</p>\n<p>A concept page explains the idea in plain language, says where it came from,\nwhat supports it, what argues against it, and what is still unclear. Written\nwell, it is readable by someone who has seen none of your sources, including\nyou in a year.</p>\n<p>This is the only page type where the agent should be synthesising across\nsources rather than recording.</p>\n<h2 id=\"synthesis\">Synthesis</h2>\n<p>Comparisons, themes, open questions. A synthesis page exists only when it says\nsomething no single source did: two sources disagree, three describe the same\npattern, a question keeps recurring across unrelated material.</p>\n<p>The rule that keeps these honest: do not write a synthesis page to have one. An\nagent asked for synthesis will always produce something, and manufactured themes\nare the fastest way to fill a wiki with confident nonsense.</p>\n<h2 id=\"where-the-types-blur\">Where the types blur</h2>\n<p>Some things are legitimately two types. A methodology named after its author is\nboth an entity and a concept. Pick one, usually the concept, and give the other\nan alias pointing at it.</p>\n<p>Some things are neither. A recipe, a config snippet, a checklist. Those are\nreference material, not knowledge, and they belong in a project folder rather\nthan the wiki.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"linking-rules.md\">Linking rules</a></p>", "headings": ["Sources", "Entities", "Concepts", "Synthesis", "Where the types blur", "Next"], "words": 400, "text": "Four types, each with a job. Every page declares its type in frontmatter, which is what lets you query the vault by shape rather than reading everything. Sources One page per ingested item. What this article, video, paper or conversation said. Records claims as claims: this source says X, with the URL, author and date attached. It does not evaluate. It does not merge in what other sources think. Source pages are the audit trail. When a concept page says something surprising, the source pages behind it are how you check whether it was ever true. Entities People, organisations, products, tools. What it is, why it appears in your vault, and everything that mentions it. Entity pages are cheap to create and pay off in a way that is not obvious until the vault is large. They become the natural join points: three unrelated sources that all mention the same company suddenly connect through it, and that connection is often the thing worth noticing. Do not write biographies. An entity page holds what is relevant to your vault, not what Wikipedia holds. Concepts Ideas, methods, frameworks, arguments. These are the pages that compound. A concept page explains the idea in plain language, says where it came from, what supports it, what argues against it, and what is still unclear. Written well, it is readable by someone who has seen none of your sources, including you in a year. This is the only page type where the agent should be synthesising across sources rather than recording. Synthesis Comparisons, themes, open questions. A synthesis page exists only when it says something no single source did: two sources disagree, three describe the same pattern, a question keeps recurring across unrelated material. The rule that keeps these honest: do not write a synthesis page to have one. An agent asked for synthesis will always produce something, and manufactured themes are the fastest way to fill a wiki with confident nonsense. Where the types blur Some things are legitimately two types. A methodology named after its author is both an entity and a concept. Pick one, usually the concept, and give the other an alias pointing at it. Some things are neither. A recipe, a config snippet, a checklist. Those are reference material, not knowledge, and they belong in a project folder rather than the wiki. Next Linking rules linking-rules.md", "links": [{"to": "04-structuring/linking-rules", "label": "Linking rules"}]}, {"id": "04-structuring/linking-rules", "path": "docs/04-structuring/linking-rules.md", "section": "04-structuring", "section_title": "Structuring", "title": "Linking rules", "html": "<p>Links are the entire value of the structure. Without them you have a folder of\nfiles with good filenames, which is a search index, and search indexes already\nexist.</p>\n<h2 id=\"the-rule\">The rule</h2>\n<p>Link the first mention of any concept or entity, on every page.</p>\n<p>That is it. Applied consistently, it produces the graph on its own, with no\nseparate linking pass and no maintenance ritual.</p>\n<h2 id=\"link-do-not-restate\">Link, do not restate</h2>\n<p>If you are explaining something that already has a page, link it and move on.</p>\n<p>This is what keeps knowledge in one place. When the explanation of a concept\nlives on four pages in four slightly different versions, updating it means\nfinding all four, and you will not. Linked, it lives once and improves once.</p>\n<h2 id=\"both-directions\">Both directions</h2>\n<p>A new page links out to what it references. What it references links back.</p>\n<p>One-directional linking produces pages that reference the vault but that the\nvault never reaches. They exist, they are correct, and nothing finds them.\nObsidian shows unlinked backlinks, which helps you spot these, but the agent\nshould be closing the loop at ingest rather than leaving it to you.</p>\n<h2 id=\"links-that-do-not-exist-yet\">Links that do not exist yet</h2>\n<p>Write the link anyway, then either create the target page in the same run or\nrecord it under Gaps in <code>index.md</code>.</p>\n<p>Gaps are useful information. A page that three sources have linked to and that\ndoes not exist yet is exactly what to write next, or exactly what to go read\nabout.</p>\n<p>What is not acceptable is a permanent gap. Links to pages that will never exist\nmake the graph lie about its own coverage.</p>\n<h2 id=\"how-many\">How many</h2>\n<p>There is no target number, but the shape matters. A page with no outbound links\nis a dead end. A page with forty is usually a list pretending to be a page.</p>\n<p>Watch the average across the vault rather than any single page. Below roughly\ntwo links per page, the graph is not connected enough to answer anything the\nindividual pages could not. Track it with <code>scripts/vault_stats.py</code>.</p>\n<h2 id=\"hub-pages\">Hub pages</h2>\n<p>Some pages accumulate links until everything routes through them. A general\nconcept that every source touches becomes a hub, and once it is a hub, the graph\naround it stops being informative: everything is two hops from everything.</p>\n<p>The fix is to split the hub into the specific ideas people are actually linking\nto. If forty pages link to a single broad concept, they are linking to four\ndifferent aspects of it.</p>\n<h2 id=\"decorative-links\">Decorative links</h2>\n<p>A link is a claim that two pages are related in a way worth following. Links\nadded because a word happened to appear are noise, and enough of them make the\ngraph unusable in exactly the way an empty graph is unusable.</p>\n<p>The test: would you follow this link while researching the topic? If not,\ndelete it.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"frontmatter-schema.md\">Frontmatter schema</a></p>", "headings": ["The rule", "Link, do not restate", "Both directions", "Links that do not exist yet", "How many", "Hub pages", "Decorative links", "Next"], "words": 481, "text": "Links are the entire value of the structure. Without them you have a folder of files with good filenames, which is a search index, and search indexes already exist. The rule Link the first mention of any concept or entity, on every page. That is it. Applied consistently, it produces the graph on its own, with no separate linking pass and no maintenance ritual. Link, do not restate If you are explaining something that already has a page, link it and move on. This is what keeps knowledge in one place. When the explanation of a concept lives on four pages in four slightly different versions, updating it means finding all four, and you will not. Linked, it lives once and improves once. Both directions A new page links out to what it references. What it references links back. One-directional linking produces pages that reference the vault but that the vault never reaches. They exist, they are correct, and nothing finds them. Obsidian shows unlinked backlinks, which helps you spot these, but the agent should be closing the loop at ingest rather than leaving it to you. Links that do not exist yet Write the link anyway, then either create the target page in the same run or record it under Gaps in index.md . Gaps are useful information. A page that three sources have linked to and that does not exist yet is exactly what to write next, or exactly what to go read about. What is not acceptable is a permanent gap. Links to pages that will never exist make the graph lie about its own coverage. How many There is no target number, but the shape matters. A page with no outbound links is a dead end. A page with forty is usually a list pretending to be a page. Watch the average across the vault rather than any single page. Below roughly two links per page, the graph is not connected enough to answer anything the individual pages could not. Track it with scripts/vault_stats.py . Hub pages Some pages accumulate links until everything routes through them. A general concept that every source touches becomes a hub, and once it is a hub, the graph around it stops being informative: everything is two hops from everything. The fix is to split the hub into the specific ideas people are actually linking to. If forty pages link to a single broad concept, they are linking to four different aspects of it. Decorative links A link is a claim that two pages are related in a way worth following. Links added because a word happened to appear are noise, and enough of them make the graph unusable in exactly the way an empty graph is unusable. The test: would you follow this link while researching the topic? If not, delete it. Next Frontmatter schema frontmatter-schema.md", "links": [{"to": "04-structuring/frontmatter-schema", "label": "Frontmatter schema"}]}, {"id": "04-structuring/frontmatter-schema", "path": "docs/04-structuring/frontmatter-schema.md", "section": "04-structuring", "section_title": "Structuring", "title": "Frontmatter schema", "html": "<p>Frontmatter is what makes the vault queryable by something other than text\nsearch. It costs nothing to write and it is what Dataview, scripts and the agent\nitself use to find things by shape.</p>\n<h2 id=\"the-schema\">The schema</h2>\n<pre><code class=\"language-yaml\">---\ntitle: Canonical name\ntype: source | entity | concept | synthesis\ncreated: YYYY-MM-DD\nupdated: YYYY-MM-DD\naliases: [other names this is known by]\ntags: [two or three]\n---\n</code></pre>\n<p>Source pages add:</p>\n<pre><code class=\"language-yaml\">url: https://...\nauthor:\npublished: YYYY-MM-DD\n</code></pre>\n<p>Entity pages add <code>kind: person | org | product | tool</code>.</p>\n<h2 id=\"why-each-field-earns-its-place\">Why each field earns its place</h2>\n<p><code>type</code> drives every structural query and every lint check. Without it you cannot\nask how many concepts you have, or find sources with no concepts attached.</p>\n<p><code>updated</code> is what makes review possible. Stale concept pages are the main way a\nvault rots, and you cannot find them without a date.</p>\n<p><code>aliases</code> is what makes wikilinks resolve when the same thing has three names.\nSee <a href=\"naming-and-aliases.md\">naming and aliases</a>.</p>\n<p><code>url</code> on a source page is what separates a citation from a claim. A source page\nwithout it is unverifiable.</p>\n<h2 id=\"tags\">Tags</h2>\n<p>Two or three per page, from a small controlled vocabulary you actually maintain.</p>\n<p>Tags fail in one specific way: the vocabulary grows until it is meaningless.\nFifty tags used once each are worse than no tags, because they create the\nimpression of a taxonomy while doing none of the work.</p>\n<p>Keep the list in <code>CLAUDE.md</code> and instruct the agent to use existing tags or\npropose a new one explicitly rather than inventing them silently.</p>\n<p>Folders and links carry the structural load. Tags are for cross-cutting\nqualities that do not fit either: <code>unverified</code>, <code>to-revisit</code>, <code>disputed</code>.</p>\n<h2 id=\"empty-fields\">Empty fields</h2>\n<p>Leave a field out rather than filling it with a guess. An absent <code>published</code>\nmeans unknown, which the agent can say honestly. A guessed date becomes a fact\nin a concept page three weeks later.</p>\n<h2 id=\"keep-it-stable\">Keep it stable</h2>\n<p>Adding a field to the schema means either backfilling every page or living with\na mixed vault where queries miss the older half.</p>\n<p>Decide the schema early, keep it small, and change it rarely. When you do change\nit, run a backfill pass over the whole vault in one go rather than letting the\nchange apply only to new pages.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"naming-and-aliases.md\">Naming and aliases</a></p>", "headings": ["The schema", "Why each field earns its place", "Tags", "Empty fields", "Keep it stable", "Next"], "words": 385, "text": "Frontmatter is what makes the vault queryable by something other than text search. It costs nothing to write and it is what Dataview, scripts and the agent itself use to find things by shape. The schema yaml --- title: Canonical name type: source | entity | concept | synthesis created: YYYY-MM-DD updated: YYYY-MM-DD aliases: other names this is known by tags: two or three --- Source pages add: yaml url: https://... author: published: YYYY-MM-DD Entity pages add kind: person | org | product | tool . Why each field earns its place type drives every structural query and every lint check. Without it you cannot ask how many concepts you have, or find sources with no concepts attached. updated is what makes review possible. Stale concept pages are the main way a vault rots, and you cannot find them without a date. aliases is what makes wikilinks resolve when the same thing has three names. See naming and aliases naming-and-aliases.md . url on a source page is what separates a citation from a claim. A source page without it is unverifiable. Tags Two or three per page, from a small controlled vocabulary you actually maintain. Tags fail in one specific way: the vocabulary grows until it is meaningless. Fifty tags used once each are worse than no tags, because they create the impression of a taxonomy while doing none of the work. Keep the list in CLAUDE.md and instruct the agent to use existing tags or propose a new one explicitly rather than inventing them silently. Folders and links carry the structural load. Tags are for cross-cutting qualities that do not fit either: unverified , to-revisit , disputed . Empty fields Leave a field out rather than filling it with a guess. An absent published means unknown, which the agent can say honestly. A guessed date becomes a fact in a concept page three weeks later. Keep it stable Adding a field to the schema means either backfilling every page or living with a mixed vault where queries miss the older half. Decide the schema early, keep it small, and change it rarely. When you do change it, run a backfill pass over the whole vault in one go rather than letting the change apply only to new pages. Next Naming and aliases naming-and-aliases.md", "links": [{"to": "04-structuring/naming-and-aliases", "label": "naming and aliases"}, {"to": "04-structuring/naming-and-aliases", "label": "Naming and aliases"}]}, {"id": "04-structuring/naming-and-aliases", "path": "docs/04-structuring/naming-and-aliases.md", "section": "04-structuring", "section_title": "Structuring", "title": "Naming and aliases", "html": "<p>Wikilinks resolve by name, so the name is not cosmetic. It is the key the whole\ngraph is built on.</p>\n<h2 id=\"canonical-titles\">Canonical titles</h2>\n<p>One page, one canonical title, and it is the name you would use talking to\nsomeone in the field.</p>\n<p>Practical rules that avoid most of the pain:</p>\n<ul>\n<li><strong>Singular, not plural.</strong> <code>Vector database</code>, not <code>Vector databases</code>.</li>\n<li><strong>Spell out acronyms in the title, put the acronym in aliases.</strong> The title is\n for the reader, the alias is for the link.</li>\n<li><strong>No dates, no versions in the title</strong> unless the thing genuinely is a\n version. A page called <code>MCP spec 2026-07</code> becomes wrong in a month; a page\n called <code>MCP</code> with a version history does not.</li>\n<li><strong>No your-vault-specific prefixes.</strong> <code>Concept - RAG</code> fights the link syntax\n for no benefit.</li>\n</ul>\n<h2 id=\"aliases\">Aliases</h2>\n<p>Everything the same subject gets called, listed in frontmatter:</p>\n<pre><code class=\"language-yaml\">title: Retrieval augmented generation\naliases: [RAG, retrieval-augmented generation]\n</code></pre>\n<p>Aliases are what stop the vault from quietly growing three pages for one thing.\nWithout the alias, a source that says RAG creates <code>RAG</code>, and a source that\nspells it out creates a second page, and neither knows about the other.</p>\n<p>Add aliases at creation, not later. By the time you notice the duplicate, both\npages have inbound links.</p>\n<h2 id=\"two-things-with-the-same-name\">Two things with the same name</h2>\n<p>Disambiguate in the title, not with a suffix nobody would type:</p>\n<pre><code>Mercury (planet)\nMercury (element)\n</code></pre>\n<p>Then alias the bare word to whichever one is dominant in your vault, or to\nneither if both matter, which forces the agent to pick explicitly rather than\nguessing.</p>\n<p>Same applies to people who share a name and to your own projects that collide\nwith a well-known product.</p>\n<h2 id=\"renaming\">Renaming</h2>\n<p>Obsidian updates links when you rename inside the app. The agent renaming a file\ndirectly does not, and that is the single most common source of broken links in\nan agent-maintained vault.</p>\n<p>Rule for <code>CLAUDE.md</code>: renames go through a documented procedure. Update the\nfile, update every inbound link, add the old name as an alias, and record it in\n<code>log.md</code>. The alias matters because it keeps external references and your own\nmemory working.</p>\n<p>Then run <code>scripts/link_check.py</code> to confirm nothing dangled.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"dedupe-and-merge.md\">Deduplication and merging</a></p>", "headings": ["Canonical titles", "Aliases", "Two things with the same name", "Renaming", "Next"], "words": 372, "text": "Wikilinks resolve by name, so the name is not cosmetic. It is the key the whole graph is built on. Canonical titles One page, one canonical title, and it is the name you would use talking to someone in the field. Practical rules that avoid most of the pain: - Singular, not plural. Vector database , not Vector databases . - Spell out acronyms in the title, put the acronym in aliases. The title is for the reader, the alias is for the link. - No dates, no versions in the title unless the thing genuinely is a version. A page called MCP spec 2026-07 becomes wrong in a month; a page called MCP with a version history does not. - No your-vault-specific prefixes. Concept - RAG fights the link syntax for no benefit. Aliases Everything the same subject gets called, listed in frontmatter: yaml title: Retrieval augmented generation aliases: RAG, retrieval-augmented generation Aliases are what stop the vault from quietly growing three pages for one thing. Without the alias, a source that says RAG creates RAG , and a source that spells it out creates a second page, and neither knows about the other. Add aliases at creation, not later. By the time you notice the duplicate, both pages have inbound links. Two things with the same name Disambiguate in the title, not with a suffix nobody would type: Mercury planet Mercury element Then alias the bare word to whichever one is dominant in your vault, or to neither if both matter, which forces the agent to pick explicitly rather than guessing. Same applies to people who share a name and to your own projects that collide with a well-known product. Renaming Obsidian updates links when you rename inside the app. The agent renaming a file directly does not, and that is the single most common source of broken links in an agent-maintained vault. Rule for CLAUDE.md : renames go through a documented procedure. Update the file, update every inbound link, add the old name as an alias, and record it in log.md . The alias matters because it keeps external references and your own memory working. Then run scripts/link_check.py to confirm nothing dangled. Next Deduplication and merging dedupe-and-merge.md", "links": [{"to": "04-structuring/dedupe-and-merge", "label": "Deduplication and merging"}]}, {"id": "04-structuring/dedupe-and-merge", "path": "docs/04-structuring/dedupe-and-merge.md", "section": "04-structuring", "section_title": "Structuring", "title": "Deduplication and merging", "html": "<p>Duplicates are inevitable. Two sources use different words for the same idea, an\nalias was missing, a bulk import ran before the vault had the concept. The\nquestion is not how to prevent them entirely but how to catch them before they\nboth accumulate links.</p>\n<h2 id=\"finding-them\">Finding them</h2>\n<p>Signals, in order of reliability:</p>\n<ul>\n<li><strong>Similar titles.</strong> Cheap to check, catches the plural and acronym cases.</li>\n<li><strong>Overlapping aliases.</strong> Two pages claiming the same alias is always a bug.</li>\n<li><strong>Shared inbound links.</strong> Two pages that the same five sources both link to\n are usually one page.</li>\n<li><strong>Content similarity.</strong> Expensive, but catches the cases where the names look\n unrelated.</li>\n</ul>\n<p><code>second-brain-lint</code> runs the first three and proposes merges. It does not\nperform them, which is deliberate.</p>\n<h2 id=\"why-merging-is-not-automatic\">Why merging is not automatic</h2>\n<p>A merge is irreversible in the way that matters: once two pages are one, you\ncannot tell which claim came from which, and the agent's judgement about \"these\nare the same thing\" is exactly the judgement that goes wrong.</p>\n<p>Two ideas that look identical from their summaries are often a general case and\na specific one, and merging them loses the distinction permanently.</p>\n<p>So: the agent proposes, you decide. Reviewing a merge takes fifteen seconds.</p>\n<h2 id=\"the-procedure\">The procedure</h2>\n<p>When you approve one:</p>\n<ol>\n<li><strong>Pick the survivor</strong> by canonical name, not by which is longer.</li>\n<li><strong>Merge content,</strong> keeping every distinct claim with its source. Overlapping\n claims collapse, differing ones both stay.</li>\n<li><strong>Merge aliases,</strong> including the dead page's title as an alias on the\n survivor.</li>\n<li><strong>Redirect inbound links</strong> to the survivor.</li>\n<li><strong>Leave a stub</strong> at the old path only if it was linked from outside the\n vault. Otherwise delete it.</li>\n<li><strong>Record it in <code>log.md</code></strong> with both names, so a page that vanishes is\n traceable.</li>\n</ol>\n<p>Step 6 is the one agents skip and the one you will need. A page that disappears\nwithout a record is indistinguishable from a page that was deleted by mistake.</p>\n<h2 id=\"do-not-dedupe-live\">Do not dedupe live</h2>\n<p>Merging during an ingest run means the agent is restructuring the vault while\nadding to it, and a bad merge lands in the middle of otherwise good work.</p>\n<p>Run dedupe as its own pass, weekly or after a large import, on a clean git\nstate. Then a wrong merge is one <code>git checkout</code> away from undone.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"contradictions-and-supersession.md\">Contradictions and supersession</a></p>", "headings": ["Finding them", "Why merging is not automatic", "The procedure", "Do not dedupe live", "Next"], "words": 394, "text": "Duplicates are inevitable. Two sources use different words for the same idea, an alias was missing, a bulk import ran before the vault had the concept. The question is not how to prevent them entirely but how to catch them before they both accumulate links. Finding them Signals, in order of reliability: - Similar titles. Cheap to check, catches the plural and acronym cases. - Overlapping aliases. Two pages claiming the same alias is always a bug. - Shared inbound links. Two pages that the same five sources both link to are usually one page. - Content similarity. Expensive, but catches the cases where the names look unrelated. second-brain-lint runs the first three and proposes merges. It does not perform them, which is deliberate. Why merging is not automatic A merge is irreversible in the way that matters: once two pages are one, you cannot tell which claim came from which, and the agent's judgement about \"these are the same thing\" is exactly the judgement that goes wrong. Two ideas that look identical from their summaries are often a general case and a specific one, and merging them loses the distinction permanently. So: the agent proposes, you decide. Reviewing a merge takes fifteen seconds. The procedure When you approve one: 1. Pick the survivor by canonical name, not by which is longer. 2. Merge content, keeping every distinct claim with its source. Overlapping claims collapse, differing ones both stay. 3. Merge aliases, including the dead page's title as an alias on the survivor. 4. Redirect inbound links to the survivor. 5. Leave a stub at the old path only if it was linked from outside the vault. Otherwise delete it. 6. Record it in log.md with both names, so a page that vanishes is traceable. Step 6 is the one agents skip and the one you will need. A page that disappears without a record is indistinguishable from a page that was deleted by mistake. Do not dedupe live Merging during an ingest run means the agent is restructuring the vault while adding to it, and a bad merge lands in the middle of otherwise good work. Run dedupe as its own pass, weekly or after a large import, on a clean git state. Then a wrong merge is one git checkout away from undone. Next Contradictions and supersession contradictions-and-supersession.md", "links": [{"to": "04-structuring/contradictions-and-supersession", "label": "Contradictions and supersession"}]}, {"id": "04-structuring/contradictions-and-supersession", "path": "docs/04-structuring/contradictions-and-supersession.md", "section": "04-structuring", "section_title": "Structuring", "title": "Contradictions and supersession", "html": "<p>This is the rule that separates a second brain from a search engine, and the one\nmost implementations get wrong.</p>\n<p>When a new source disagrees with what a page already says, the page records\nboth. It does not overwrite.</p>\n<h2 id=\"why-overwriting-is-the-worst-failure-mode\">Why overwriting is the worst failure mode</h2>\n<p>A vault that silently updates to the latest claim has no memory of what you\nbelieved and why. It always presents the most recent thing you read as the\ntruth, which is a ranking by recency, not by evidence.</p>\n<p>Worse, it is invisible. Nothing errors. The page simply says something different\nthan it did last month, with the same confidence, and you have no way to notice\nor to check what changed.</p>\n<p>The history is the asset. Knowing that you believed X because of a 2024 source,\nthen revised to Y after better evidence, is more valuable than either claim\nalone, because it tells you how firm Y actually is.</p>\n<h2 id=\"what-a-contradiction-looks-like-on-a-page\">What a contradiction looks like on a page</h2>\n<p>Both positions, each attributed and dated:</p>\n<pre><code class=\"language-markdown\">## Current position\n\nRetrieval quality degrades past roughly 50k tokens of context\n([[Lost in the Middle]], 2023).\n\n## Contested\n\n[[Some 2026 benchmark]] reports no degradation up to 200k on the same task\nfamily. The two use different evaluation setups: the first measures position\nsensitivity, the second end-task accuracy. Unresolved.\n</code></pre>\n<p>The reader can act on that. A page that had silently adopted whichever was\ningested last cannot be acted on at all.</p>\n<h2 id=\"supersession\">Supersession</h2>\n<p>Sometimes it is not a genuine disagreement, it is old information. A tool\nchanged its API, a company was acquired, a paper was retracted.</p>\n<p>Mark the old claim as superseded and keep it:</p>\n<pre><code class=\"language-markdown\">~~Requires Node 18 or later~~ superseded 2026-05: the native installer no\nlonger requires Node ([[source]]).\n</code></pre>\n<p>Deleting it means that when you read something written before the change, you\nhave no way to reconcile it with what the vault now says.</p>\n<h2 id=\"confidence\">Confidence</h2>\n<p>Not everything ingested deserves equal weight. A tag or a frontmatter field is\nenough:</p>\n<ul>\n<li><strong>stated</strong> by a primary source you trust</li>\n<li><strong>reported</strong> by secondary coverage</li>\n<li><strong>self-reported</strong> by the party it benefits</li>\n<li><strong>unverified</strong></li>\n</ul>\n<p>Self-reported numbers in particular should never lose that label. A company's\nown performance claim repeated as fact in a concept page is how a vault becomes\nconfidently wrong.</p>\n<h2 id=\"the-instruction\">The instruction</h2>\n<p>In <code>CLAUDE.md</code>, worded so it generalises rather than covering only the obvious\ncase:</p>\n<pre><code>When a new source disagrees with an existing page, do not overwrite. Record both\npositions with sources and dates, and say what would settle it. If the new\nsource is clearly better evidence, mark the older claim superseded rather than\ndeleting it. Never resolve a contradiction by picking the more recent source.\n</code></pre>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"index-and-log.md\">index.md and log.md</a></p>", "headings": ["Why overwriting is the worst failure mode", "What a contradiction looks like on a page", "Current position", "Contested", "Supersession", "Confidence", "The instruction", "Next"], "words": 463, "text": "This is the rule that separates a second brain from a search engine, and the one most implementations get wrong. When a new source disagrees with what a page already says, the page records both. It does not overwrite. Why overwriting is the worst failure mode A vault that silently updates to the latest claim has no memory of what you believed and why. It always presents the most recent thing you read as the truth, which is a ranking by recency, not by evidence. Worse, it is invisible. Nothing errors. The page simply says something different than it did last month, with the same confidence, and you have no way to notice or to check what changed. The history is the asset. Knowing that you believed X because of a 2024 source, then revised to Y after better evidence, is more valuable than either claim alone, because it tells you how firm Y actually is. What a contradiction looks like on a page Both positions, each attributed and dated: markdown Current position Retrieval quality degrades past roughly 50k tokens of context Lost in the Middle , 2023 . Contested Some 2026 benchmark reports no degradation up to 200k on the same task family. The two use different evaluation setups: the first measures position sensitivity, the second end-task accuracy. Unresolved. The reader can act on that. A page that had silently adopted whichever was ingested last cannot be acted on at all. Supersession Sometimes it is not a genuine disagreement, it is old information. A tool changed its API, a company was acquired, a paper was retracted. Mark the old claim as superseded and keep it: markdown ~~Requires Node 18 or later~~ superseded 2026-05: the native installer no longer requires Node source . Deleting it means that when you read something written before the change, you have no way to reconcile it with what the vault now says. Confidence Not everything ingested deserves equal weight. A tag or a frontmatter field is enough: - stated by a primary source you trust - reported by secondary coverage - self-reported by the party it benefits - unverified Self-reported numbers in particular should never lose that label. A company's own performance claim repeated as fact in a concept page is how a vault becomes confidently wrong. The instruction In CLAUDE.md , worded so it generalises rather than covering only the obvious case: When a new source disagrees with an existing page, do not overwrite. Record both positions with sources and dates, and say what would settle it. If the new source is clearly better evidence, mark the older claim superseded rather than deleting it. Never resolve a contradiction by picking the more recent source. Next index.md and log.md index-and-log.md", "links": [{"to": "04-structuring/index-and-log", "label": "index.md and log.md"}]}, {"id": "04-structuring/index-and-log", "path": "docs/04-structuring/index-and-log.md", "section": "04-structuring", "section_title": "Structuring", "title": "index.md and log.md", "html": "<p>Two files that are not knowledge, but without which the knowledge is hard to\nreach and impossible to audit.</p>\n<h2 id=\"indexmd\">index.md</h2>\n<p>The catalog. Every page, grouped by type, with the gaps listed at the bottom.</p>\n<p>Its real job is retrieval economy. When the agent gets a question, reading the\nindex first tells it what exists and which pages are worth opening. Without it,\nthe alternative is a full-text sweep, which is slower, costs more context, and\nmisses pages whose wording differs from the question.</p>\n<p>Keep it navigable rather than exhaustive-looking:</p>\n<pre><code class=\"language-markdown\">## Concepts\n\n### Retrieval\n- [[Retrieval augmented generation]] - chunking, embeddings, when it beats a wiki\n- [[GraphRAG]] - entity graph plus community summaries\n\n### Agents\n- [[Agent harness]] - the loop around a model\n</code></pre>\n<p>One line of description per entry. That line is what lets the agent decide\nwhether to open the page, and it is worth the tokens.</p>\n<h2 id=\"gaps\">Gaps</h2>\n<p>At the bottom of the index, the pages that are linked and do not exist.</p>\n<p>This section is the most actionable thing in the vault. It is a list of what\nyour own material keeps referring to and you have never written down, which is\nusually a precise map of what to read next.</p>\n<h2 id=\"logmd\">log.md</h2>\n<p>One line per operation, appended, newest at the bottom.</p>\n<pre><code>2026-09-07 ingest raw/karpathy-gist.md -> 1 source, 2 concepts, 1 entity, 9 links\n2026-09-07 merge [[RAG]] <- [[Retrieval-augmented generation]]\n2026-09-08 lint -> 3 broken links fixed, 2 orphans flagged\n</code></pre>\n<p>The log is what makes an agent-maintained vault auditable. When a page says\nsomething you do not recognise, the log tells you which run produced it. When\nsomething disappears, the log is the difference between a traceable merge and a\nmystery.</p>\n<p>It also gives the <a href=\"../../skills/README.md\">review skill</a> its raw material: what\nchanged this week comes from here, not from guessing at file timestamps.</p>\n<h2 id=\"keeping-both-from-bloating\">Keeping both from bloating</h2>\n<p>The index grows with the vault, which is fine, but flat lists stop being\nnavigable somewhere around two hundred entries. Group by theme, and once a theme\nhas more than about thirty entries, give it its own index page and link it from\nthe main one.</p>\n<p>The log grows forever and nobody reads old entries. Roll entries older than a\nfew months into one summary line per month, or archive them into a dated file.\nKeep recent detail, compress history.</p>\n<h2 id=\"the-rule-that-matters\">The rule that matters</h2>\n<p>Both files update in the same run as the work they describe.</p>\n<p>An index that lags is worse than no index, because the agent trusts it and stops\nlooking for pages it does not list. A log written later is a reconstruction, not\na record.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"../05-graphs/README.md\">Graphs</a>, where these structures start paying off.</p>", "headings": ["index.md", "Concepts", "Gaps", "log.md", "Keeping both from bloating", "The rule that matters", "Next"], "words": 456, "text": "Two files that are not knowledge, but without which the knowledge is hard to reach and impossible to audit. index.md The catalog. Every page, grouped by type, with the gaps listed at the bottom. Its real job is retrieval economy. When the agent gets a question, reading the index first tells it what exists and which pages are worth opening. Without it, the alternative is a full-text sweep, which is slower, costs more context, and misses pages whose wording differs from the question. Keep it navigable rather than exhaustive-looking: markdown Concepts Retrieval - Retrieval augmented generation - chunking, embeddings, when it beats a wiki - GraphRAG - entity graph plus community summaries Agents - Agent harness - the loop around a model One line of description per entry. That line is what lets the agent decide whether to open the page, and it is worth the tokens. Gaps At the bottom of the index, the pages that are linked and do not exist. This section is the most actionable thing in the vault. It is a list of what your own material keeps referring to and you have never written down, which is usually a precise map of what to read next. log.md One line per operation, appended, newest at the bottom. 2026-09-07 ingest raw/karpathy-gist.md - 1 source, 2 concepts, 1 entity, 9 links 2026-09-07 merge RAG <- Retrieval-augmented generation 2026-09-08 lint - 3 broken links fixed, 2 orphans flagged The log is what makes an agent-maintained vault auditable. When a page says something you do not recognise, the log tells you which run produced it. When something disappears, the log is the difference between a traceable merge and a mystery. It also gives the review skill ../../skills/README.md its raw material: what changed this week comes from here, not from guessing at file timestamps. Keeping both from bloating The index grows with the vault, which is fine, but flat lists stop being navigable somewhere around two hundred entries. Group by theme, and once a theme has more than about thirty entries, give it its own index page and link it from the main one. The log grows forever and nobody reads old entries. Roll entries older than a few months into one summary line per month, or archive them into a dated file. Keep recent detail, compress history. The rule that matters Both files update in the same run as the work they describe. An index that lags is worse than no index, because the agent trusts it and stops looking for pages it does not list. A log written later is a reconstruction, not a record. Next Graphs ../05-graphs/README.md , where these structures start paying off.", "links": []}, {"id": "05-graphs/graph-basics", "path": "docs/05-graphs/graph-basics.md", "section": "05-graphs", "section_title": "Graphs", "title": "Graph basics for a knowledge base", "html": "<p>Your vault is a graph whether you plan it or not. Pages are nodes, wikilinks are\nedges. Every structural decision in the previous section was a decision about\nwhat shape that graph takes.</p>\n<p>Four terms are enough to reason about it.</p>\n<p><strong>Degree</strong> is how many links a page has. In-degree is how many point at it,\nout-degree how many it points out. A page with zero in-degree is unreachable by\nfollowing links, which is what makes orphans a problem rather than a cosmetic\nissue.</p>\n<p><strong>Path length</strong> is how many hops separate two pages. This is the one that\nmatters for answers: the agent following links from a starting page can only\nreach what is a few hops away before the context budget runs out. Two related\nideas eight hops apart will never be connected in an answer.</p>\n<p><strong>Clustering</strong> is how much a page's neighbours link to each other. High\nclustering means a genuine topic area. Low clustering with high degree usually\nmeans a page that collects unrelated things.</p>\n<p><strong>Components</strong> are the disconnected islands. A vault in five components is five\nvaults, and nothing in one will ever inform an answer about another.</p>\n<h2 id=\"the-shapes-that-go-wrong\">The shapes that go wrong</h2>\n<p><strong>The star.</strong> Everything links to two or three hub pages and to nothing else.\nPath length between any two leaves is short, but only through the hub, so the\ngraph tells you nothing beyond \"these are all in my vault\". Usually caused by\nlinking to broad concepts instead of specific ones.</p>\n<p><strong>The chain.</strong> Sources link to the concept they introduced and nothing links\nsideways. Common after a bulk import that ran without checking existing pages.\nThe vault grows and never connects.</p>\n<p><strong>Islands.</strong> Distinct topic clusters with no bridges. Sometimes legitimate: your\ncooking notes and your database notes genuinely do not connect. Often not: two\nclusters about related things that were built under different vocabulary and\nnever linked because the aliases were missing.</p>\n<h2 id=\"what-a-healthy-graph-looks-like\">What a healthy graph looks like</h2>\n<p>Dense within topics, sparse but present between them. Most pages reachable from\nmost pages within three or four hops. Hubs that exist but do not dominate. A\nsmall number of bridge pages that connect clusters, which are usually your most\nvaluable pages, because they hold the connections you could not have made from\none source alone.</p>\n<h2 id=\"why-any-of-this-matters\">Why any of this matters</h2>\n<p>When you ask the vault something, the agent starts at the pages that match and\nwalks outward. The graph is the search space. A well-shaped graph means the walk\nreaches the relevant material in a few hops; a badly shaped one means it either\nreaches nothing or reaches everything.</p>\n<p>That is the whole argument for the linking rules. They are not tidiness, they\nare what determines whether retrieval works.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"obsidian-graph-view.md\">Reading the Obsidian graph view</a></p>", "headings": ["The shapes that go wrong", "What a healthy graph looks like", "Why any of this matters", "Next"], "words": 465, "text": "Your vault is a graph whether you plan it or not. Pages are nodes, wikilinks are edges. Every structural decision in the previous section was a decision about what shape that graph takes. Four terms are enough to reason about it. Degree is how many links a page has. In-degree is how many point at it, out-degree how many it points out. A page with zero in-degree is unreachable by following links, which is what makes orphans a problem rather than a cosmetic issue. Path length is how many hops separate two pages. This is the one that matters for answers: the agent following links from a starting page can only reach what is a few hops away before the context budget runs out. Two related ideas eight hops apart will never be connected in an answer. Clustering is how much a page's neighbours link to each other. High clustering means a genuine topic area. Low clustering with high degree usually means a page that collects unrelated things. Components are the disconnected islands. A vault in five components is five vaults, and nothing in one will ever inform an answer about another. The shapes that go wrong The star. Everything links to two or three hub pages and to nothing else. Path length between any two leaves is short, but only through the hub, so the graph tells you nothing beyond \"these are all in my vault\". Usually caused by linking to broad concepts instead of specific ones. The chain. Sources link to the concept they introduced and nothing links sideways. Common after a bulk import that ran without checking existing pages. The vault grows and never connects. Islands. Distinct topic clusters with no bridges. Sometimes legitimate: your cooking notes and your database notes genuinely do not connect. Often not: two clusters about related things that were built under different vocabulary and never linked because the aliases were missing. What a healthy graph looks like Dense within topics, sparse but present between them. Most pages reachable from most pages within three or four hops. Hubs that exist but do not dominate. A small number of bridge pages that connect clusters, which are usually your most valuable pages, because they hold the connections you could not have made from one source alone. Why any of this matters When you ask the vault something, the agent starts at the pages that match and walks outward. The graph is the search space. A well-shaped graph means the walk reaches the relevant material in a few hops; a badly shaped one means it either reaches nothing or reaches everything. That is the whole argument for the linking rules. They are not tidiness, they are what determines whether retrieval works. Next Reading the Obsidian graph view obsidian-graph-view.md", "links": [{"to": "05-graphs/obsidian-graph-view", "label": "Reading the Obsidian graph view"}]}, {"id": "05-graphs/obsidian-graph-view", "path": "docs/05-graphs/obsidian-graph-view.md", "section": "05-graphs", "section_title": "Graphs", "title": "Reading the Obsidian graph view", "html": "<p>The global graph is the screenshot everyone posts. It is the least useful view\nin the app.</p>\n<p>At two hundred pages it is a hairball, and a hairball tells you nothing except\nthat you have pages. What it is good for is spotting shape at a glance: isolated\nclumps, a single dominant hub, a scatter of unconnected dots around the edge.</p>\n<h2 id=\"local-graph\">Local graph</h2>\n<p>This is the view that does work. Open a page, show the local graph, set depth to\ntwo.</p>\n<p>You are looking for two things. What is one hop away should be obviously\nrelated; anything surprising there is either a decorative link to delete or a\nconnection worth reading. What is missing at two hops tells you where the page\nis under-connected.</p>\n<p>Reviewing the local graph of a page you just wrote is the fastest quality check\nthere is, and it takes five seconds.</p>\n<h2 id=\"filters-that-make-the-global-view-usable\">Filters that make the global view usable</h2>\n<ul>\n<li><strong>Filter by type.</strong> <code>-path:sources</code> hides source pages and leaves the concept\n graph, which is the part with meaning in it. Sources outnumber concepts\n heavily and drown them visually.</li>\n<li><strong>Groups by colour.</strong> Colour concepts, entities and synthesis differently. A\n cluster with no concept pages in it is a pile of sources nobody has processed.</li>\n<li><strong>Orphan toggle.</strong> Turn orphans on deliberately, look at what appears, then\n fix or delete them.</li>\n<li><strong>Depth and forces.</strong> Lower link force spreads clusters apart enough to see\n bridges.</li>\n</ul>\n<h2 id=\"what-to-look-for\">What to look for</h2>\n<p><strong>Dots at the edge, connected to one thing.</strong> Failed ingests, usually. The\nsource page was written and the concepts never linked back.</p>\n<p><strong>One giant node in the middle.</strong> A hub that has swallowed the graph. Split it.</p>\n<p><strong>Two clusters with a single connecting page.</strong> That page is doing real work.\nIt is also fragile: if it is wrong, both clusters are wrong about each other.</p>\n<p><strong>A cluster you do not recognise.</strong> Usually the most interesting thing on\nscreen. It means the vault has accumulated material on a topic you have not\nconsciously been tracking.</p>\n<h2 id=\"what-the-view-cannot-tell-you\">What the view cannot tell you</h2>\n<p>It shows that pages are connected, never why. Every edge looks the same whether\nit means \"supports\", \"contradicts\" or \"mentioned once in passing\".</p>\n<p>That limitation is the entire argument for the next page.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"typed-links.md\">Typed links</a></p>", "headings": ["Local graph", "Filters that make the global view usable", "What to look for", "What the view cannot tell you", "Next"], "words": 383, "text": "The global graph is the screenshot everyone posts. It is the least useful view in the app. At two hundred pages it is a hairball, and a hairball tells you nothing except that you have pages. What it is good for is spotting shape at a glance: isolated clumps, a single dominant hub, a scatter of unconnected dots around the edge. Local graph This is the view that does work. Open a page, show the local graph, set depth to two. You are looking for two things. What is one hop away should be obviously related; anything surprising there is either a decorative link to delete or a connection worth reading. What is missing at two hops tells you where the page is under-connected. Reviewing the local graph of a page you just wrote is the fastest quality check there is, and it takes five seconds. Filters that make the global view usable - Filter by type. -path:sources hides source pages and leaves the concept graph, which is the part with meaning in it. Sources outnumber concepts heavily and drown them visually. - Groups by colour. Colour concepts, entities and synthesis differently. A cluster with no concept pages in it is a pile of sources nobody has processed. - Orphan toggle. Turn orphans on deliberately, look at what appears, then fix or delete them. - Depth and forces. Lower link force spreads clusters apart enough to see bridges. What to look for Dots at the edge, connected to one thing. Failed ingests, usually. The source page was written and the concepts never linked back. One giant node in the middle. A hub that has swallowed the graph. Split it. Two clusters with a single connecting page. That page is doing real work. It is also fragile: if it is wrong, both clusters are wrong about each other. A cluster you do not recognise. Usually the most interesting thing on screen. It means the vault has accumulated material on a topic you have not consciously been tracking. What the view cannot tell you It shows that pages are connected, never why. Every edge looks the same whether it means \"supports\", \"contradicts\" or \"mentioned once in passing\". That limitation is the entire argument for the next page. Next Typed links typed-links.md", "links": [{"to": "05-graphs/typed-links", "label": "Typed links"}]}, {"id": "05-graphs/typed-links", "path": "docs/05-graphs/typed-links.md", "section": "05-graphs", "section_title": "Graphs", "title": "Typed links", "html": "<p>A plain <code>[[wikilink]]</code> says two pages are related. It does not say how, and at\nscale that is a real loss.</p>\n<p>You cannot ask an untyped graph what contradicts a claim, what evidence supports\nit, or which pages extend a method. Every edge is the same edge, so every\nquestion collapses to \"what is nearby\".</p>\n<h2 id=\"a-minimal-vocabulary\">A minimal vocabulary</h2>\n<p>Small enough to remember, expressive enough to be worth it:</p>\n<ul>\n<li><strong>supports</strong> - this page is evidence for that one</li>\n<li><strong>contradicts</strong> - this page argues against it</li>\n<li><strong>extends</strong> - builds on it, adds to it</li>\n<li><strong>part-of</strong> - a component of a larger thing</li>\n<li><strong>applies</strong> - a use of a method in practice</li>\n</ul>\n<p>Five is deliberately few. Every additional type is one the agent has to choose\nbetween correctly on every link, and a vocabulary of twenty produces\ninconsistent tagging, which is worse than none.</p>\n<h2 id=\"two-ways-to-encode-it\">Two ways to encode it</h2>\n<p><strong>Inline, next to the link:</strong></p>\n<pre><code class=\"language-markdown\">The position sensitivity result (supports:: [[Lost in the Middle]]) suggests\ncontext length alone does not fix retrieval.\n</code></pre>\n<p>Dataview reads inline fields, so this is queryable inside Obsidian without extra\ntooling.</p>\n<p><strong>In frontmatter, per page:</strong></p>\n<pre><code class=\"language-yaml\">contradicts: ["[[Long context replaces RAG]]"]\nextends: ["[[Retrieval augmented generation]]"]\n</code></pre>\n<p>Cleaner to query, further from the sentence the link came from. Frontmatter for\npage-level relationships, inline for claim-level ones.</p>\n<h2 id=\"what-it-buys-you\">What it buys you</h2>\n<pre><code class=\"language-dataview\">LIST FROM "wiki/concepts"\nWHERE contains(contradicts, this.file.link)\n</code></pre>\n<p>That is \"everything in my vault that argues against this page\", which is a\nquestion a plain graph cannot answer at all.</p>\n<p>At the agent level it is stronger still. An ingest that records a new source as\n<code>contradicts</code> an existing page has done the work of flagging the disagreement\nstructurally, rather than burying it in prose that only surfaces if someone\nreads the page.</p>\n<h2 id=\"do-not-type-everything\">Do not type everything</h2>\n<p>Most links are plain mentions and should stay plain. Typing every link makes the\nvocabulary meaningless and makes ingestion slower and more error-prone.</p>\n<p>Type the links where the relationship is the point: evidence, disagreement,\nextension. Roughly one in five links, in practice.</p>\n<h2 id=\"the-instruction\">The instruction</h2>\n<pre><code>When a source supports, contradicts or extends a claim on an existing page,\nrecord the relationship with a typed link. Plain wikilinks for ordinary\nmentions. Do not type a relationship you are inferring; only type what the\nsource states.\n</code></pre>\n<p>That last sentence matters. An agent guessing at relationships produces a graph\nthat looks rigorous and encodes its own assumptions.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"graph-vs-vectors.md\">Graph vs embeddings</a></p>", "headings": ["A minimal vocabulary", "Two ways to encode it", "What it buys you", "Do not type everything", "The instruction", "Next"], "words": 418, "text": "A plain wikilink says two pages are related. It does not say how, and at scale that is a real loss. You cannot ask an untyped graph what contradicts a claim, what evidence supports it, or which pages extend a method. Every edge is the same edge, so every question collapses to \"what is nearby\". A minimal vocabulary Small enough to remember, expressive enough to be worth it: - supports - this page is evidence for that one - contradicts - this page argues against it - extends - builds on it, adds to it - part-of - a component of a larger thing - applies - a use of a method in practice Five is deliberately few. Every additional type is one the agent has to choose between correctly on every link, and a vocabulary of twenty produces inconsistent tagging, which is worse than none. Two ways to encode it Inline, next to the link: markdown The position sensitivity result supports:: Lost in the Middle suggests context length alone does not fix retrieval. Dataview reads inline fields, so this is queryable inside Obsidian without extra tooling. In frontmatter, per page: yaml contradicts: \" Long context replaces RAG \" extends: \" Retrieval augmented generation \" Cleaner to query, further from the sentence the link came from. Frontmatter for page-level relationships, inline for claim-level ones. What it buys you dataview LIST FROM \"wiki/concepts\" WHERE contains contradicts, this.file.link That is \"everything in my vault that argues against this page\", which is a question a plain graph cannot answer at all. At the agent level it is stronger still. An ingest that records a new source as contradicts an existing page has done the work of flagging the disagreement structurally, rather than burying it in prose that only surfaces if someone reads the page. Do not type everything Most links are plain mentions and should stay plain. Typing every link makes the vocabulary meaningless and makes ingestion slower and more error-prone. Type the links where the relationship is the point: evidence, disagreement, extension. Roughly one in five links, in practice. The instruction When a source supports, contradicts or extends a claim on an existing page, record the relationship with a typed link. Plain wikilinks for ordinary mentions. Do not type a relationship you are inferring; only type what the source states. That last sentence matters. An agent guessing at relationships produces a graph that looks rigorous and encodes its own assumptions. Next Graph vs embeddings graph-vs-vectors.md", "links": [{"to": "05-graphs/graph-vs-vectors", "label": "Graph vs embeddings"}]}, {"id": "05-graphs/graph-vs-vectors", "path": "docs/05-graphs/graph-vs-vectors.md", "section": "05-graphs", "section_title": "Graphs", "title": "Graph vs embeddings", "html": "<p>The usual advice for asking questions of your own documents is to embed them and\nretrieve by similarity. This guide does not, and the reason is worth\nunderstanding rather than taking on faith.</p>\n<h2 id=\"what-each-is-good-at\">What each is good at</h2>\n<p><strong>Embeddings</strong> find text that means something similar to your query, including\nwhen the wording is completely different. They are good at recall, they need no\nstructure, and they work on a pile of documents you have never organised.</p>\n<p><strong>A graph</strong> finds things that are explicitly connected, in a direction you can\nfollow, with a reason attached if the links are typed. It is good at\nmulti-hop questions and at telling you why two things are related.</p>\n<h2 id=\"where-similarity-fails\">Where similarity fails</h2>\n<p>The failure is specific: similarity retrieves chunks that resemble the question,\nand the answer to a good question often does not resemble it.</p>\n<p>Ask what connects two ideas, and the passages that establish the connection may\nshare no vocabulary with either. Ask what you have changed your mind about, and\nno chunk is similar to that, because the answer lives in the relationship\nbetween two pages written a year apart.</p>\n<p>There is also the ranking problem. Twenty chunks that all half-answer the\nquestion crowd out the one page that answers it fully, because similarity has no\nnotion of completeness.</p>\n<h2 id=\"where-the-graph-fails\">Where the graph fails</h2>\n<p>Recall. If a page was never linked, the graph cannot reach it, and the linking\nrules are exactly the thing that degrades quietly when ingestion gets sloppy.</p>\n<p>The graph also cannot find the thing you half-remember but cannot name. That is\na search problem, and full-text search on a vault of a few thousand pages is\ninstant, which is why <code>ripgrep</code> covers most of this in practice.</p>\n<h2 id=\"why-a-personal-vault-leans-graph\">Why a personal vault leans graph</h2>\n<p>Three reasons specific to this scale.</p>\n<p>Your corpus is small. A few thousand pages is not a retrieval problem, it is a\nfolder. The infrastructure that embeddings require pays off at millions of\ndocuments and costs more than it returns below that.</p>\n<p>Your corpus is already chunked. Atomic pages are semantic units written by\nsomething that understood them. Splitting them again into fixed-size chunks\ndestroys the structure you paid to create.</p>\n<p>Your questions are relational. What do I know about X, what connects X and Y,\nwhat argues against Z. Those are graph queries.</p>\n<h2 id=\"hybrid-when-you-get-there\">Hybrid, when you get there</h2>\n<p>The combination that makes sense: full-text search or embeddings to find\nentry points, the graph to expand from them.</p>\n<p>That way recall comes from search and structure comes from the graph, each doing\nwhat it is good at. See <a href=\"../07-retrieval/rag-on-top.md\">adding RAG when you need\nit</a> for the threshold where it starts to be worth\nthe maintenance.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"graphrag.md\">GraphRAG and where it fits</a></p>", "headings": ["What each is good at", "Where similarity fails", "Where the graph fails", "Why a personal vault leans graph", "Hybrid, when you get there", "Next"], "words": 460, "text": "The usual advice for asking questions of your own documents is to embed them and retrieve by similarity. This guide does not, and the reason is worth understanding rather than taking on faith. What each is good at Embeddings find text that means something similar to your query, including when the wording is completely different. They are good at recall, they need no structure, and they work on a pile of documents you have never organised. A graph finds things that are explicitly connected, in a direction you can follow, with a reason attached if the links are typed. It is good at multi-hop questions and at telling you why two things are related. Where similarity fails The failure is specific: similarity retrieves chunks that resemble the question, and the answer to a good question often does not resemble it. Ask what connects two ideas, and the passages that establish the connection may share no vocabulary with either. Ask what you have changed your mind about, and no chunk is similar to that, because the answer lives in the relationship between two pages written a year apart. There is also the ranking problem. Twenty chunks that all half-answer the question crowd out the one page that answers it fully, because similarity has no notion of completeness. Where the graph fails Recall. If a page was never linked, the graph cannot reach it, and the linking rules are exactly the thing that degrades quietly when ingestion gets sloppy. The graph also cannot find the thing you half-remember but cannot name. That is a search problem, and full-text search on a vault of a few thousand pages is instant, which is why ripgrep covers most of this in practice. Why a personal vault leans graph Three reasons specific to this scale. Your corpus is small. A few thousand pages is not a retrieval problem, it is a folder. The infrastructure that embeddings require pays off at millions of documents and costs more than it returns below that. Your corpus is already chunked. Atomic pages are semantic units written by something that understood them. Splitting them again into fixed-size chunks destroys the structure you paid to create. Your questions are relational. What do I know about X, what connects X and Y, what argues against Z. Those are graph queries. Hybrid, when you get there The combination that makes sense: full-text search or embeddings to find entry points, the graph to expand from them. That way recall comes from search and structure comes from the graph, each doing what it is good at. See adding RAG when you need it ../07-retrieval/rag-on-top.md for the threshold where it starts to be worth the maintenance. Next GraphRAG and where it fits graphrag.md", "links": [{"to": "07-retrieval/rag-on-top", "label": "adding RAG when you need\nit"}, {"to": "05-graphs/graphrag", "label": "GraphRAG and where it fits"}]}, {"id": "05-graphs/graphrag", "path": "docs/05-graphs/graphrag.md", "section": "05-graphs", "section_title": "Graphs", "title": "GraphRAG and where it fits", "html": "<p>GraphRAG is the approach of building a graph from a corpus first, then answering\nquestions against the graph rather than against raw chunks. Microsoft Research\npublished the best-known version, \"From Local to Global: A Graph RAG Approach to\nQuery-Focused Summarization\".</p>\n<p>The pipeline, in outline: extract entities and relationships from every\ndocument, build a graph, detect communities of densely connected entities,\nsummarise each community, and answer questions by drawing on the community\nsummaries rather than on retrieved passages.</p>\n<h2 id=\"why-it-exists\">Why it exists</h2>\n<p>It targets a specific failure of chunk retrieval: questions about the corpus as\na whole. \"What are the main themes here\" cannot be answered by retrieving the\nfive most similar chunks, because no chunk contains the answer. It has to be\nassembled from everything.</p>\n<p>That class of question is exactly what people want from a second brain and\nexactly what similarity search is worst at.</p>\n<h2 id=\"what-your-vault-already-has\">What your vault already has</h2>\n<p>Read the pipeline again against a well-maintained wiki and most of it is already\nbuilt.</p>\n<p>Entity extraction is what ingestion does when it writes entity pages.\nRelationships are the wikilinks, with types if you added them. The graph is the\nvault. What is missing is the community layer: the detection of clusters and the\nsummaries over them.</p>\n<p>And that missing piece has a manual equivalent you are already writing.\nSynthesis pages are community summaries, produced by a model that read the\nsources rather than by an algorithm clustering entities.</p>\n<h2 id=\"whether-to-run-it\">Whether to run it</h2>\n<p>Probably not, at personal scale, and the honest reason is size. The approach\nearns its cost on corpora too large to have been curated by hand. A few thousand\ncurated pages with real links do not need automated community detection to find\ntheir own themes; you can see the clusters in the graph view.</p>\n<p>There is a case for it as an audit rather than as a retrieval system. Running\ncommunity detection over your exported graph and comparing the algorithmic\nclusters against your synthesis pages tells you where the vault has themes you\nhave not noticed. That is a once-a-quarter exercise, not infrastructure.</p>\n<h2 id=\"related-research-worth-reading\">Related research worth reading</h2>\n<p><strong>HippoRAG</strong> applies personalised PageRank over a knowledge graph for multi-hop\nquestions, which is a more direct analogue of what an agent does walking links\noutward from a starting page.</p>\n<p>Read the papers themselves rather than summaries of them. Both are specific\nabout the conditions their results hold under, and those conditions are what\ndecide whether the approach transfers to your situation.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"exporting-your-graph.md\">Exporting the graph</a></p>", "headings": ["Why it exists", "What your vault already has", "Whether to run it", "Related research worth reading", "Next"], "words": 420, "text": "GraphRAG is the approach of building a graph from a corpus first, then answering questions against the graph rather than against raw chunks. Microsoft Research published the best-known version, \"From Local to Global: A Graph RAG Approach to Query-Focused Summarization\". The pipeline, in outline: extract entities and relationships from every document, build a graph, detect communities of densely connected entities, summarise each community, and answer questions by drawing on the community summaries rather than on retrieved passages. Why it exists It targets a specific failure of chunk retrieval: questions about the corpus as a whole. \"What are the main themes here\" cannot be answered by retrieving the five most similar chunks, because no chunk contains the answer. It has to be assembled from everything. That class of question is exactly what people want from a second brain and exactly what similarity search is worst at. What your vault already has Read the pipeline again against a well-maintained wiki and most of it is already built. Entity extraction is what ingestion does when it writes entity pages. Relationships are the wikilinks, with types if you added them. The graph is the vault. What is missing is the community layer: the detection of clusters and the summaries over them. And that missing piece has a manual equivalent you are already writing. Synthesis pages are community summaries, produced by a model that read the sources rather than by an algorithm clustering entities. Whether to run it Probably not, at personal scale, and the honest reason is size. The approach earns its cost on corpora too large to have been curated by hand. A few thousand curated pages with real links do not need automated community detection to find their own themes; you can see the clusters in the graph view. There is a case for it as an audit rather than as a retrieval system. Running community detection over your exported graph and comparing the algorithmic clusters against your synthesis pages tells you where the vault has themes you have not noticed. That is a once-a-quarter exercise, not infrastructure. Related research worth reading HippoRAG applies personalised PageRank over a knowledge graph for multi-hop questions, which is a more direct analogue of what an agent does walking links outward from a starting page. Read the papers themselves rather than summaries of them. Both are specific about the conditions their results hold under, and those conditions are what decide whether the approach transfers to your situation. Next Exporting the graph exporting-your-graph.md", "links": [{"to": "05-graphs/exporting-your-graph", "label": "Exporting the graph"}]}, {"id": "05-graphs/exporting-your-graph", "path": "docs/05-graphs/exporting-your-graph.md", "section": "05-graphs", "section_title": "Graphs", "title": "Exporting the graph", "html": "<p>Obsidian's graph view is a viewer. To compute anything, you need the graph\noutside it.</p>\n<h2 id=\"export\">Export</h2>\n<pre><code class=\"language-bash\">python3 scripts/graph_export.py ~/brain edges.csv\npython3 scripts/graph_export.py ~/brain graph.graphml --format graphml\n</code></pre>\n<p>The script parses every wikilink into an edge list, carries the page <code>type</code> as a\nnode attribute, and has no dependencies. CSV for code, GraphML for Gephi.</p>\n<h2 id=\"analysis\">Analysis</h2>\n<pre><code class=\"language-python\">import networkx as nx, csv\n\ng = nx.DiGraph()\nwith open("edges.csv") as f:\n next(f)\n g.add_edges_from(tuple(r) for r in csv.reader(f))\n\nprint(nx.number_weakly_connected_components(g))\nprint(sorted(nx.pagerank(g).items(), key=lambda kv: -kv[1])[:10])\nprint([n for n in g if g.in_degree(n) == 0])\n</code></pre>\n<p>Three questions in ten lines: how fragmented is the vault, which pages are\nstructurally central, and what is unreachable.</p>\n<p>PageRank on a knowledge graph is worth running once. The top pages are what your\nvault is actually about, which is reliably different from what you would say it\nis about.</p>\n<h2 id=\"betweenness-the-one-worth-the-compute\">Betweenness, the one worth the compute</h2>\n<pre><code class=\"language-python\">b = nx.betweenness_centrality(g)\n</code></pre>\n<p>Betweenness measures how often a page sits on the shortest path between two\nothers. High-betweenness pages are the bridges between clusters.</p>\n<p>They matter for two reasons. They are your most valuable pages, holding\nconnections no single source contained. And they are the fragile points: if a\nbridge page is wrong or gets deleted in a merge, two areas of the vault silently\nstop informing each other.</p>\n<h2 id=\"graph-databases\">Graph databases</h2>\n<p>Kuzu is embedded, no server, reads CSV directly, and Cypher queries over your\nown notes are genuinely fun for an evening. Neo4j is the full version and is\noverkill unless you are building something on top.</p>\n<p>Be clear about what this is: an analysis layer, not a replacement. The markdown\nstays canonical, the database is a rebuildable derivative. The moment you start\nwriting knowledge that exists only in the database, you have lost the\nportability that made the whole approach worth choosing.</p>\n<h2 id=\"gephi\">Gephi</h2>\n<p>For looking rather than computing. Load the GraphML, run ForceAtlas2, size nodes\nby degree, colour by type. It renders large graphs in a way Obsidian cannot, and\nit is what to use if you want a screenshot worth showing.</p>\n<h2 id=\"keep-it-in-sync\">Keep it in sync</h2>\n<p>The export is a snapshot and it is stale immediately. Regenerate it rather than\nmaintaining it, and never edit the exported graph expecting the vault to follow.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"metrics.md\">Graph metrics worth tracking</a></p>", "headings": ["Export", "Analysis", "Betweenness, the one worth the compute", "Graph databases", "Gephi", "Keep it in sync", "Next"], "words": 384, "text": "Obsidian's graph view is a viewer. To compute anything, you need the graph outside it. Export bash python3 scripts/graph_export.py ~/brain edges.csv python3 scripts/graph_export.py ~/brain graph.graphml --format graphml The script parses every wikilink into an edge list, carries the page type as a node attribute, and has no dependencies. CSV for code, GraphML for Gephi. Analysis python import networkx as nx, csv g = nx.DiGraph with open \"edges.csv\" as f: next f g.add_edges_from tuple r for r in csv.reader f print nx.number_weakly_connected_components g print sorted nx.pagerank g .items , key=lambda kv: -kv 1 :10 print n for n in g if g.in_degree n == 0 Three questions in ten lines: how fragmented is the vault, which pages are structurally central, and what is unreachable. PageRank on a knowledge graph is worth running once. The top pages are what your vault is actually about, which is reliably different from what you would say it is about. Betweenness, the one worth the compute python b = nx.betweenness_centrality g Betweenness measures how often a page sits on the shortest path between two others. High-betweenness pages are the bridges between clusters. They matter for two reasons. They are your most valuable pages, holding connections no single source contained. And they are the fragile points: if a bridge page is wrong or gets deleted in a merge, two areas of the vault silently stop informing each other. Graph databases Kuzu is embedded, no server, reads CSV directly, and Cypher queries over your own notes are genuinely fun for an evening. Neo4j is the full version and is overkill unless you are building something on top. Be clear about what this is: an analysis layer, not a replacement. The markdown stays canonical, the database is a rebuildable derivative. The moment you start writing knowledge that exists only in the database, you have lost the portability that made the whole approach worth choosing. Gephi For looking rather than computing. Load the GraphML, run ForceAtlas2, size nodes by degree, colour by type. It renders large graphs in a way Obsidian cannot, and it is what to use if you want a screenshot worth showing. Keep it in sync The export is a snapshot and it is stale immediately. Regenerate it rather than maintaining it, and never edit the exported graph expecting the vault to follow. Next Graph metrics worth tracking metrics.md", "links": [{"to": "05-graphs/metrics", "label": "Graph metrics worth tracking"}]}, {"id": "05-graphs/metrics", "path": "docs/05-graphs/metrics.md", "section": "05-graphs", "section_title": "Graphs", "title": "Graph metrics worth tracking", "html": "<p>Four numbers, checked monthly. Their direction over time tells you whether the\nsystem is working, which is not obvious from using it day to day.</p>\n<pre><code class=\"language-bash\">python3 scripts/vault_stats.py ~/brain\n</code></pre>\n<h2 id=\"orphan-rate\">Orphan rate</h2>\n<p>Pages with no inbound links, as a share of all pages.</p>\n<p>The single most diagnostic number in the vault. A rising orphan rate means\ningestion is writing pages without connecting them, which is the exact failure\nmode that turns a wiki back into a folder.</p>\n<p>Under five percent is healthy. Over fifteen and something is broken in the\ningest instructions, not in your habits.</p>\n<h2 id=\"average-degree\">Average degree</h2>\n<p>Links per page.</p>\n<p>Below two, the graph is barely connected and retrieval cannot do better than\nsearch. Between three and eight is the working range for a personal vault. Much\nabove ten, check whether links are being added decoratively, which inflates the\nnumber while making the graph less useful.</p>\n<p>Watch it alongside page count. Degree that stays flat while the vault doubles is\nfine; degree that falls means new pages are attaching to less than the existing\nones did.</p>\n<h2 id=\"component-count\">Component count</h2>\n<p>How many disconnected islands.</p>\n<p>Ideally one large component holding most pages, plus a few genuinely separate\ntopics. If the main component holds less than about eighty percent of pages, the\nvault is fragmented and answers will be systematically incomplete without\nanything appearing wrong.</p>\n<h2 id=\"stale-page-rate\">Stale page rate</h2>\n<p>Concept pages whose <code>updated</code> date is older than ninety days, as a share of\nconcept pages.</p>\n<p>Some staleness is correct: a well-written page on a settled idea does not need\ntouching. But a vault where most concept pages have not been touched in months\nwhile sources keep arriving means new material is landing in new pages instead\nof updating existing ones. That is how you end up with four pages about one\nthing.</p>\n<pre><code class=\"language-dataview\">TABLE updated FROM "wiki/concepts"\nWHERE updated < date(today) - dur(90 days)\nSORT updated ASC\n</code></pre>\n<h2 id=\"what-not-to-track\">What not to track</h2>\n<p>Page count and word count. Both go up regardless of whether the vault is getting\nbetter, which makes them satisfying and useless. A vault that doubled its pages\nwhile doubling its orphan rate got worse.</p>\n<h2 id=\"recording-them\">Recording them</h2>\n<p>Append the four numbers to a note monthly. Trend is the information; a single\nreading tells you almost nothing, and you will not remember what last quarter's\norphan rate was.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"../06-agents/README.md\">Agents</a>, for running all of this without you.</p>", "headings": ["Orphan rate", "Average degree", "Component count", "Stale page rate", "What not to track", "Recording them", "Next"], "words": 401, "text": "Four numbers, checked monthly. Their direction over time tells you whether the system is working, which is not obvious from using it day to day. bash python3 scripts/vault_stats.py ~/brain Orphan rate Pages with no inbound links, as a share of all pages. The single most diagnostic number in the vault. A rising orphan rate means ingestion is writing pages without connecting them, which is the exact failure mode that turns a wiki back into a folder. Under five percent is healthy. Over fifteen and something is broken in the ingest instructions, not in your habits. Average degree Links per page. Below two, the graph is barely connected and retrieval cannot do better than search. Between three and eight is the working range for a personal vault. Much above ten, check whether links are being added decoratively, which inflates the number while making the graph less useful. Watch it alongside page count. Degree that stays flat while the vault doubles is fine; degree that falls means new pages are attaching to less than the existing ones did. Component count How many disconnected islands. Ideally one large component holding most pages, plus a few genuinely separate topics. If the main component holds less than about eighty percent of pages, the vault is fragmented and answers will be systematically incomplete without anything appearing wrong. Stale page rate Concept pages whose updated date is older than ninety days, as a share of concept pages. Some staleness is correct: a well-written page on a settled idea does not need touching. But a vault where most concept pages have not been touched in months while sources keep arriving means new material is landing in new pages instead of updating existing ones. That is how you end up with four pages about one thing. dataview TABLE updated FROM \"wiki/concepts\" WHERE updated < date today - dur 90 days SORT updated ASC What not to track Page count and word count. Both go up regardless of whether the vault is getting better, which makes them satisfying and useless. A vault that doubled its pages while doubling its orphan rate got worse. Recording them Append the four numbers to a note monthly. Trend is the information; a single reading tells you almost nothing, and you will not remember what last quarter's orphan rate was. Next Agents ../06-agents/README.md , for running all of this without you.", "links": []}, {"id": "06-agents/agent-roles", "path": "docs/06-agents/agent-roles.md", "section": "06-agents", "section_title": "Agents", "title": "Agent roles", "html": "<p>One agent doing everything produces mediocre work at every job. The instructions\nthat make a good ingestor are not the ones that make a good reviewer, and stuffed\ninto one prompt they dilute each other.</p>\n<p>Six roles cover a vault, four of them read-only. The definitions are in\n<a href=\"../../agents/README.md\"><code>agents/</code></a>.</p>\n<h2 id=\"ingestor\">Ingestor</h2>\n<p>Reads <code>raw/</code>, writes wiki pages, links them, updates the index and log. Writes\nmore than any other role and is the one whose output quality determines\neverything downstream.</p>\n<p>Its instructions are narrow on purpose: it does not answer questions, does not\nrestructure existing pages beyond adding links, and does not delete. An ingestor\nthat reorganises while ingesting produces runs you cannot review, because content\nchanges and structural changes arrive mixed in the same diff.</p>\n<h2 id=\"linker\">Linker</h2>\n<p>Finds connections between existing pages that ingestion missed.</p>\n<p>Runs after imports and weekly. Adds links, creates nothing, rewrites nothing.\nSeparating it from the ingestor matters because linking well requires reading\nbroadly across the vault, which is a different job from reading one source\nclosely.</p>\n<p>Its one rule: a link it adds must be one you would agree with on reading both\npages side by side. A linker optimising for link count degrades the graph while\nappearing productive.</p>\n<h2 id=\"reviewer\">Reviewer</h2>\n<p>Read-only. Produces the periodic review: what changed, where attention went,\nwhat contradicts what, what to read next.</p>\n<p>Read-only is not caution, it is what makes the review trustworthy. A reviewer\nthat can edit will fix small things as it goes, and then its report describes a\nvault that no longer exists.</p>\n<h2 id=\"researcher\">Researcher</h2>\n<p>Read-only. Answers questions from the vault, cites pages, names what is missing.</p>\n<p>Also the role you talk to most, and the one that most needs the rule about not\nfalling back on general knowledge. See the\n<a href=\"../../skills/README.md\">query skill</a>.</p>\n<h2 id=\"graph-analyst\">Graph analyst</h2>\n<p>Read-only. Runs the metrics, finds hubs, bridges and clusters, and says what the\nnumbers mean for retrieval. Monthly.</p>\n<p>Separate from the linter because analysis and repair want opposite dispositions:\none should notice everything, the other should touch as little as possible.</p>\n<h2 id=\"curator\">Curator</h2>\n<p>Read-only. Proposes what to prune, archive or merge, quarterly.</p>\n<p>Proposals only, never actions. Deletion is the one operation you cannot recover\nfrom by reading a diff, so it stays a decision the owner makes.</p>\n<h2 id=\"roles-not-worth-creating\">Roles not worth creating</h2>\n<p><strong>A deleter.</strong> Deletion should be a decision you make, executed with a record.\nThe curator proposes; you dispose.</p>\n<p><strong>A summariser.</strong> Summaries of pages that are already summaries produce a layer\nthat is less true than what is under it and gets read instead of it.</p>\n<p><strong>A tagger.</strong> Tagging is a five-second judgement made during ingest with full\ncontext. A separate pass has less context and produces worse tags.</p>\n<h2 id=\"handoffs\">Handoffs</h2>\n<p>Roles communicate through the vault, not through each other. The ingestor writes\ngaps into <code>index.md</code>; the linker reads them. The ingestor logs its run; the\nreviewer reads the log.</p>\n<p>That is deliberate. Files as the interface means any run is inspectable\nafterwards, and a role can be replaced without touching the others.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"scheduled-maintenance.md\">Scheduling</a></p>", "headings": ["Ingestor", "Linker", "Reviewer", "Researcher", "Graph analyst", "Curator", "Roles not worth creating", "Handoffs", "Next"], "words": 507, "text": "One agent doing everything produces mediocre work at every job. The instructions that make a good ingestor are not the ones that make a good reviewer, and stuffed into one prompt they dilute each other. Six roles cover a vault, four of them read-only. The definitions are in agents/ ../../agents/README.md . Ingestor Reads raw/ , writes wiki pages, links them, updates the index and log. Writes more than any other role and is the one whose output quality determines everything downstream. Its instructions are narrow on purpose: it does not answer questions, does not restructure existing pages beyond adding links, and does not delete. An ingestor that reorganises while ingesting produces runs you cannot review, because content changes and structural changes arrive mixed in the same diff. Linker Finds connections between existing pages that ingestion missed. Runs after imports and weekly. Adds links, creates nothing, rewrites nothing. Separating it from the ingestor matters because linking well requires reading broadly across the vault, which is a different job from reading one source closely. Its one rule: a link it adds must be one you would agree with on reading both pages side by side. A linker optimising for link count degrades the graph while appearing productive. Reviewer Read-only. Produces the periodic review: what changed, where attention went, what contradicts what, what to read next. Read-only is not caution, it is what makes the review trustworthy. A reviewer that can edit will fix small things as it goes, and then its report describes a vault that no longer exists. Researcher Read-only. Answers questions from the vault, cites pages, names what is missing. Also the role you talk to most, and the one that most needs the rule about not falling back on general knowledge. See the query skill ../../skills/README.md . Graph analyst Read-only. Runs the metrics, finds hubs, bridges and clusters, and says what the numbers mean for retrieval. Monthly. Separate from the linter because analysis and repair want opposite dispositions: one should notice everything, the other should touch as little as possible. Curator Read-only. Proposes what to prune, archive or merge, quarterly. Proposals only, never actions. Deletion is the one operation you cannot recover from by reading a diff, so it stays a decision the owner makes. Roles not worth creating A deleter. Deletion should be a decision you make, executed with a record. The curator proposes; you dispose. A summariser. Summaries of pages that are already summaries produce a layer that is less true than what is under it and gets read instead of it. A tagger. Tagging is a five-second judgement made during ingest with full context. A separate pass has less context and produces worse tags. Handoffs Roles communicate through the vault, not through each other. The ingestor writes gaps into index.md ; the linker reads them. The ingestor logs its run; the reviewer reads the log. That is deliberate. Files as the interface means any run is inspectable afterwards, and a role can be replaced without touching the others. Next Scheduling scheduled-maintenance.md", "links": [{"to": "06-agents/scheduled-maintenance", "label": "Scheduling"}]}, {"id": "06-agents/scheduled-maintenance", "path": "docs/06-agents/scheduled-maintenance.md", "section": "06-agents", "section_title": "Agents", "title": "Scheduling", "html": "<p>Scheduled runs are what make the vault feel alive. You wake up and it has filed\nwhat you clipped, noticed a contradiction, and left you three lines about what\nchanged.</p>\n<p>They are also unattended writes to your notes, so the order matters: get the\n<a href=\"safety-and-guardrails.md\">guardrails</a> right first, then schedule.</p>\n<h2 id=\"cadence-per-job\">Cadence per job</h2>\n<p><strong>Ingest, daily.</strong> Overnight, on whatever accumulated in <code>raw/</code> during the day.\nDaily is right because a batch gives the agent a chance to notice that three\nthings you saved are about the same idea. Hourly does not.</p>\n<p><strong>Link, weekly.</strong> Connections need material to connect. Run it after a week of\ningestion.</p>\n<p><strong>Lint, weekly.</strong> After the linker, so it catches what that pass broke.</p>\n<p><strong>Review, weekly.</strong> The one output you actually read. Put it on the morning you\nplan.</p>\n<p><strong>Metrics, monthly.</strong> Four numbers appended to a note. See\n<a href=\"../05-graphs/metrics.md\">metrics</a>.</p>\n<h2 id=\"setting-one-up\">Setting one up</h2>\n<p>In Claude Desktop, the Schedule tab, then a new task:</p>\n<pre><code>Frequency: Daily, 7:00am\nFolder: your vault\nPrompt: File anything new in raw/ into the wiki following CLAUDE.md.\n Link it to existing pages. Update index.md and log.md. Commit\n with a message naming the run. Then write me three lines on\n what changed.\n</code></pre>\n<p>Or ask for it in a session: \"set up a daily task at 7am that ingests raw/ and\nsummarises what changed\".</p>\n<p>From a terminal, <code>cron</code> or Task Scheduler calling Claude Code headless works the\nsame way, and is the better option if you want the run inside a git commit\nautomatically.</p>\n<h2 id=\"what-a-run-must-produce\">What a run must produce</h2>\n<p>Three things, every time.</p>\n<p><strong>A log entry.</strong> Otherwise you cannot audit what happened while you were asleep.</p>\n<p><strong>A commit.</strong> One per run, with the run named in the message. This is what makes\na bad run revertible in one command instead of an evening.</p>\n<p><strong>A report to you.</strong> Even one line. A scheduled task that produces nothing\nvisible is one you stop trusting and then stop reading.</p>\n<h2 id=\"detecting-silent-failure\">Detecting silent failure</h2>\n<p>The failure mode is not a crash. It is a run that completes and does nothing\nuseful: the source was empty, the API call failed halfway, the instructions\nmatched no files.</p>\n<p>Two cheap checks. Have the run report counts, not just completion, so \"ingested\n0 sources\" is visible. And look at commit frequency once a month: a week with no\ncommits from the daily task means it has been failing quietly since Tuesday.</p>\n<h2 id=\"start-manual\">Start manual</h2>\n<p>Run each job by hand for a week before scheduling it. You are checking that the\noutput is good enough to accept without reading it closely, because that is\nexactly what scheduling means.</p>\n<p>Schedule the ingest last. It is the one that writes most.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"subagents.md\">Subagents and parallel work</a></p>", "headings": ["Cadence per job", "Setting one up", "What a run must produce", "Detecting silent failure", "Start manual", "Next"], "words": 452, "text": "Scheduled runs are what make the vault feel alive. You wake up and it has filed what you clipped, noticed a contradiction, and left you three lines about what changed. They are also unattended writes to your notes, so the order matters: get the guardrails safety-and-guardrails.md right first, then schedule. Cadence per job Ingest, daily. Overnight, on whatever accumulated in raw/ during the day. Daily is right because a batch gives the agent a chance to notice that three things you saved are about the same idea. Hourly does not. Link, weekly. Connections need material to connect. Run it after a week of ingestion. Lint, weekly. After the linker, so it catches what that pass broke. Review, weekly. The one output you actually read. Put it on the morning you plan. Metrics, monthly. Four numbers appended to a note. See metrics ../05-graphs/metrics.md . Setting one up In Claude Desktop, the Schedule tab, then a new task: Frequency: Daily, 7:00am Folder: your vault Prompt: File anything new in raw/ into the wiki following CLAUDE.md. Link it to existing pages. Update index.md and log.md. Commit with a message naming the run. Then write me three lines on what changed. Or ask for it in a session: \"set up a daily task at 7am that ingests raw/ and summarises what changed\". From a terminal, cron or Task Scheduler calling Claude Code headless works the same way, and is the better option if you want the run inside a git commit automatically. What a run must produce Three things, every time. A log entry. Otherwise you cannot audit what happened while you were asleep. A commit. One per run, with the run named in the message. This is what makes a bad run revertible in one command instead of an evening. A report to you. Even one line. A scheduled task that produces nothing visible is one you stop trusting and then stop reading. Detecting silent failure The failure mode is not a crash. It is a run that completes and does nothing useful: the source was empty, the API call failed halfway, the instructions matched no files. Two cheap checks. Have the run report counts, not just completion, so \"ingested 0 sources\" is visible. And look at commit frequency once a month: a week with no commits from the daily task means it has been failing quietly since Tuesday. Start manual Run each job by hand for a week before scheduling it. You are checking that the output is good enough to accept without reading it closely, because that is exactly what scheduling means. Schedule the ingest last. It is the one that writes most. Next Subagents and parallel work subagents.md", "links": [{"to": "06-agents/safety-and-guardrails", "label": "guardrails"}, {"to": "05-graphs/metrics", "label": "metrics"}, {"to": "06-agents/subagents", "label": "Subagents and parallel work"}]}, {"id": "06-agents/subagents", "path": "docs/06-agents/subagents.md", "section": "06-agents", "section_title": "Agents", "title": "Subagents and parallel work", "html": "<p>Subagents run with their own context. That is the whole point: a subagent\nreading thirty pages to answer a question does not fill the main session's\ncontext with those thirty pages, only with the answer.</p>\n<h2 id=\"when-to-fan-out\">When to fan out</h2>\n<p><strong>Research across many pages.</strong> Send a subagent to read a cluster and come back\nwith a summary. The main session keeps its budget for the actual work.</p>\n<p><strong>Independent sources.</strong> Ingesting ten unrelated articles parallelises cleanly,\nbecause none of them touch the same wiki pages.</p>\n<p><strong>Verification.</strong> One agent writes, another checks the pages against the sources.\nSeparate context is what makes the check meaningful; the same agent rereading its\nown work mostly agrees with itself.</p>\n<h2 id=\"when-not-to\">When not to</h2>\n<p><strong>Related sources.</strong> Three articles about the same topic must be ingested\nsequentially. In parallel, each one creates the concept page independently and\nyou get three versions of it, or two of them are overwritten.</p>\n<p><strong>Anything touching the index.</strong> <code>index.md</code> and <code>log.md</code> are single files that\nevery run wants to append to. Parallel writes to them conflict or silently lose\nentries.</p>\n<p><strong>Small jobs.</strong> Spawning a subagent costs a full context setup. For two files it\nis slower than doing it directly.</p>\n<h2 id=\"merging-parallel-work\">Merging parallel work</h2>\n<p>The rule that avoids most conflicts: subagents write to disjoint paths, the\nparent merges.</p>\n<p>Have each subagent report what it would write rather than writing shared files\ndirectly. The parent applies the index and log updates in one pass, after all\nsubagents return. Page files themselves are safe to write in parallel as long as\ntwo subagents were never given overlapping material.</p>\n<p>Commit before any parallel run. When it goes wrong, it goes wrong across many\nfiles at once.</p>\n<h2 id=\"cost\">Cost</h2>\n<p>Parallelism does not reduce total token use, it reduces wall-clock time and\nprotects the main context. Four subagents cost roughly four times one.</p>\n<p>That trade is worth it for a large backfill and pointless for a daily ingest of\nfive clipped articles.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"hooks.md\">Hooks</a></p>", "headings": ["When to fan out", "When not to", "Merging parallel work", "Cost", "Next"], "words": 328, "text": "Subagents run with their own context. That is the whole point: a subagent reading thirty pages to answer a question does not fill the main session's context with those thirty pages, only with the answer. When to fan out Research across many pages. Send a subagent to read a cluster and come back with a summary. The main session keeps its budget for the actual work. Independent sources. Ingesting ten unrelated articles parallelises cleanly, because none of them touch the same wiki pages. Verification. One agent writes, another checks the pages against the sources. Separate context is what makes the check meaningful; the same agent rereading its own work mostly agrees with itself. When not to Related sources. Three articles about the same topic must be ingested sequentially. In parallel, each one creates the concept page independently and you get three versions of it, or two of them are overwritten. Anything touching the index. index.md and log.md are single files that every run wants to append to. Parallel writes to them conflict or silently lose entries. Small jobs. Spawning a subagent costs a full context setup. For two files it is slower than doing it directly. Merging parallel work The rule that avoids most conflicts: subagents write to disjoint paths, the parent merges. Have each subagent report what it would write rather than writing shared files directly. The parent applies the index and log updates in one pass, after all subagents return. Page files themselves are safe to write in parallel as long as two subagents were never given overlapping material. Commit before any parallel run. When it goes wrong, it goes wrong across many files at once. Cost Parallelism does not reduce total token use, it reduces wall-clock time and protects the main context. Four subagents cost roughly four times one. That trade is worth it for a large backfill and pointless for a daily ingest of five clipped articles. Next Hooks hooks.md", "links": [{"to": "06-agents/hooks", "label": "Hooks"}]}, {"id": "06-agents/hooks", "path": "docs/06-agents/hooks.md", "section": "06-agents", "section_title": "Agents", "title": "Hooks", "html": "<p>Hooks fire on events rather than on a schedule. They are the right tool for\nthings that must happen every time, which is exactly the set of things a prompt\ninstruction will eventually miss.</p>\n<h2 id=\"worth-hooking\">Worth hooking</h2>\n<p><strong>Validation before a write.</strong> Check frontmatter parses and required fields are\npresent. A malformed page caught at write time is a non-event; caught a month\nlater it is a page that has been invisible to every query since.</p>\n<p><strong>Lint after a run.</strong> Broken links appear at the moment they are created, which\nis the moment there is enough context to fix them properly.</p>\n<p><strong>Commit after a scheduled run.</strong> Removes the possibility of a run that changed\nforty files and left no commit.</p>\n<p><strong>Notify on deletion.</strong> Any delete, any time, surfaces. Deletions are rare enough\nthat a notification costs nothing and matters when it fires.</p>\n<h2 id=\"not-worth-hooking\">Not worth hooking</h2>\n<p>Anything slow. A hook that runs on every file write and takes two seconds turns a\nforty-page ingest into a ninety-second pause, and you will disable it.</p>\n<p>Anything that needs judgement. Hooks are mechanical checks. A hook trying to\ndecide whether a page is good enough will be wrong in both directions.</p>\n<h2 id=\"keep-them-fast-and-quiet\">Keep them fast and quiet</h2>\n<p>A hook should complete in well under a second and print nothing when it passes.\nHooks that log on success train you to ignore hook output, which is the same as\nhaving no hooks the day one fails.</p>\n<h2 id=\"failure-behaviour\">Failure behaviour</h2>\n<p>Decide explicitly whether a failing hook blocks the operation.</p>\n<p>Validation hooks should block: a page that fails schema validation should not be\nwritten. Notification hooks should not: a failed notification is not a reason to\nlose the work.</p>\n<p>The bad case is a blocking hook that fails for an unrelated reason and silently\nstops your scheduled ingest for a week. Whatever blocks must be simple enough\nthat it only fails for the reason it exists.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"skills-and-commands.md\">Skills and slash commands</a></p>", "headings": ["Worth hooking", "Not worth hooking", "Keep them fast and quiet", "Failure behaviour", "Next"], "words": 325, "text": "Hooks fire on events rather than on a schedule. They are the right tool for things that must happen every time, which is exactly the set of things a prompt instruction will eventually miss. Worth hooking Validation before a write. Check frontmatter parses and required fields are present. A malformed page caught at write time is a non-event; caught a month later it is a page that has been invisible to every query since. Lint after a run. Broken links appear at the moment they are created, which is the moment there is enough context to fix them properly. Commit after a scheduled run. Removes the possibility of a run that changed forty files and left no commit. Notify on deletion. Any delete, any time, surfaces. Deletions are rare enough that a notification costs nothing and matters when it fires. Not worth hooking Anything slow. A hook that runs on every file write and takes two seconds turns a forty-page ingest into a ninety-second pause, and you will disable it. Anything that needs judgement. Hooks are mechanical checks. A hook trying to decide whether a page is good enough will be wrong in both directions. Keep them fast and quiet A hook should complete in well under a second and print nothing when it passes. Hooks that log on success train you to ignore hook output, which is the same as having no hooks the day one fails. Failure behaviour Decide explicitly whether a failing hook blocks the operation. Validation hooks should block: a page that fails schema validation should not be written. Notification hooks should not: a failed notification is not a reason to lose the work. The bad case is a blocking hook that fails for an unrelated reason and silently stops your scheduled ingest for a week. Whatever blocks must be simple enough that it only fails for the reason it exists. Next Skills and slash commands skills-and-commands.md", "links": [{"to": "06-agents/skills-and-commands", "label": "Skills and slash commands"}]}, {"id": "06-agents/skills-and-commands", "path": "docs/06-agents/skills-and-commands.md", "section": "06-agents", "section_title": "Agents", "title": "Skills and slash commands", "html": "<p>Two mechanisms that look similar and do different jobs.</p>\n<p><strong>A skill</strong> teaches repeatable behaviour. It loads when relevant and shapes how\nthe agent does something, whether you invoked it explicitly or just described the\ntask.</p>\n<p><strong>A command</strong> is a shortcut for a task you run often. It points at a skill and\nsaves you typing the instructions.</p>\n<p>The behaviour belongs in the skill. That way ingestion works the same whether it\nwas triggered by <code>/ingest</code>, by a scheduled task, or by you saying \"add this to my\nvault\".</p>\n<h2 id=\"what-this-repo-ships\">What this repo ships</h2>\n<p>Eighteen skills in <a href=\"../../skills/README.md\"><code>skills/</code></a>, one per workflow in this\nguide. Seventy-two commands in <a href=\"../../commands/README.md\"><code>commands/</code></a>, each a\nfew lines pointing at a skill and setting its scope.</p>\n<p>The ratio is deliberate. Behaviour belongs in a small number of well-written\nskills; commands are cheap, so there is no reason to make you remember how to\nphrase a request you make every week.</p>\n<p>Install them inside the vault at <code>.claude/skills/</code> and <code>.claude/commands/</code> so\nthey are versioned alongside your notes and travel with the vault.</p>\n<h2 id=\"writing-your-own\">Writing your own</h2>\n<p>A skill worth writing has three properties: you do it repeatedly, you have\nopinions about how, and the opinions are not obvious enough for the model to\nguess.</p>\n<p>Structure that works:</p>\n<pre><code class=\"language-markdown\">---\nname: skill-name\ndescription: >-\n What it does. When to use it, written pushy, because agents under-trigger\n skills. Do NOT use for the tempting near-misses.\n---\n\n# Name\n\n[Why this skill exists: what failure it prevents. This paragraph is the rubric\nfor every case the rules below do not cover.]\n\n## Core rule\n## Workflow\n## Output format\n## Calibration\n## Example\n</code></pre>\n<p>The opening paragraph does more work than the rules. Rules cover the cases you\nthought of; the reason covers the rest.</p>\n<h2 id=\"explain-the-why\">Explain the why</h2>\n<p>\"Never overwrite a contradiction\" gets applied literally and fails on the edge\ncases. \"Never overwrite a contradiction, because the history of what you believed\nis the thing this vault has that a search engine does not\" generalises to\nsituations you never described.</p>\n<p>All-caps NEVER without a reason is usually a missing explanation.</p>\n<h2 id=\"versioning\">Versioning</h2>\n<p>Skills live in the vault, so git tracks them. When output quality changes, the\nskill diff is the first place to look.</p>\n<p>Test a skill on three or four real cases before letting a scheduled task use it.\nA flaw in a skill that runs nightly is a flaw in three hundred pages by the end\nof the year.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"safety-and-guardrails.md\">Guardrails</a></p>", "headings": ["What this repo ships", "Writing your own", "Core rule", "Workflow", "Output format", "Calibration", "Example", "Explain the why", "Versioning", "Next"], "words": 414, "text": "Two mechanisms that look similar and do different jobs. A skill teaches repeatable behaviour. It loads when relevant and shapes how the agent does something, whether you invoked it explicitly or just described the task. A command is a shortcut for a task you run often. It points at a skill and saves you typing the instructions. The behaviour belongs in the skill. That way ingestion works the same whether it was triggered by /ingest , by a scheduled task, or by you saying \"add this to my vault\". What this repo ships Eighteen skills in skills/ ../../skills/README.md , one per workflow in this guide. Seventy-two commands in commands/ ../../commands/README.md , each a few lines pointing at a skill and setting its scope. The ratio is deliberate. Behaviour belongs in a small number of well-written skills; commands are cheap, so there is no reason to make you remember how to phrase a request you make every week. Install them inside the vault at .claude/skills/ and .claude/commands/ so they are versioned alongside your notes and travel with the vault. Writing your own A skill worth writing has three properties: you do it repeatedly, you have opinions about how, and the opinions are not obvious enough for the model to guess. Structure that works: markdown --- name: skill-name description: - What it does. When to use it, written pushy, because agents under-trigger skills. Do NOT use for the tempting near-misses. --- Name Why this skill exists: what failure it prevents. This paragraph is the rubric for every case the rules below do not cover. Core rule Workflow Output format Calibration Example The opening paragraph does more work than the rules. Rules cover the cases you thought of; the reason covers the rest. Explain the why \"Never overwrite a contradiction\" gets applied literally and fails on the edge cases. \"Never overwrite a contradiction, because the history of what you believed is the thing this vault has that a search engine does not\" generalises to situations you never described. All-caps NEVER without a reason is usually a missing explanation. Versioning Skills live in the vault, so git tracks them. When output quality changes, the skill diff is the first place to look. Test a skill on three or four real cases before letting a scheduled task use it. A flaw in a skill that runs nightly is a flaw in three hundred pages by the end of the year. Next Guardrails safety-and-guardrails.md", "links": [{"to": "06-agents/safety-and-guardrails", "label": "Guardrails"}]}, {"id": "06-agents/safety-and-guardrails", "path": "docs/06-agents/safety-and-guardrails.md", "section": "06-agents", "section_title": "Agents", "title": "Guardrails", "html": "<p>The rule this whole section rests on:</p>\n<p><strong>Keys, not prompts.</strong></p>\n<p>Telling an agent not to do something is a preference. It is not a boundary. If\nthe agent technically can delete a file, empty a folder or send an email, then\none day, in a context you did not anticipate, it will.</p>\n<p>Control what is possible at the permission level. Then the instruction in\n<code>CLAUDE.md</code> is a preference sitting on top of a boundary, rather than the only\nthing between your notes and a bad run.</p>\n<h2 id=\"scope-write-access\">Scope write access</h2>\n<p>The agent needs write access to the vault. It does not need write access to your\nhome directory, and a scheduled task running with broad filesystem permissions is\na large blast radius for a small convenience.</p>\n<p>Same principle for connectors: read-only wherever the option exists. A calendar\nconnector that can only read cannot cancel a meeting, no matter what a\nmisinterpreted instruction says.</p>\n<h2 id=\"never-delete-without-a-record\">Never delete without a record</h2>\n<p>Deletion is the one operation you cannot recover from by reading a diff, because\nthe content is gone and only the absence remains.</p>\n<p>Rule: no page is deleted without a line in <code>log.md</code> naming it and why. Merges\ncount as deletions. Applied consistently, a page that vanishes is always\ntraceable, and \"where did that page go\" stops being an unanswerable question.</p>\n<h2 id=\"git-is-the-real-safety-net\">Git is the real safety net</h2>\n<p>Every guardrail above is preventive. Git is what saves you when one fails.</p>\n<p>Commit before any run that writes at scale. Scheduled runs commit their own work.\nThen a bad ingest is <code>git checkout .</code>, and a bad merge is one revert.</p>\n<p>Read the diffs from scheduled runs occasionally, especially in the first weeks.\nThat is how you learn what your agent actually does at 7am, which is reliably\ndifferent from what you assumed.</p>\n<h2 id=\"dry-runs\">Dry runs</h2>\n<p>For anything that touches many files, run it once in report-only mode.</p>\n<pre><code>Do a dry run: list every page you would create, update or delete, and the links\nyou would add. Write nothing.\n</code></pre>\n<p>The output takes a minute to read and catches misread instructions before they\nbecome four hundred edits.</p>\n<h2 id=\"watch-for-scope-creep\">Watch for scope creep</h2>\n<p>Agents extend the job. Asked to ingest, an agent may also tidy an unrelated page,\nfix formatting, rename something for consistency. Each is defensible; together\nthey mean you cannot tell what a run did without reading everything.</p>\n<p>Instruct explicitly: do the job asked, list anything else you noticed, change\nnothing else.</p>\n<h2 id=\"what-not-to-put-in-the-vault\">What not to put in the vault</h2>\n<p>Credentials, API keys, anything you are under obligation to keep confidential,\nother people's private information.</p>\n<p>Not because the agent will leak it, but because the vault is a single file tree\nthat gets synced, committed, backed up and occasionally shared. Every copy is\nanother place that content exists. See\n<a href=\"../09-maintenance/privacy-and-secrets.md\">privacy</a>.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"../07-retrieval/README.md\">Retrieval</a>, for getting answers out of what all this\nbuilt.</p>", "headings": ["Scope write access", "Never delete without a record", "Git is the real safety net", "Dry runs", "Watch for scope creep", "What not to put in the vault", "Next"], "words": 482, "text": "The rule this whole section rests on: Keys, not prompts. Telling an agent not to do something is a preference. It is not a boundary. If the agent technically can delete a file, empty a folder or send an email, then one day, in a context you did not anticipate, it will. Control what is possible at the permission level. Then the instruction in CLAUDE.md is a preference sitting on top of a boundary, rather than the only thing between your notes and a bad run. Scope write access The agent needs write access to the vault. It does not need write access to your home directory, and a scheduled task running with broad filesystem permissions is a large blast radius for a small convenience. Same principle for connectors: read-only wherever the option exists. A calendar connector that can only read cannot cancel a meeting, no matter what a misinterpreted instruction says. Never delete without a record Deletion is the one operation you cannot recover from by reading a diff, because the content is gone and only the absence remains. Rule: no page is deleted without a line in log.md naming it and why. Merges count as deletions. Applied consistently, a page that vanishes is always traceable, and \"where did that page go\" stops being an unanswerable question. Git is the real safety net Every guardrail above is preventive. Git is what saves you when one fails. Commit before any run that writes at scale. Scheduled runs commit their own work. Then a bad ingest is git checkout . , and a bad merge is one revert. Read the diffs from scheduled runs occasionally, especially in the first weeks. That is how you learn what your agent actually does at 7am, which is reliably different from what you assumed. Dry runs For anything that touches many files, run it once in report-only mode. Do a dry run: list every page you would create, update or delete, and the links you would add. Write nothing. The output takes a minute to read and catches misread instructions before they become four hundred edits. Watch for scope creep Agents extend the job. Asked to ingest, an agent may also tidy an unrelated page, fix formatting, rename something for consistency. Each is defensible; together they mean you cannot tell what a run did without reading everything. Instruct explicitly: do the job asked, list anything else you noticed, change nothing else. What not to put in the vault Credentials, API keys, anything you are under obligation to keep confidential, other people's private information. Not because the agent will leak it, but because the vault is a single file tree that gets synced, committed, backed up and occasionally shared. Every copy is another place that content exists. See privacy ../09-maintenance/privacy-and-secrets.md . Next Retrieval ../07-retrieval/README.md , for getting answers out of what all this built.", "links": [{"to": "09-maintenance/privacy-and-secrets", "label": "privacy"}]}, {"id": "07-retrieval/asking-questions", "path": "docs/07-retrieval/asking-questions.md", "section": "07-retrieval", "section_title": "Retrieval", "title": "Asking the vault", "html": "<p>You built the vault so answers would come from what you actually read. An agent\nthat quietly falls back on its own knowledge destroys that, and it does so\ninvisibly: the answer is fluent, plausible, and unverifiable.</p>\n<h2 id=\"the-rule\">The rule</h2>\n<p>Every claim in an answer comes from a page, and names the page.</p>\n<pre><code>Answer from my vault only. Cite the page for each claim. If the vault does not\ncover part of the question, say which part rather than filling it in.\n</code></pre>\n<p>That instruction belongs in <code>CLAUDE.md</code>, not typed each time. A rule you have to\nremember is a rule that lapses on the day it matters.</p>\n<h2 id=\"start-from-the-index\">Start from the index</h2>\n<p>The agent should read <code>index.md</code> first, then open the pages that look relevant,\nthen follow links outward from those.</p>\n<p>The alternative, a full-text sweep, is slower, spends context on near-misses, and\nmisses pages whose wording differs from your question. The index exists to make\nthis cheap; see <a href=\"../04-structuring/index-and-log.md\">index.md and log.md</a>.</p>\n<h2 id=\"outside-knowledge-labelled\">Outside knowledge, labelled</h2>\n<p>Sometimes the model knows something useful that the vault does not contain. That\nis fine as long as it is marked:</p>\n<pre><code>Cite vault pages for anything from my notes. Anything you know that my vault\ndoes not contain, put under a separate heading marked outside the vault.\n</code></pre>\n<p>Separated, it is useful context. Blended, it makes the whole answer unreliable,\nbecause you no longer know which parts you can trace.</p>\n<h2 id=\"empty-is-a-valid-answer\">Empty is a valid answer</h2>\n<p>If the vault has nothing on a topic, the right response is one sentence saying\nso.</p>\n<p>An agent padding an empty result with general knowledge is the failure mode to\nwatch for, because it feels like a good answer. Notice when an answer contains no\npage references at all; that is the signal.</p>\n<h2 id=\"answers-should-end-with-what-is-missing\">Answers should end with what is missing</h2>\n<pre><code>Read: [[page]], [[page]], [[page]]\nNot covered: whether this holds for the streaming case\n</code></pre>\n<p>Two lines, and they do more than they look. They tell you how much of the vault\nthe answer rests on, and the gap line is often the more useful half, because it\nis a precise statement of what to go read next.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"query-patterns.md\">Query patterns</a></p>", "headings": ["The rule", "Start from the index", "Outside knowledge, labelled", "Empty is a valid answer", "Answers should end with what is missing", "Next"], "words": 368, "text": "You built the vault so answers would come from what you actually read. An agent that quietly falls back on its own knowledge destroys that, and it does so invisibly: the answer is fluent, plausible, and unverifiable. The rule Every claim in an answer comes from a page, and names the page. Answer from my vault only. Cite the page for each claim. If the vault does not cover part of the question, say which part rather than filling it in. That instruction belongs in CLAUDE.md , not typed each time. A rule you have to remember is a rule that lapses on the day it matters. Start from the index The agent should read index.md first, then open the pages that look relevant, then follow links outward from those. The alternative, a full-text sweep, is slower, spends context on near-misses, and misses pages whose wording differs from your question. The index exists to make this cheap; see index.md and log.md ../04-structuring/index-and-log.md . Outside knowledge, labelled Sometimes the model knows something useful that the vault does not contain. That is fine as long as it is marked: Cite vault pages for anything from my notes. Anything you know that my vault does not contain, put under a separate heading marked outside the vault. Separated, it is useful context. Blended, it makes the whole answer unreliable, because you no longer know which parts you can trace. Empty is a valid answer If the vault has nothing on a topic, the right response is one sentence saying so. An agent padding an empty result with general knowledge is the failure mode to watch for, because it feels like a good answer. Notice when an answer contains no page references at all; that is the signal. Answers should end with what is missing Read: page , page , page Not covered: whether this holds for the streaming case Two lines, and they do more than they look. They tell you how much of the vault the answer rests on, and the gap line is often the more useful half, because it is a precise statement of what to go read next. Next Query patterns query-patterns.md", "links": [{"to": "04-structuring/index-and-log", "label": "index.md and log.md"}, {"to": "07-retrieval/query-patterns", "label": "Query patterns"}]}, {"id": "07-retrieval/query-patterns", "path": "docs/07-retrieval/query-patterns.md", "section": "07-retrieval", "section_title": "Retrieval", "title": "Query patterns", "html": "<p>Some questions a vault answers far better than a search engine or a general\nmodel. These are the ones worth building the habit around.</p>\n<h2 id=\"what-do-i-know-about-x\">What do I know about X</h2>\n<p>The basic one, and the reason most people build a vault.</p>\n<pre><code>What do I know about agent harnesses? Read the concept pages and the sources\nbehind them. Say where my sources disagree.\n</code></pre>\n<p>The second sentence is what makes it better than reading a page yourself. A\nconsolidated view across everything you read, with the disagreements surfaced,\nis not something any single page contains.</p>\n<h2 id=\"what-connects-x-and-y\">What connects X and Y</h2>\n<p>The question a search index cannot answer at all.</p>\n<pre><code>What connects retrieval quality and context length in my vault? Show the path\nthrough pages, not just the endpoints.\n</code></pre>\n<p>Asking for the path matters. The intermediate pages are the reasoning, and they\nare checkable in a way a bare conclusion is not.</p>\n<h2 id=\"what-have-i-changed-my-mind-about\">What have I changed my mind about</h2>\n<p>Only possible because of the <a href=\"../04-structuring/contradictions-and-supersession.md\">supersession\nrules</a>.</p>\n<pre><code>Find pages where a later source superseded an earlier claim. What did I believe,\nwhat changed it, and when?\n</code></pre>\n<p>Run this quarterly. It is the closest thing to watching your own thinking from\noutside, and it usually surfaces at least one belief you updated without\nnoticing.</p>\n<h2 id=\"what-is-missing\">What is missing</h2>\n<pre><code>Look at my concept pages on prediction markets. What questions do they raise\nthat no source in my vault answers?\n</code></pre>\n<p>This turns the vault into a reading list generated from your own gaps rather\nthan from what an algorithm thinks you would click.</p>\n<h2 id=\"what-did-i-say-about-this-before\">What did I say about this before</h2>\n<p>Especially useful with <a href=\"../03-ingestion/chat-exports.md\">chat exports</a> ingested.</p>\n<pre><code>Have I worked on this problem before? What did I conclude and what did I get\nwrong?\n</code></pre>\n<h2 id=\"what-contradicts-this\">What contradicts this</h2>\n<pre><code>I am about to argue that X. What in my vault argues against it?\n</code></pre>\n<p>The most valuable query in the set and the least used, because nobody\nvolunteers to be contradicted. A vault that only confirms you is a vault you\nbuilt badly.</p>\n<h2 id=\"questions-to-ask-elsewhere\">Questions to ask elsewhere</h2>\n<p>Anything about the present state of the world. Your vault knows what your\nsources said on the day you saved them, and nothing since.</p>\n<p>Anything general the model already knows. Asking your vault to explain a\nwell-documented concept from scratch gets you a worse version of what a plain\nanswer would give.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"search-tools.md\">Search tools</a></p>", "headings": ["What do I know about X", "What connects X and Y", "What have I changed my mind about", "What is missing", "What did I say about this before", "What contradicts this", "Questions to ask elsewhere", "Next"], "words": 410, "text": "Some questions a vault answers far better than a search engine or a general model. These are the ones worth building the habit around. What do I know about X The basic one, and the reason most people build a vault. What do I know about agent harnesses? Read the concept pages and the sources behind them. Say where my sources disagree. The second sentence is what makes it better than reading a page yourself. A consolidated view across everything you read, with the disagreements surfaced, is not something any single page contains. What connects X and Y The question a search index cannot answer at all. What connects retrieval quality and context length in my vault? Show the path through pages, not just the endpoints. Asking for the path matters. The intermediate pages are the reasoning, and they are checkable in a way a bare conclusion is not. What have I changed my mind about Only possible because of the supersession rules ../04-structuring/contradictions-and-supersession.md . Find pages where a later source superseded an earlier claim. What did I believe, what changed it, and when? Run this quarterly. It is the closest thing to watching your own thinking from outside, and it usually surfaces at least one belief you updated without noticing. What is missing Look at my concept pages on prediction markets. What questions do they raise that no source in my vault answers? This turns the vault into a reading list generated from your own gaps rather than from what an algorithm thinks you would click. What did I say about this before Especially useful with chat exports ../03-ingestion/chat-exports.md ingested. Have I worked on this problem before? What did I conclude and what did I get wrong? What contradicts this I am about to argue that X. What in my vault argues against it? The most valuable query in the set and the least used, because nobody volunteers to be contradicted. A vault that only confirms you is a vault you built badly. Questions to ask elsewhere Anything about the present state of the world. Your vault knows what your sources said on the day you saved them, and nothing since. Anything general the model already knows. Asking your vault to explain a well-documented concept from scratch gets you a worse version of what a plain answer would give. Next Search tools search-tools.md", "links": [{"to": "04-structuring/contradictions-and-supersession", "label": "supersession\nrules"}, {"to": "03-ingestion/chat-exports", "label": "chat exports"}, {"to": "07-retrieval/search-tools", "label": "Search tools"}]}, {"id": "07-retrieval/search-tools", "path": "docs/07-retrieval/search-tools.md", "section": "07-retrieval", "section_title": "Retrieval", "title": "Search tools", "html": "<p>Retrieval in a plain-text vault is mostly grep. That sounds primitive and is\nalmost always enough.</p>\n<h2 id=\"ripgrep\">ripgrep</h2>\n<pre><code class=\"language-bash\">rg -i "graph rag" ~/brain --type md -l\nrg -i "supersed" ~/brain -C 2\n</code></pre>\n<p>Instant on tens of thousands of files. The agent uses it by default when working\non the filesystem, and for \"where did I mention this\" it beats every fancier\noption on both speed and predictability.</p>\n<p>Its limit is exact wording. It cannot find the page about a concept you\ndescribed differently, which is what the graph and the index are for.</p>\n<h2 id=\"obsidian-search\">Obsidian search</h2>\n<p>Fine for interactive use. Operators worth knowing: <code>path:</code>, <code>file:</code>, <code>tag:</code> and\n<code>line:</code> for terms co-occurring on the same line, which cuts most false positives.</p>\n<h2 id=\"dataview\">Dataview</h2>\n<p>Queries over frontmatter, which is where structural questions get answered:</p>\n<pre><code>```dataview\nTABLE updated, tags FROM "wiki/concepts"\nWHERE contains(tags, "unverified")\nSORT updated ASC\n```\n</code></pre>\n<p>Anything phrased as \"which pages have property P\" is a Dataview query, and\nanswering those by asking the agent to read files is slower and less reliable.</p>\n<h2 id=\"combining-them\">Combining them</h2>\n<p>The pattern that works: Dataview or ripgrep to get a candidate set, the graph to\nexpand from it, the agent to read and synthesise.</p>\n<pre><code>Find every page tagged unverified, follow their links, and tell me which claims\ndepend on unverified sources.\n</code></pre>\n<p>Mechanical filtering first, judgement second. Asking the agent to do the\nfiltering by reading everything wastes context on pages a query would have\nexcluded in milliseconds.</p>\n<h2 id=\"when-search-gets-slow\">When search gets slow</h2>\n<p>It will not, at personal scale. Ripgrep over ten thousand markdown files is\nstill instant, and if search feels slow the cause is usually the agent reading\ntoo many files, not the search itself.</p>\n<p>That is a context problem, not a search problem. See <a href=\"context-budget.md\">context\nbudget</a>.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"rag-on-top.md\">Adding RAG when you need it</a></p>", "headings": ["ripgrep", "Obsidian search", "Dataview", "Combining them", "When search gets slow", "Next"], "words": 307, "text": "Retrieval in a plain-text vault is mostly grep. That sounds primitive and is almost always enough. ripgrep bash rg -i \"graph rag\" ~/brain --type md -l rg -i \"supersed\" ~/brain -C 2 Instant on tens of thousands of files. The agent uses it by default when working on the filesystem, and for \"where did I mention this\" it beats every fancier option on both speed and predictability. Its limit is exact wording. It cannot find the page about a concept you described differently, which is what the graph and the index are for. Obsidian search Fine for interactive use. Operators worth knowing: path: , file: , tag: and line: for terms co-occurring on the same line, which cuts most false positives. Dataview Queries over frontmatter, which is where structural questions get answered: dataview TABLE updated, tags FROM \"wiki/concepts\" WHERE contains tags, \"unverified\" SORT updated ASC Anything phrased as \"which pages have property P\" is a Dataview query, and answering those by asking the agent to read files is slower and less reliable. Combining them The pattern that works: Dataview or ripgrep to get a candidate set, the graph to expand from it, the agent to read and synthesise. Find every page tagged unverified, follow their links, and tell me which claims depend on unverified sources. Mechanical filtering first, judgement second. Asking the agent to do the filtering by reading everything wastes context on pages a query would have excluded in milliseconds. When search gets slow It will not, at personal scale. Ripgrep over ten thousand markdown files is still instant, and if search feels slow the cause is usually the agent reading too many files, not the search itself. That is a context problem, not a search problem. See context budget context-budget.md . Next Adding RAG when you need it rag-on-top.md", "links": [{"to": "07-retrieval/context-budget", "label": "context\nbudget"}, {"to": "07-retrieval/rag-on-top", "label": "Adding RAG when you need it"}]}, {"id": "07-retrieval/rag-on-top", "path": "docs/07-retrieval/rag-on-top.md", "section": "07-retrieval", "section_title": "Retrieval", "title": "Adding RAG when you need it", "html": "<p>This guide argues against a vector database for a personal vault. That argument\nhas a threshold, and it is worth naming rather than treating as doctrine.</p>\n<h2 id=\"when-it-starts-to-pay\">When it starts to pay</h2>\n<p>Three conditions, roughly together:</p>\n<p><strong>Scale past a few thousand pages,</strong> where reading the index plus following\nlinks stops fitting the context budget.</p>\n<p><strong>Questions phrased in wording your pages do not use.</strong> If you regularly fail to\nfind things you know are there, that is a recall problem, which is what\nembeddings solve.</p>\n<p><strong>A corpus you did not curate.</strong> A vault that absorbed ten thousand documents\nwithout a human deciding what mattered has no reliable structure to navigate,\nso similarity is what is left.</p>\n<p>Most personal vaults never hit all three. Mine has not, and I would not add the\nmaintenance for two out of three.</p>\n<h2 id=\"what-to-embed\">What to embed</h2>\n<p>Not raw sources. Embed the wiki pages.</p>\n<p>They are already semantic units, written by something that understood them, one\nidea each. That is what chunking tries to approximate and rarely achieves.\nRe-chunking them into fixed-size windows destroys the structure you paid for.</p>\n<p>Embed the page title, aliases and body together. Titles carry a lot of signal\nin a curated vault, because you chose them.</p>\n<h2 id=\"hybrid-not-replacement\">Hybrid, not replacement</h2>\n<p>The useful arrangement keeps the graph in charge:</p>\n<ol>\n<li>Embeddings find entry-point pages, including ones whose wording differs.</li>\n<li>The graph expands from those entry points through links.</li>\n<li>The agent reads the expanded set and answers with citations.</li>\n</ol>\n<p>Embeddings supply recall, the graph supplies structure and the reason two pages\nare related. Using similarity for the whole pipeline throws away the links,\nwhich is the part of your vault that took work.</p>\n<h2 id=\"keeping-the-index-fresh\">Keeping the index fresh</h2>\n<p>This is the maintenance nobody accounts for. Every ingest changes pages, and a\nstale embedding index returns pages whose content has moved on.</p>\n<p>Re-embed changed pages as part of the ingest run, not on a separate schedule. An\nindex that lags by a week is quietly wrong in a way that produces plausible bad\nanswers.</p>\n<p>If that sounds like more upkeep than it is worth, that is the correct reading for\nmost vaults, and it is the honest reason this section is short.</p>\n<h2 id=\"simpler-things-to-try-first\">Simpler things to try first</h2>\n<p>Before adding infrastructure, check whether the problem is actually recall.</p>\n<p>Missing aliases are the most common cause of \"I cannot find it\". So is a bad\nindex. So is an ingest that stopped linking properly two months ago and left a\ngrowing pile of orphans, which no retrieval method can reach.</p>\n<p>Run <code>scripts/link_check.py</code> and read your index before concluding you need\nvectors.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"context-budget.md\">Context budget</a></p>", "headings": ["When it starts to pay", "What to embed", "Hybrid, not replacement", "Keeping the index fresh", "Simpler things to try first", "Next"], "words": 442, "text": "This guide argues against a vector database for a personal vault. That argument has a threshold, and it is worth naming rather than treating as doctrine. When it starts to pay Three conditions, roughly together: Scale past a few thousand pages, where reading the index plus following links stops fitting the context budget. Questions phrased in wording your pages do not use. If you regularly fail to find things you know are there, that is a recall problem, which is what embeddings solve. A corpus you did not curate. A vault that absorbed ten thousand documents without a human deciding what mattered has no reliable structure to navigate, so similarity is what is left. Most personal vaults never hit all three. Mine has not, and I would not add the maintenance for two out of three. What to embed Not raw sources. Embed the wiki pages. They are already semantic units, written by something that understood them, one idea each. That is what chunking tries to approximate and rarely achieves. Re-chunking them into fixed-size windows destroys the structure you paid for. Embed the page title, aliases and body together. Titles carry a lot of signal in a curated vault, because you chose them. Hybrid, not replacement The useful arrangement keeps the graph in charge: 1. Embeddings find entry-point pages, including ones whose wording differs. 2. The graph expands from those entry points through links. 3. The agent reads the expanded set and answers with citations. Embeddings supply recall, the graph supplies structure and the reason two pages are related. Using similarity for the whole pipeline throws away the links, which is the part of your vault that took work. Keeping the index fresh This is the maintenance nobody accounts for. Every ingest changes pages, and a stale embedding index returns pages whose content has moved on. Re-embed changed pages as part of the ingest run, not on a separate schedule. An index that lags by a week is quietly wrong in a way that produces plausible bad answers. If that sounds like more upkeep than it is worth, that is the correct reading for most vaults, and it is the honest reason this section is short. Simpler things to try first Before adding infrastructure, check whether the problem is actually recall. Missing aliases are the most common cause of \"I cannot find it\". So is a bad index. So is an ingest that stopped linking properly two months ago and left a growing pile of orphans, which no retrieval method can reach. Run scripts/link_check.py and read your index before concluding you need vectors. Next Context budget context-budget.md", "links": [{"to": "07-retrieval/context-budget", "label": "Context budget"}]}, {"id": "07-retrieval/context-budget", "path": "docs/07-retrieval/context-budget.md", "section": "07-retrieval", "section_title": "Retrieval", "title": "Context budget", "html": "<p>Every page the agent reads costs context, and quality degrades well before the\nwindow is full. Reading more is not reading better.</p>\n<h2 id=\"progressive-disclosure\">Progressive disclosure</h2>\n<p>The pattern that works:</p>\n<ol>\n<li><strong>Index first.</strong> What exists, one line each.</li>\n<li><strong>Open the pages that matter.</strong> Usually three to eight.</li>\n<li><strong>Follow links one hop at a time,</strong> stopping when new pages stop adding.</li>\n</ol>\n<p>Each step is cheap and informs the next. The alternative, loading everything\nplausibly related up front, spends most of the budget on pages that turn out\nirrelevant, and pushes the useful ones into the middle of a long context where\nattention is weakest.</p>\n<h2 id=\"why-not-paste-the-whole-vault\">Why not paste the whole vault</h2>\n<p>Long-context models can hold a lot, and it is tempting to skip retrieval\nentirely.</p>\n<p>Two reasons not to. Attention is uneven across a long context, and material in\nthe middle is used less reliably than material at the edges, which is the finding\nin \"Lost in the Middle\" and the reason position matters at all. And an answer\nbuilt from everything cannot be checked: you have no idea which pages it actually\nused.</p>\n<p>An answer citing five pages you can open beats a fluent answer built from four\nhundred you cannot.</p>\n<h2 id=\"summary-layers\">Summary layers</h2>\n<p>Past a few hundred pages, add one level of index between the master index and\nthe pages: a short page per topic area, listing what is in that area and what\neach page covers.</p>\n<p>The agent reads the master index, opens the one topic index that matters, then\nopens pages. Three cheap reads instead of one expensive one.</p>\n<p>Do not let summary layers accumulate. Two levels is enough; three means you are\nbuilding a hierarchy nobody maintains, and summaries of summaries drift from\nwhat is underneath them.</p>\n<h2 id=\"measuring-what-was-read\">Measuring what was read</h2>\n<pre><code>List the pages you read to answer that, in the order you opened them.\n</code></pre>\n<p>Worth running occasionally. It exposes two problems: an agent reading thirty\npages when six would do, and an agent answering from three when the vault has\ntwenty relevant ones. Both are fixable by adjusting the instructions, and neither\nis visible from the answer alone.</p>\n<h2 id=\"subagents-for-wide-reads\">Subagents for wide reads</h2>\n<p>When a question genuinely needs a lot of material, send a\n<a href=\"../06-agents/subagents.md\">subagent</a>. It reads in its own context and returns a\nsummary, so the main session pays for the answer rather than for the sources.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"../08-outputs/README.md\">Outputs</a>, where the vault starts producing rather than\nanswering.</p>", "headings": ["Progressive disclosure", "Why not paste the whole vault", "Summary layers", "Measuring what was read", "Subagents for wide reads", "Next"], "words": 408, "text": "Every page the agent reads costs context, and quality degrades well before the window is full. Reading more is not reading better. Progressive disclosure The pattern that works: 1. Index first. What exists, one line each. 2. Open the pages that matter. Usually three to eight. 3. Follow links one hop at a time, stopping when new pages stop adding. Each step is cheap and informs the next. The alternative, loading everything plausibly related up front, spends most of the budget on pages that turn out irrelevant, and pushes the useful ones into the middle of a long context where attention is weakest. Why not paste the whole vault Long-context models can hold a lot, and it is tempting to skip retrieval entirely. Two reasons not to. Attention is uneven across a long context, and material in the middle is used less reliably than material at the edges, which is the finding in \"Lost in the Middle\" and the reason position matters at all. And an answer built from everything cannot be checked: you have no idea which pages it actually used. An answer citing five pages you can open beats a fluent answer built from four hundred you cannot. Summary layers Past a few hundred pages, add one level of index between the master index and the pages: a short page per topic area, listing what is in that area and what each page covers. The agent reads the master index, opens the one topic index that matters, then opens pages. Three cheap reads instead of one expensive one. Do not let summary layers accumulate. Two levels is enough; three means you are building a hierarchy nobody maintains, and summaries of summaries drift from what is underneath them. Measuring what was read List the pages you read to answer that, in the order you opened them. Worth running occasionally. It exposes two problems: an agent reading thirty pages when six would do, and an agent answering from three when the vault has twenty relevant ones. Both are fixable by adjusting the instructions, and neither is visible from the answer alone. Subagents for wide reads When a question genuinely needs a lot of material, send a subagent ../06-agents/subagents.md . It reads in its own context and returns a summary, so the main session pays for the answer rather than for the sources. Next Outputs ../08-outputs/README.md , where the vault starts producing rather than answering.", "links": [{"to": "06-agents/subagents", "label": "subagent"}]}, {"id": "08-outputs/writing-from-the-vault", "path": "docs/08-outputs/writing-from-the-vault.md", "section": "08-outputs", "section_title": "Outputs", "title": "Writing from the vault", "html": "<p>Writing is where the vault stops being an input and starts being leverage. The\nresearch is already done, cited, and connected. What is left is the argument.</p>\n<h2 id=\"outline-from-concept-pages-not-from-a-prompt\">Outline from concept pages, not from a prompt</h2>\n<pre><code>I want to write about why context length does not replace retrieval. Which of my\nconcept pages are relevant, what do they collectively argue, and where do my\nsources disagree?\n</code></pre>\n<p>That gives you an outline grounded in things you read, with the weak points\nmarked. Asking a model to outline the topic from scratch gives you the consensus\nview of the internet, which is what everyone else is also writing.</p>\n<p>The disagreements are the most useful part. They are where you have something to\nsay that is not the consensus.</p>\n<h2 id=\"cite-your-own-sources\">Cite your own sources</h2>\n<p>Every claim in a draft traces back through a concept page to a source page to a\nURL. That chain is what makes fact-checking a five-minute job instead of an\nafternoon.</p>\n<p>It also protects you from the specific failure of writing with a model: fluent\nsentences containing invented specifics. If a number in the draft has no source\npage behind it, it did not come from your research.</p>\n<h2 id=\"keep-your-voice\">Keep your voice</h2>\n<p>Drafting from the vault produces the model's phrasing over your material. That is\nfine as a first pass and bad as a final one.</p>\n<p>The practical split: let the agent assemble structure and evidence, write the\nsentences yourself. Or draft with it and rewrite every paragraph. What does not\nwork is publishing the assembly, which reads exactly like what it is.</p>\n<h2 id=\"close-the-loop\">Close the loop</h2>\n<p>Ingest your own finished work back into the vault.</p>\n<p>Your published pieces are sources like any other: they contain your positions,\nstated clearly, at a date. Six months later the vault can tell you what you\nargued and whether you still believe it.</p>\n<p>This is the step almost everyone skips, and it is what makes the second piece in\na domain meaningfully faster than the first.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"research-reports.md\">Research reports</a></p>", "headings": ["Outline from concept pages, not from a prompt", "Cite your own sources", "Keep your voice", "Close the loop", "Next"], "words": 340, "text": "Writing is where the vault stops being an input and starts being leverage. The research is already done, cited, and connected. What is left is the argument. Outline from concept pages, not from a prompt I want to write about why context length does not replace retrieval. Which of my concept pages are relevant, what do they collectively argue, and where do my sources disagree? That gives you an outline grounded in things you read, with the weak points marked. Asking a model to outline the topic from scratch gives you the consensus view of the internet, which is what everyone else is also writing. The disagreements are the most useful part. They are where you have something to say that is not the consensus. Cite your own sources Every claim in a draft traces back through a concept page to a source page to a URL. That chain is what makes fact-checking a five-minute job instead of an afternoon. It also protects you from the specific failure of writing with a model: fluent sentences containing invented specifics. If a number in the draft has no source page behind it, it did not come from your research. Keep your voice Drafting from the vault produces the model's phrasing over your material. That is fine as a first pass and bad as a final one. The practical split: let the agent assemble structure and evidence, write the sentences yourself. Or draft with it and rewrite every paragraph. What does not work is publishing the assembly, which reads exactly like what it is. Close the loop Ingest your own finished work back into the vault. Your published pieces are sources like any other: they contain your positions, stated clearly, at a date. Six months later the vault can tell you what you argued and whether you still believe it. This is the step almost everyone skips, and it is what makes the second piece in a domain meaningfully faster than the first. Next Research reports research-reports.md", "links": [{"to": "08-outputs/research-reports", "label": "Research reports"}]}, {"id": "08-outputs/research-reports", "path": "docs/08-outputs/research-reports.md", "section": "08-outputs", "section_title": "Outputs", "title": "Research reports", "html": "<p>A research report is what you produce when a question needs more than the vault\ncurrently holds. The vault is the starting point, not the whole answer.</p>\n<h2 id=\"scope-against-what-exists-first\">Scope against what exists first</h2>\n<pre><code>I need to understand how companies are deploying agent harnesses in production.\nWhat does my vault already cover, what is thin, and what is missing entirely?\n</code></pre>\n<p>That answer is your research plan. Most of the work in a good report is knowing\nwhat you do not need to look up, and starting from the vault means you are not\nre-reading things you read last year.</p>\n<h2 id=\"fill-the-gaps-deliberately\">Fill the gaps deliberately</h2>\n<p>Go find sources for the gaps, ingest them properly through <code>raw/</code>, and let them\nbuild pages the same way everything else does.</p>\n<p>Resisting the shortcut matters. Pasting a fresh article straight into the report\ndraft gets the report written and leaves the vault no better, which means the\nnext report on an adjacent topic starts from the same place.</p>\n<h2 id=\"structure\">Structure</h2>\n<pre><code>Question\nWhat I found (with page citations)\nWhere sources disagree\nWhat I could not establish\nWhat would change the conclusion\n</code></pre>\n<p>The last two sections are what make a report worth rereading. A report that\npresents only findings looks stronger and is less useful, because the reader\ncannot tell where it is load-bearing and where it is thin.</p>\n<h2 id=\"store-it-as-a-source\">Store it as a source</h2>\n<p>Reports go in <code>output/</code>, then get ingested back as sources.</p>\n<p>A report is a dated snapshot of your understanding, and having it in the vault as\na source means later material can contradict it explicitly rather than quietly\nsuperseding it. See\n<a href=\"../04-structuring/contradictions-and-supersession.md\">supersession</a>.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"publishing-and-export.md\">Publishing and export</a></p>", "headings": ["Scope against what exists first", "Fill the gaps deliberately", "Structure", "Store it as a source", "Next"], "words": 278, "text": "A research report is what you produce when a question needs more than the vault currently holds. The vault is the starting point, not the whole answer. Scope against what exists first I need to understand how companies are deploying agent harnesses in production. What does my vault already cover, what is thin, and what is missing entirely? That answer is your research plan. Most of the work in a good report is knowing what you do not need to look up, and starting from the vault means you are not re-reading things you read last year. Fill the gaps deliberately Go find sources for the gaps, ingest them properly through raw/ , and let them build pages the same way everything else does. Resisting the shortcut matters. Pasting a fresh article straight into the report draft gets the report written and leaves the vault no better, which means the next report on an adjacent topic starts from the same place. Structure Question What I found with page citations Where sources disagree What I could not establish What would change the conclusion The last two sections are what make a report worth rereading. A report that presents only findings looks stronger and is less useful, because the reader cannot tell where it is load-bearing and where it is thin. Store it as a source Reports go in output/ , then get ingested back as sources. A report is a dated snapshot of your understanding, and having it in the vault as a source means later material can contradict it explicitly rather than quietly superseding it. See supersession ../04-structuring/contradictions-and-supersession.md . Next Publishing and export publishing-and-export.md", "links": [{"to": "04-structuring/contradictions-and-supersession", "label": "supersession"}, {"to": "08-outputs/publishing-and-export", "label": "Publishing and export"}]}, {"id": "08-outputs/publishing-and-export", "path": "docs/08-outputs/publishing-and-export.md", "section": "08-outputs", "section_title": "Outputs", "title": "Publishing and export", "html": "<p>Some of your vault is worth showing to other people. Most of it is not, and the\nmechanics of that split are worth setting up before you publish anything.</p>\n<h2 id=\"deciding-what-is-public\">Deciding what is public</h2>\n<p>The simplest reliable approach is an explicit opt-in: a <code>publish: true</code> field in\nfrontmatter, and nothing without it ever leaves.</p>\n<p>Opt-out is the alternative and it is a mistake. Under opt-out, one forgotten flag\npublishes something private, and the failure is silent and permanent because it\nis already indexed.</p>\n<h2 id=\"static-site-options\">Static site options</h2>\n<p>Obsidian Publish is the official route and the least work. Quartz and Obsidian\nDigital Garden are the common open-source ones, both build a static site from a\nvault and both understand wikilinks and backlinks, which matters because a\npublished wiki with broken links is worse than a blog.</p>\n<p>Whatever you use, check what happens to a link pointing at an unpublished page.\nIt should degrade to plain text rather than to a 404.</p>\n<h2 id=\"publishing-a-subset-safely\">Publishing a subset safely</h2>\n<p>The pattern that works: a build step copies only <code>publish: true</code> pages into a\nseparate folder, rewrites links to unpublished pages as plain text, and builds\nfrom that copy.</p>\n<p>Never point a publishing tool at your live vault directly. One misconfigured\ninclude pattern publishes everything, and there is no way to unpublish something\nthat was crawled.</p>\n<h2 id=\"what-publishing-does-to-your-writing\">What publishing does to your writing</h2>\n<p>A public wiki changes how you write pages, and not entirely for the better. You\nstart writing for an audience: hedging more, explaining more, keeping tentative\nthoughts out.</p>\n<p>Tentative thoughts are exactly what a personal vault is for. If you publish,\nconsider keeping the private vault primary and publishing a deliberately selected\nsubset, rather than making the whole thing public and unconsciously sanitising\nit.</p>\n<h2 id=\"other-exports\">Other exports</h2>\n<p>PDF and HTML for a single report, straight from markdown with pandoc. Fine for\nsharing one document.</p>\n<p>Do not export the vault as a whole to any format you cannot regenerate. The\nmarkdown is the artifact.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"teaching-yourself.md\">Learning from your own vault</a></p>", "headings": ["Deciding what is public", "Static site options", "Publishing a subset safely", "What publishing does to your writing", "Other exports", "Next"], "words": 338, "text": "Some of your vault is worth showing to other people. Most of it is not, and the mechanics of that split are worth setting up before you publish anything. Deciding what is public The simplest reliable approach is an explicit opt-in: a publish: true field in frontmatter, and nothing without it ever leaves. Opt-out is the alternative and it is a mistake. Under opt-out, one forgotten flag publishes something private, and the failure is silent and permanent because it is already indexed. Static site options Obsidian Publish is the official route and the least work. Quartz and Obsidian Digital Garden are the common open-source ones, both build a static site from a vault and both understand wikilinks and backlinks, which matters because a published wiki with broken links is worse than a blog. Whatever you use, check what happens to a link pointing at an unpublished page. It should degrade to plain text rather than to a 404. Publishing a subset safely The pattern that works: a build step copies only publish: true pages into a separate folder, rewrites links to unpublished pages as plain text, and builds from that copy. Never point a publishing tool at your live vault directly. One misconfigured include pattern publishes everything, and there is no way to unpublish something that was crawled. What publishing does to your writing A public wiki changes how you write pages, and not entirely for the better. You start writing for an audience: hedging more, explaining more, keeping tentative thoughts out. Tentative thoughts are exactly what a personal vault is for. If you publish, consider keeping the private vault primary and publishing a deliberately selected subset, rather than making the whole thing public and unconsciously sanitising it. Other exports PDF and HTML for a single report, straight from markdown with pandoc. Fine for sharing one document. Do not export the vault as a whole to any format you cannot regenerate. The markdown is the artifact. Next Learning from your own vault teaching-yourself.md", "links": [{"to": "08-outputs/teaching-yourself", "label": "Learning from your own vault"}]}, {"id": "08-outputs/teaching-yourself", "path": "docs/08-outputs/teaching-yourself.md", "section": "08-outputs", "section_title": "Outputs", "title": "Learning from your own vault", "html": "<p>Reading something is not learning it. A vault full of well-written pages you\nnever revisit is a library, and libraries do not make anyone knowledgeable.</p>\n<h2 id=\"questions-from-your-own-pages\">Questions from your own pages</h2>\n<pre><code>Generate ten questions from my concept pages on prediction markets. Mix recall\nand application. Do not include the answers.\n</code></pre>\n<p>Answer them without looking. The ones you cannot answer are things you saved and\nnever actually learned, which is most of what anyone saves.</p>\n<p>This is more useful than generic quizzing because the questions come from\nmaterial you chose, at the depth you recorded it.</p>\n<h2 id=\"spaced-repetition-without-the-card-writing\">Spaced repetition, without the card-writing</h2>\n<p>The reason spaced repetition has low adoption is that writing cards is tedious.\nThe vault removes that step: concept pages are the source material, and the agent\ncan generate cards from them.</p>\n<p>The <a href=\"https://github.com/st3v3nmw/obsidian-spaced-repetition\">Spaced Repetition</a>\nplugin reads cards written inside your notes, so they live alongside the concept\nrather than in a separate app that drifts out of sync.</p>\n<p>Keep it to a small number of pages that actually matter. Reviewing everything you\never saved is a job, not a habit.</p>\n<h2 id=\"find-what-you-saved-and-did-not-understand\">Find what you saved and did not understand</h2>\n<pre><code>Which of my concept pages are written in language copied from the source rather\nthan explained in my own words? Those are the ones I probably did not understand.\n</code></pre>\n<p>A page that reproduces the source's phrasing is a page nobody digested. That is a\nreal signal, and it is invisible until you ask.</p>\n<h2 id=\"explain-it-back\">Explain it back</h2>\n<p>The oldest test there is:</p>\n<pre><code>Ask me to explain [[GraphRAG]] as if to someone who has not read about it. Then\ncompare what I said to my page and tell me what I left out.\n</code></pre>\n<p>Gaps between what you can say and what your page contains are precise, and they\nare exactly the thing rereading never reveals.</p>\n<h2 id=\"measure-learning-not-collection\">Measure learning, not collection</h2>\n<p>Page count goes up whether or not you know more. What is worth tracking is\nwhether you can answer questions from your own material without opening it.</p>\n<p>Once a quarter is enough. The result reliably surprises people, in both\ndirections.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"../09-maintenance/README.md\">Maintenance</a>, for keeping all of it alive.</p>", "headings": ["Questions from your own pages", "Spaced repetition, without the card-writing", "Find what you saved and did not understand", "Explain it back", "Measure learning, not collection", "Next"], "words": 365, "text": "Reading something is not learning it. A vault full of well-written pages you never revisit is a library, and libraries do not make anyone knowledgeable. Questions from your own pages Generate ten questions from my concept pages on prediction markets. Mix recall and application. Do not include the answers. Answer them without looking. The ones you cannot answer are things you saved and never actually learned, which is most of what anyone saves. This is more useful than generic quizzing because the questions come from material you chose, at the depth you recorded it. Spaced repetition, without the card-writing The reason spaced repetition has low adoption is that writing cards is tedious. The vault removes that step: concept pages are the source material, and the agent can generate cards from them. The Spaced Repetition https://github.com/st3v3nmw/obsidian-spaced-repetition plugin reads cards written inside your notes, so they live alongside the concept rather than in a separate app that drifts out of sync. Keep it to a small number of pages that actually matter. Reviewing everything you ever saved is a job, not a habit. Find what you saved and did not understand Which of my concept pages are written in language copied from the source rather than explained in my own words? Those are the ones I probably did not understand. A page that reproduces the source's phrasing is a page nobody digested. That is a real signal, and it is invisible until you ask. Explain it back The oldest test there is: Ask me to explain GraphRAG as if to someone who has not read about it. Then compare what I said to my page and tell me what I left out. Gaps between what you can say and what your page contains are precise, and they are exactly the thing rereading never reveals. Measure learning, not collection Page count goes up whether or not you know more. What is worth tracking is whether you can answer questions from your own material without opening it. Once a quarter is enough. The result reliably surprises people, in both directions. Next Maintenance ../09-maintenance/README.md , for keeping all of it alive.", "links": []}, {"id": "09-maintenance/lint-and-health", "path": "docs/09-maintenance/lint-and-health.md", "section": "09-maintenance", "section_title": "Maintenance", "title": "Linting the vault", "html": "<p>Structural rot is silent. Nothing errors. The vault just slowly stops answering\nwell because a third of its pages are unreachable and nobody noticed.</p>\n<h2 id=\"what-a-lint-checks\">What a lint checks</h2>\n<p><strong>Broken links.</strong> Two distinct cases: a typo or rename, which gets fixed, and a\ngenuine gap, which goes into <code>index.md</code> under Gaps.</p>\n<p><strong>Orphans.</strong> Pages nothing links to. Either find where they belong and link\nthem, or delete them.</p>\n<p><strong>Stubs.</strong> Pages under about forty words with no links, usually a failed ingest.\nFlag for re-ingest from the original in <code>raw/</code>.</p>\n<p><strong>Schema violations.</strong> Missing frontmatter, wrong type, tags outside the\nvocabulary.</p>\n<p><strong>Near-duplicates.</strong> Similar titles, overlapping aliases, shared inbound links.</p>\n<p><strong>Index drift.</strong> Pages missing from <code>index.md</code>, entries pointing nowhere.</p>\n<h2 id=\"report-before-repairing\">Report before repairing</h2>\n<p>Mechanical fixes happen automatically. Anything requiring judgement gets\nproposed and waits for you.</p>\n<p>That line matters because a linter that merges pages on its own judgement\ndestroys work, and one that only reports produces a list nobody acts on. Broken\nlinks and schema errors are mechanical. Merges and deletions are not.</p>\n<h2 id=\"running-it\">Running it</h2>\n<pre><code>/lint\n</code></pre>\n<p>Weekly, or after any import of more than about twenty sources. Not after every\ningest, where it costs more than it catches.</p>\n<p>Run it on a clean git state, so a wrong repair is one <code>git checkout</code> away.</p>\n<p>Inside Obsidian, <a href=\"https://github.com/Vinzent03/find-unlinked-files\">Find orphaned files and broken\nlinks</a> covers the same two\nchecks visually.</p>\n<p>For a fast read without invoking the agent:</p>\n<pre><code class=\"language-bash\">python3 scripts/link_check.py ~/brain\n</code></pre>\n<h2 id=\"reading-the-output\">Reading the output</h2>\n<p>The counts matter more than the individual items. Three broken links after a\nweek is normal. Forty means something in the ingest instructions changed and is\nproducing links to pages it never creates.</p>\n<p>Track the rates over time rather than the raw numbers, since both grow with the\nvault. See <a href=\"../05-graphs/metrics.md\">metrics</a>.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"review-cadence.md\">Review cadence</a></p>", "headings": ["What a lint checks", "Report before repairing", "Running it", "Reading the output", "Next"], "words": 300, "text": "Structural rot is silent. Nothing errors. The vault just slowly stops answering well because a third of its pages are unreachable and nobody noticed. What a lint checks Broken links. Two distinct cases: a typo or rename, which gets fixed, and a genuine gap, which goes into index.md under Gaps. Orphans. Pages nothing links to. Either find where they belong and link them, or delete them. Stubs. Pages under about forty words with no links, usually a failed ingest. Flag for re-ingest from the original in raw/ . Schema violations. Missing frontmatter, wrong type, tags outside the vocabulary. Near-duplicates. Similar titles, overlapping aliases, shared inbound links. Index drift. Pages missing from index.md , entries pointing nowhere. Report before repairing Mechanical fixes happen automatically. Anything requiring judgement gets proposed and waits for you. That line matters because a linter that merges pages on its own judgement destroys work, and one that only reports produces a list nobody acts on. Broken links and schema errors are mechanical. Merges and deletions are not. Running it /lint Weekly, or after any import of more than about twenty sources. Not after every ingest, where it costs more than it catches. Run it on a clean git state, so a wrong repair is one git checkout away. Inside Obsidian, Find orphaned files and broken links https://github.com/Vinzent03/find-unlinked-files covers the same two checks visually. For a fast read without invoking the agent: bash python3 scripts/link_check.py ~/brain Reading the output The counts matter more than the individual items. Three broken links after a week is normal. Forty means something in the ingest instructions changed and is producing links to pages it never creates. Track the rates over time rather than the raw numbers, since both grow with the vault. See metrics ../05-graphs/metrics.md . Next Review cadence review-cadence.md", "links": [{"to": "05-graphs/metrics", "label": "metrics"}, {"to": "09-maintenance/review-cadence", "label": "Review cadence"}]}, {"id": "09-maintenance/review-cadence", "path": "docs/09-maintenance/review-cadence.md", "section": "09-maintenance", "section_title": "Maintenance", "title": "Review cadence", "html": "<p>Lint keeps the structure sound. Review is what keeps you in the loop, and it is\nthe only maintenance task that produces something you read rather than something\nthat happens.</p>\n<h2 id=\"weekly-ten-minutes\">Weekly, ten minutes</h2>\n<p>The agent prepares it; you read it.</p>\n<pre><code>/review\n</code></pre>\n<p>What comes back: what was added, which concepts gained the most links,\ncontradictions recorded and still unresolved, open questions, and three specific\nthings to read or write next.</p>\n<p>The clusters are the part worth attention. Where your links went last week is\nwhere your attention actually was, which is reliably different from where you\nthink it was.</p>\n<h2 id=\"monthly-structurally\">Monthly, structurally</h2>\n<p>Once a month, look at the vault rather than the week:</p>\n<ul>\n<li>The four <a href=\"../05-graphs/metrics.md\">metrics</a>, appended to a note so you have a\n trend</li>\n<li>Concept pages untouched in ninety days while their topic kept getting sources</li>\n<li>The Gaps list in <code>index.md</code>, which is a reading list you generated without\n trying</li>\n<li>One local graph of a page you wrote recently, as a spot check on linking\n quality</li>\n</ul>\n<h2 id=\"quarterly-honestly\">Quarterly, honestly</h2>\n<p>Two questions.</p>\n<p><strong>What have I changed my mind about?</strong> Only answerable because of the\n<a href=\"../04-structuring/contradictions-and-supersession.md\">supersession rules</a>, and\nworth the whole system on its own.</p>\n<p><strong>What am I keeping that I will never use?</strong> Archive it. A vault carrying dead\nmaterial makes every query slightly worse, forever.</p>\n<h2 id=\"what-to-prune\">What to prune</h2>\n<p>Sources for topics you no longer care about: archive rather than delete, they\ncost nothing in <code>raw/</code> and the wiki pages can go.</p>\n<p>Concept pages that never got a second source: usually means the idea was not\nactually important to you.</p>\n<p>Nothing that is linked. A page five others depend on is load-bearing regardless\nof how it reads.</p>\n<h2 id=\"keep-the-review-short\">Keep the review short</h2>\n<p>A review that lists everything gets skimmed and then ignored. Three\nrecommendations, not ten. If a week produced nothing worth reporting, one line\nsaying so is the correct output.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"versioning-with-git.md\">Versioning</a></p>", "headings": ["Weekly, ten minutes", "Monthly, structurally", "Quarterly, honestly", "What to prune", "Keep the review short", "Next"], "words": 321, "text": "Lint keeps the structure sound. Review is what keeps you in the loop, and it is the only maintenance task that produces something you read rather than something that happens. Weekly, ten minutes The agent prepares it; you read it. /review What comes back: what was added, which concepts gained the most links, contradictions recorded and still unresolved, open questions, and three specific things to read or write next. The clusters are the part worth attention. Where your links went last week is where your attention actually was, which is reliably different from where you think it was. Monthly, structurally Once a month, look at the vault rather than the week: - The four metrics ../05-graphs/metrics.md , appended to a note so you have a trend - Concept pages untouched in ninety days while their topic kept getting sources - The Gaps list in index.md , which is a reading list you generated without trying - One local graph of a page you wrote recently, as a spot check on linking quality Quarterly, honestly Two questions. What have I changed my mind about? Only answerable because of the supersession rules ../04-structuring/contradictions-and-supersession.md , and worth the whole system on its own. What am I keeping that I will never use? Archive it. A vault carrying dead material makes every query slightly worse, forever. What to prune Sources for topics you no longer care about: archive rather than delete, they cost nothing in raw/ and the wiki pages can go. Concept pages that never got a second source: usually means the idea was not actually important to you. Nothing that is linked. A page five others depend on is load-bearing regardless of how it reads. Keep the review short A review that lists everything gets skimmed and then ignored. Three recommendations, not ten. If a week produced nothing worth reporting, one line saying so is the correct output. Next Versioning versioning-with-git.md", "links": [{"to": "05-graphs/metrics", "label": "metrics"}, {"to": "04-structuring/contradictions-and-supersession", "label": "supersession rules"}, {"to": "09-maintenance/versioning-with-git", "label": "Versioning"}]}, {"id": "09-maintenance/versioning-with-git", "path": "docs/09-maintenance/versioning-with-git.md", "section": "09-maintenance", "section_title": "Maintenance", "title": "Versioning", "html": "<p>Git is what makes an agent safe to run unattended. Without it, a bad run is a\nmystery; with it, every change is a diff you can read and revert in one command.</p>\n<h2 id=\"commit-granularity\">Commit granularity</h2>\n<p>One commit per run, with the run named:</p>\n<pre><code>ingest 2026-09-07: 4 sources, 9 pages\nlint 2026-09-07: 3 broken links, 1 merge\n</code></pre>\n<p>Not one commit per file, which buries the history, and not one commit per week,\nwhich makes reverting a single bad run impossible without losing the good ones.</p>\n<p>Scheduled tasks commit their own work as part of the run. See\n<a href=\"../06-agents/scheduled-maintenance.md\">scheduling</a>.</p>\n<h2 id=\"reading-diffs-of-generated-pages\">Reading diffs of generated pages</h2>\n<p>Worth doing in the first weeks, and occasionally after.</p>\n<p>You are looking for two things: pages that changed when they should not have,\nand rewrites where an update was expected. An agent quietly rewriting a page it\nwas asked to append to is the kind of behaviour that only shows up in a diff.</p>\n<p><code>git log --stat</code> after a week tells you which pages your automation touches most,\nwhich is usually informative.</p>\n<h2 id=\"reverting\">Reverting</h2>\n<pre><code class=\"language-bash\">git revert HEAD # undo one run, keep the history\ngit checkout . # discard uncommitted work\ngit checkout HEAD~3 -- wiki/concepts/some-page.md # one page back\n</code></pre>\n<p>The middle one is the reason to commit before any large operation. A backfill\nthat went wrong halfway costs you the run rather than the vault.</p>\n<h2 id=\"branches\">Branches</h2>\n<p>Worth it for experiments that touch structure: a new page contract, a schema\nchange, a bulk re-ingest under different instructions.</p>\n<pre><code class=\"language-bash\">git checkout -b new-schema\n</code></pre>\n<p>Run it, read the result, merge or delete the branch. Doing this on <code>main</code> and\ndeciding afterwards is how vaults end up in a half-migrated state that nobody\nwants to finish.</p>\n<h2 id=\"what-not-to-commit\">What not to commit</h2>\n<p><code>.obsidian/workspace*</code>, caches, and anything containing a key. The Local REST API\nkey lives in plugin data, so check <code>.obsidian/plugins/</code> before the first push.</p>\n<p>Keep the remote private unless you have deliberately made the vault public.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"backups-and-portability.md\">Backups and portability</a></p>", "headings": ["Commit granularity", "Reading diffs of generated pages", "Reverting", "Branches", "What not to commit", "Next"], "words": 338, "text": "Git is what makes an agent safe to run unattended. Without it, a bad run is a mystery; with it, every change is a diff you can read and revert in one command. Commit granularity One commit per run, with the run named: ingest 2026-09-07: 4 sources, 9 pages lint 2026-09-07: 3 broken links, 1 merge Not one commit per file, which buries the history, and not one commit per week, which makes reverting a single bad run impossible without losing the good ones. Scheduled tasks commit their own work as part of the run. See scheduling ../06-agents/scheduled-maintenance.md . Reading diffs of generated pages Worth doing in the first weeks, and occasionally after. You are looking for two things: pages that changed when they should not have, and rewrites where an update was expected. An agent quietly rewriting a page it was asked to append to is the kind of behaviour that only shows up in a diff. git log --stat after a week tells you which pages your automation touches most, which is usually informative. Reverting bash git revert HEAD undo one run, keep the history git checkout . discard uncommitted work git checkout HEAD~3 -- wiki/concepts/some-page.md one page back The middle one is the reason to commit before any large operation. A backfill that went wrong halfway costs you the run rather than the vault. Branches Worth it for experiments that touch structure: a new page contract, a schema change, a bulk re-ingest under different instructions. bash git checkout -b new-schema Run it, read the result, merge or delete the branch. Doing this on main and deciding afterwards is how vaults end up in a half-migrated state that nobody wants to finish. What not to commit .obsidian/workspace , caches, and anything containing a key. The Local REST API key lives in plugin data, so check .obsidian/plugins/ before the first push. Keep the remote private unless you have deliberately made the vault public. Next Backups and portability backups-and-portability.md", "links": [{"to": "06-agents/scheduled-maintenance", "label": "scheduling"}, {"to": "09-maintenance/backups-and-portability", "label": "Backups and portability"}]}, {"id": "09-maintenance/backups-and-portability", "path": "docs/09-maintenance/backups-and-portability.md", "section": "09-maintenance", "section_title": "Maintenance", "title": "Backups and portability", "html": "<h2 id=\"sync-is-not-backup\">Sync is not backup</h2>\n<p>This is the whole page, and it is the mistake almost everyone makes.</p>\n<p>Sync propagates. If an automation rewrites two hundred pages badly, sync\nfaithfully copies the damage to every device within seconds. If a file is\ndeleted, it is deleted everywhere.</p>\n<p>Backup means a copy that does not follow. At least one, disconnected from the\nsync path.</p>\n<h2 id=\"a-workable-arrangement\">A workable arrangement</h2>\n<p><strong>Git remote,</strong> private, pushed after every run. Versioned, so it covers the\n\"what did it look like three weeks ago\" case that a file backup does not.</p>\n<p><strong>Sync</strong> for working across machines, whichever kind you already use.</p>\n<p><strong>A periodic archive</strong> to external or separate cloud storage, not connected to\neither of the above. Monthly is enough.</p>\n<p>Three copies, one of which is dumb and slow, is the arrangement that survives the\nfailure modes that actually happen.</p>\n<h2 id=\"test-a-restore\">Test a restore</h2>\n<p>Once. Take the archive, restore it somewhere else, open it in Obsidian, and check\nthe links work.</p>\n<p>Untested backups fail at a reliably bad moment, and the common failure is not\ncorruption. It is discovering that the archive excluded a folder, or captured the\nvault mid-sync in a half-written state.</p>\n<h2 id=\"what-you-are-protecting-against\">What you are protecting against</h2>\n<p>Not disk failure, which is rare and which sync handles.</p>\n<p>The real risk is an automation that quietly did something wrong three weeks ago,\nwhich you notice now. That needs history, which is why git carries more of the\nload here than file backups.</p>\n<h2 id=\"portability\">Portability</h2>\n<p>The vault is markdown and wikilinks, so leaving any particular tool costs\nnothing structural. What is worth checking occasionally:</p>\n<p><strong>Nothing important lives outside the files.</strong> Plugin-specific metadata, canvas\nfiles, database exports. All fine as extras, none of it should carry knowledge\nthat exists nowhere else.</p>\n<p><strong>Links resolve without Obsidian.</strong> <code>scripts/link_check.py</code> verifies this, since\nit parses wikilinks itself.</p>\n<p><strong>The agent instructions are in the vault,</strong> not in a chat history or an app\nsetting. <code>CLAUDE.md</code>, skills and commands travel with the folder.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"privacy-and-secrets.md\">Privacy</a></p>", "headings": ["Sync is not backup", "A workable arrangement", "Test a restore", "What you are protecting against", "Portability", "Next"], "words": 333, "text": "Sync is not backup This is the whole page, and it is the mistake almost everyone makes. Sync propagates. If an automation rewrites two hundred pages badly, sync faithfully copies the damage to every device within seconds. If a file is deleted, it is deleted everywhere. Backup means a copy that does not follow. At least one, disconnected from the sync path. A workable arrangement Git remote, private, pushed after every run. Versioned, so it covers the \"what did it look like three weeks ago\" case that a file backup does not. Sync for working across machines, whichever kind you already use. A periodic archive to external or separate cloud storage, not connected to either of the above. Monthly is enough. Three copies, one of which is dumb and slow, is the arrangement that survives the failure modes that actually happen. Test a restore Once. Take the archive, restore it somewhere else, open it in Obsidian, and check the links work. Untested backups fail at a reliably bad moment, and the common failure is not corruption. It is discovering that the archive excluded a folder, or captured the vault mid-sync in a half-written state. What you are protecting against Not disk failure, which is rare and which sync handles. The real risk is an automation that quietly did something wrong three weeks ago, which you notice now. That needs history, which is why git carries more of the load here than file backups. Portability The vault is markdown and wikilinks, so leaving any particular tool costs nothing structural. What is worth checking occasionally: Nothing important lives outside the files. Plugin-specific metadata, canvas files, database exports. All fine as extras, none of it should carry knowledge that exists nowhere else. Links resolve without Obsidian. scripts/link_check.py verifies this, since it parses wikilinks itself. The agent instructions are in the vault, not in a chat history or an app setting. CLAUDE.md , skills and commands travel with the folder. Next Privacy privacy-and-secrets.md", "links": [{"to": "09-maintenance/privacy-and-secrets", "label": "Privacy"}]}, {"id": "09-maintenance/privacy-and-secrets", "path": "docs/09-maintenance/privacy-and-secrets.md", "section": "09-maintenance", "section_title": "Maintenance", "title": "Privacy", "html": "<p>A mature second brain is one of the highest-signal documents about a person that\nexists. Everything you read, worked on, worried about and asked, connected and\nindexed.</p>\n<p>That is the point, and it is the reason to be deliberate about what goes in and\nwhere it lives.</p>\n<h2 id=\"decide-at-capture-not-later\">Decide at capture, not later</h2>\n<p>Redaction after ingest does not work. By the time you decide something should not\nbe there, it has propagated into concept pages, links and synthesis pages, and\nremoving it means finding all of them.</p>\n<p>Decide before the file lands in <code>raw/</code>. See <a href=\"../03-ingestion/chat-exports.md\">chat\nexports</a>, which is where this bites hardest,\nbecause chat history contains more than any other source and is imported in bulk.</p>\n<h2 id=\"what-does-not-belong\">What does not belong</h2>\n<p><strong>Credentials of any kind.</strong> Not because the agent leaks them, but because the\nvault gets synced, committed, backed up and occasionally shared. Every copy is\nanother place the key exists.</p>\n<p><strong>Other people's private information.</strong> Meeting transcripts, personal messages,\nanything told to you in confidence. Your notes are not the right home for\nsomeone else's confidences, and they did not consent to being ingested.</p>\n<p><strong>Material you are contractually bound to keep confidential.</strong> Client work under\nNDA in a vault that syncs to a personal cloud account is a real exposure.</p>\n<h2 id=\"separate-vaults-over-careful-filtering\">Separate vaults over careful filtering</h2>\n<p>If you have material that must not mix, use a separate vault rather than tags or\nfolders inside one.</p>\n<p>A single vault with a private section relies on every query, every export and\nevery publish step respecting the boundary. Two vaults cannot leak into each\nother, and the cost is having to pick which one to open.</p>\n<h2 id=\"local-models-for-sensitive-material\">Local models for sensitive material</h2>\n<p>If a category of material should not leave your machine at all, a local model\nhandles ingestion for that vault. Quality is lower than a frontier model, which\nis the trade.</p>\n<p>Worth it for medical, legal or financial material. Usually not worth it for\narticles about software.</p>\n<h2 id=\"publishing\">Publishing</h2>\n<p>Explicit opt-in only. See <a href=\"../08-outputs/publishing-and-export.md\">publishing and\nexport</a>.</p>\n<h2 id=\"before-sharing-a-vault\">Before sharing a vault</h2>\n<p>Search it for keys, run through the frontmatter for personal identifiers, and\nread the log for what was ingested from where. Once shared, it is out, and the\ngraph makes it easy for a reader to assemble a picture you did not intend to\ngive.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"scaling.md\">Scaling past a thousand pages</a></p>", "headings": ["Decide at capture, not later", "What does not belong", "Separate vaults over careful filtering", "Local models for sensitive material", "Publishing", "Before sharing a vault", "Next"], "words": 393, "text": "A mature second brain is one of the highest-signal documents about a person that exists. Everything you read, worked on, worried about and asked, connected and indexed. That is the point, and it is the reason to be deliberate about what goes in and where it lives. Decide at capture, not later Redaction after ingest does not work. By the time you decide something should not be there, it has propagated into concept pages, links and synthesis pages, and removing it means finding all of them. Decide before the file lands in raw/ . See chat exports ../03-ingestion/chat-exports.md , which is where this bites hardest, because chat history contains more than any other source and is imported in bulk. What does not belong Credentials of any kind. Not because the agent leaks them, but because the vault gets synced, committed, backed up and occasionally shared. Every copy is another place the key exists. Other people's private information. Meeting transcripts, personal messages, anything told to you in confidence. Your notes are not the right home for someone else's confidences, and they did not consent to being ingested. Material you are contractually bound to keep confidential. Client work under NDA in a vault that syncs to a personal cloud account is a real exposure. Separate vaults over careful filtering If you have material that must not mix, use a separate vault rather than tags or folders inside one. A single vault with a private section relies on every query, every export and every publish step respecting the boundary. Two vaults cannot leak into each other, and the cost is having to pick which one to open. Local models for sensitive material If a category of material should not leave your machine at all, a local model handles ingestion for that vault. Quality is lower than a frontier model, which is the trade. Worth it for medical, legal or financial material. Usually not worth it for articles about software. Publishing Explicit opt-in only. See publishing and export ../08-outputs/publishing-and-export.md . Before sharing a vault Search it for keys, run through the frontmatter for personal identifiers, and read the log for what was ingested from where. Once shared, it is out, and the graph makes it easy for a reader to assemble a picture you did not intend to give. Next Scaling past a thousand pages scaling.md", "links": [{"to": "03-ingestion/chat-exports", "label": "chat\nexports"}, {"to": "08-outputs/publishing-and-export", "label": "publishing and\nexport"}, {"to": "09-maintenance/scaling", "label": "Scaling past a thousand pages"}]}, {"id": "09-maintenance/scaling", "path": "docs/09-maintenance/scaling.md", "section": "09-maintenance", "section_title": "Maintenance", "title": "Scaling past a thousand pages", "html": "<p>Most of this guide assumes a vault of a few hundred to a few thousand pages,\nwhich is where personal vaults live for years. Past that, some things strain.</p>\n<h2 id=\"what-actually-breaks\">What actually breaks</h2>\n<p><strong>Not search.</strong> Ripgrep over ten thousand markdown files is still instant.</p>\n<p><strong>Not Obsidian,</strong> although the global graph view stops being usable somewhere\naround a thousand nodes.</p>\n<p><strong>Retrieval economy.</strong> The index gets long enough that reading it costs real\ncontext, which is the first genuine constraint.</p>\n<p><strong>Your attention.</strong> A thousand pages is more than you can hold a mental map of,\nwhich is precisely when the vault becomes more useful and also when you stop\nnoticing that parts of it have rotted.</p>\n<h2 id=\"summary-layers\">Summary layers</h2>\n<p>The fix for the index problem: one level between the master index and the pages.</p>\n<p>A short page per topic area, listing what is in it and what each page covers. The\nagent reads the master index, opens the one topic index that matters, then opens\npages. Three cheap reads instead of one expensive one.</p>\n<p>Two levels is enough. Three means summaries of summaries, which drift from what\nthey describe and get read instead of it.</p>\n<h2 id=\"splitting-vaults\">Splitting vaults</h2>\n<p>Split by domain when two areas genuinely do not inform each other: work and a\nhobby, two unrelated fields.</p>\n<p>Do not split by date or by size. The whole value is that old material connects to\nnew, and a vault split chronologically severs exactly the connections worth\nhaving.</p>\n<p>The cost of splitting is that cross-domain connections stop happening, and those\nare often the interesting ones. Split late and reluctantly.</p>\n<h2 id=\"archiving\">Archiving</h2>\n<p>Move cold material to an <code>archive/</code> folder outside <code>wiki/</code>: still on disk, still\nsearchable with ripgrep, no longer in the index or the graph.</p>\n<p>Reversible, which matters, because \"cold\" is a guess. A topic you archived can be\nbrought back if it turns out to matter again.</p>\n<h2 id=\"pruning-what-never-mattered\">Pruning what never mattered</h2>\n<p>Concept pages with one source and no inbound links after a year were never\nconcepts, they were paragraphs. Deleting them improves everything else by\nreducing what queries have to read past.</p>\n<p>Run this once a year, not continuously.</p>\n<h2 id=\"the-honest-ceiling\">The honest ceiling</h2>\n<p>Somewhere past ten thousand pages, a curated wiki stops being the right structure\nfor a single person, because nobody can curate at that rate and the curation is\nwhat made it work.</p>\n<p>If you are there, either the vault has stopped being personal, or ingestion has\nbeen running without judgement for a long time. The second is far more common,\nand the fix is upstream, in what you feed it.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"../10-troubleshooting/README.md\">Troubleshooting</a>.</p>", "headings": ["What actually breaks", "Summary layers", "Splitting vaults", "Archiving", "Pruning what never mattered", "The honest ceiling", "Next"], "words": 434, "text": "Most of this guide assumes a vault of a few hundred to a few thousand pages, which is where personal vaults live for years. Past that, some things strain. What actually breaks Not search. Ripgrep over ten thousand markdown files is still instant. Not Obsidian, although the global graph view stops being usable somewhere around a thousand nodes. Retrieval economy. The index gets long enough that reading it costs real context, which is the first genuine constraint. Your attention. A thousand pages is more than you can hold a mental map of, which is precisely when the vault becomes more useful and also when you stop noticing that parts of it have rotted. Summary layers The fix for the index problem: one level between the master index and the pages. A short page per topic area, listing what is in it and what each page covers. The agent reads the master index, opens the one topic index that matters, then opens pages. Three cheap reads instead of one expensive one. Two levels is enough. Three means summaries of summaries, which drift from what they describe and get read instead of it. Splitting vaults Split by domain when two areas genuinely do not inform each other: work and a hobby, two unrelated fields. Do not split by date or by size. The whole value is that old material connects to new, and a vault split chronologically severs exactly the connections worth having. The cost of splitting is that cross-domain connections stop happening, and those are often the interesting ones. Split late and reluctantly. Archiving Move cold material to an archive/ folder outside wiki/ : still on disk, still searchable with ripgrep, no longer in the index or the graph. Reversible, which matters, because \"cold\" is a guess. A topic you archived can be brought back if it turns out to matter again. Pruning what never mattered Concept pages with one source and no inbound links after a year were never concepts, they were paragraphs. Deleting them improves everything else by reducing what queries have to read past. Run this once a year, not continuously. The honest ceiling Somewhere past ten thousand pages, a curated wiki stops being the right structure for a single person, because nobody can curate at that rate and the curation is what made it work. If you are there, either the vault has stopped being personal, or ingestion has been running without judgement for a long time. The second is far more common, and the fix is upstream, in what you feed it. Next Troubleshooting ../10-troubleshooting/README.md .", "links": []}, {"id": "10-troubleshooting/common-failures", "path": "docs/10-troubleshooting/common-failures.md", "section": "10-troubleshooting", "section_title": "Troubleshooting", "title": "The failures everyone hits", "html": "<h2 id=\"the-vault-stalls-after-two-weeks\">The vault stalls after two weeks</h2>\n<p>Almost always capture, not the system. Clipping takes three clicks instead of\none, or the phone has no path into the vault, so material stops arriving and\nthere is nothing to process.</p>\n<p>Fix the capture path, not the vault. See\n<a href=\"../03-ingestion/README.md\">Ingestion</a>.</p>\n<p>The other cause is expecting the payoff too early. At thirty pages there is\nnothing to connect. See <a href=\"../01-concepts/what-good-looks-like.md\">what good looks\nlike</a> for the real timeline.</p>\n<h2 id=\"pages-are-summaries-of-summaries\">Pages are summaries of summaries</h2>\n<p>Source pages that summarise the article, concept pages that summarise the source\npages. Each layer loses information and the bottom layer is what gets read.</p>\n<p>The cause is a page contract that says \"summarise\" anywhere in it. Concept pages\nexplain an idea in plain language, in your words, standing on their own. Rewrite\nthe contract in <code>CLAUDE.md</code> and re-ingest a few sources to check.</p>\n<h2 id=\"the-agent-rewrites-work-you-did-by-hand\">The agent rewrites work you did by hand</h2>\n<p>Infuriating and preventable. Mark hand-written pages in frontmatter:</p>\n<pre><code class=\"language-yaml\">maintained_by: human\n</code></pre>\n<p>And in <code>CLAUDE.md</code>: never rewrite a page marked <code>maintained_by: human</code>, only\nappend links and flag issues for the owner.</p>\n<h2 id=\"ingest-quality-drops-as-the-vault-grows\">Ingest quality drops as the vault grows</h2>\n<p>Real, and the cause is usually context. Ingesting into a vault of three hundred\npages means the agent should be checking what exists first, and if it is not, it\ncreates new pages instead of updating.</p>\n<p>Check that ingestion reads <code>index.md</code> before writing. That one step is what keeps\nquality flat as the vault grows.</p>\n<h2 id=\"everything-connects-to-everything\">Everything connects to everything</h2>\n<p>A few hub pages have accumulated every link, so the graph says nothing. Split\nthe hubs into the specific ideas people are actually linking to. See <a href=\"../04-structuring/linking-rules.md\">linking\nrules</a>.</p>\n<h2 id=\"you-stopped-opening-it\">You stopped opening it</h2>\n<p>The honest failure. Usually capture broke months ago and the vault has been\nstatic, or the review is too long to read.</p>\n<p>Both are fixable. Neither is a reason to start over with a different tool, which\nis the instinct and always costs another month.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"agent-writes-garbage.md\">The agent writes garbage</a></p>", "headings": ["The vault stalls after two weeks", "Pages are summaries of summaries", "The agent rewrites work you did by hand", "Ingest quality drops as the vault grows", "Everything connects to everything", "You stopped opening it", "Next"], "words": 336, "text": "The vault stalls after two weeks Almost always capture, not the system. Clipping takes three clicks instead of one, or the phone has no path into the vault, so material stops arriving and there is nothing to process. Fix the capture path, not the vault. See Ingestion ../03-ingestion/README.md . The other cause is expecting the payoff too early. At thirty pages there is nothing to connect. See what good looks like ../01-concepts/what-good-looks-like.md for the real timeline. Pages are summaries of summaries Source pages that summarise the article, concept pages that summarise the source pages. Each layer loses information and the bottom layer is what gets read. The cause is a page contract that says \"summarise\" anywhere in it. Concept pages explain an idea in plain language, in your words, standing on their own. Rewrite the contract in CLAUDE.md and re-ingest a few sources to check. The agent rewrites work you did by hand Infuriating and preventable. Mark hand-written pages in frontmatter: yaml maintained_by: human And in CLAUDE.md : never rewrite a page marked maintained_by: human , only append links and flag issues for the owner. Ingest quality drops as the vault grows Real, and the cause is usually context. Ingesting into a vault of three hundred pages means the agent should be checking what exists first, and if it is not, it creates new pages instead of updating. Check that ingestion reads index.md before writing. That one step is what keeps quality flat as the vault grows. Everything connects to everything A few hub pages have accumulated every link, so the graph says nothing. Split the hubs into the specific ideas people are actually linking to. See linking rules ../04-structuring/linking-rules.md . You stopped opening it The honest failure. Usually capture broke months ago and the vault has been static, or the review is too long to read. Both are fixable. Neither is a reason to start over with a different tool, which is the instinct and always costs another month. Next The agent writes garbage agent-writes-garbage.md", "links": [{"to": "01-concepts/what-good-looks-like", "label": "what good looks\nlike"}, {"to": "04-structuring/linking-rules", "label": "linking\nrules"}, {"to": "10-troubleshooting/agent-writes-garbage", "label": "The agent writes garbage"}]}, {"id": "10-troubleshooting/agent-writes-garbage", "path": "docs/10-troubleshooting/agent-writes-garbage.md", "section": "10-troubleshooting", "section_title": "Troubleshooting", "title": "The agent writes garbage", "html": "<p>Pages that are technically about the right thing and useless to read.</p>\n<h2 id=\"diagnose-the-source-first\">Diagnose the source first</h2>\n<p>Before touching instructions, check the input. Open the file in <code>raw/</code> and read\nit.</p>\n<p>Half of the bad pages people blame on the agent come from a bad extraction: a PDF\nwhose columns interleaved, an auto-caption transcript with no punctuation, a\nclipped page that captured the cookie banner instead of the article.</p>\n<p>The agent cannot write a good page from mangled text, and it will not tell you it\nis struggling. See <a href=\"../03-ingestion/pdfs-and-books.md\">PDFs</a> and\n<a href=\"../03-ingestion/youtube-transcripts.md\">transcripts</a>.</p>\n<h2 id=\"then-check-claudemd\">Then check CLAUDE.md</h2>\n<p>If the source is clean, the page contract is the problem.</p>\n<p>The specific things that produce vague pages: no definition of what each page\ntype contains, the word \"summarise\" anywhere, no instruction to write for a\nreader who has not seen the source, no requirement to link.</p>\n<p>Rewrite the contract with the shape spelled out. See <a href=\"../04-structuring/page-types.md\">page\ntypes</a>.</p>\n<h2 id=\"add-an-example-not-another-rule\">Add an example, not another rule</h2>\n<p>The highest-leverage fix and the least used. Put one good concept page in\n<code>CLAUDE.md</code>, in full, as the target.</p>\n<p>Rules describe the output abstractly and each new rule interacts with the others.\nOne example communicates the target directly, and it is what a person would ask\nfor if you told them to match a style.</p>\n<h2 id=\"ask-what-it-was-working-from\">Ask what it was working from</h2>\n<pre><code>You wrote [[page]]. Which parts of the source did you use, and what did you leave\nout?\n</code></pre>\n<p>The answer usually identifies the problem immediately: it read a fragment, it\ncould not tell what the source claimed versus reported, or the instructions\npulled it toward summarising.</p>\n<h2 id=\"roll-back-and-re-run\">Roll back and re-run</h2>\n<p>Fix the contract, revert the bad pages, re-ingest.</p>\n<pre><code class=\"language-bash\">git checkout HEAD~1 -- wiki/\n</code></pre>\n<p>Do not patch the bad pages by hand. If the contract was wrong, every page from\nthat run has the same flaw, and hand-fixing the three you noticed leaves the rest.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"broken-links.md\">Broken links and orphans</a></p>", "headings": ["Diagnose the source first", "Then check CLAUDE.md", "Add an example, not another rule", "Ask what it was working from", "Roll back and re-run", "Next"], "words": 327, "text": "Pages that are technically about the right thing and useless to read. Diagnose the source first Before touching instructions, check the input. Open the file in raw/ and read it. Half of the bad pages people blame on the agent come from a bad extraction: a PDF whose columns interleaved, an auto-caption transcript with no punctuation, a clipped page that captured the cookie banner instead of the article. The agent cannot write a good page from mangled text, and it will not tell you it is struggling. See PDFs ../03-ingestion/pdfs-and-books.md and transcripts ../03-ingestion/youtube-transcripts.md . Then check CLAUDE.md If the source is clean, the page contract is the problem. The specific things that produce vague pages: no definition of what each page type contains, the word \"summarise\" anywhere, no instruction to write for a reader who has not seen the source, no requirement to link. Rewrite the contract with the shape spelled out. See page types ../04-structuring/page-types.md . Add an example, not another rule The highest-leverage fix and the least used. Put one good concept page in CLAUDE.md , in full, as the target. Rules describe the output abstractly and each new rule interacts with the others. One example communicates the target directly, and it is what a person would ask for if you told them to match a style. Ask what it was working from You wrote page . Which parts of the source did you use, and what did you leave out? The answer usually identifies the problem immediately: it read a fragment, it could not tell what the source claimed versus reported, or the instructions pulled it toward summarising. Roll back and re-run Fix the contract, revert the bad pages, re-ingest. bash git checkout HEAD~1 -- wiki/ Do not patch the bad pages by hand. If the contract was wrong, every page from that run has the same flaw, and hand-fixing the three you noticed leaves the rest. Next Broken links and orphans broken-links.md", "links": [{"to": "03-ingestion/pdfs-and-books", "label": "PDFs"}, {"to": "03-ingestion/youtube-transcripts", "label": "transcripts"}, {"to": "04-structuring/page-types", "label": "page\ntypes"}, {"to": "10-troubleshooting/broken-links", "label": "Broken links and orphans"}]}, {"id": "10-troubleshooting/broken-links", "path": "docs/10-troubleshooting/broken-links.md", "section": "10-troubleshooting", "section_title": "Troubleshooting", "title": "Broken links and orphans", "html": "<pre><code class=\"language-bash\">python3 scripts/link_check.py ~/brain\n</code></pre>\n<h2 id=\"why-renames-break-links\">Why renames break links</h2>\n<p>Obsidian updates links when you rename inside the app. An agent renaming a file\ndirectly does not, and that is the most common cause of broken links in an\nagent-maintained vault.</p>\n<p>Prevent it with a rule in <code>CLAUDE.md</code>: renames update every inbound link, add the\nold name as an alias, and get recorded in <code>log.md</code>. See <a href=\"../04-structuring/naming-and-aliases.md\">naming and\naliases</a>.</p>\n<h2 id=\"fixing-in-bulk\">Fixing in bulk</h2>\n<p>Two categories, handled differently.</p>\n<p><strong>Typos and renames</strong> get fixed: point the link at the right page. Safe to\nautomate.</p>\n<p><strong>Genuine gaps</strong>, where the target never existed, go into <code>index.md</code> under Gaps.\nDo not create empty pages to satisfy them; an empty page is worse than a\nrecorded gap because it looks like coverage.</p>\n<p>Always on a clean git state, so a bad bulk fix is one command to undo.</p>\n<h2 id=\"orphans\">Orphans</h2>\n<p>Pages nothing links to. Three cases.</p>\n<p><strong>Should be linked and is not.</strong> Find the pages that ought to reference it and\nadd the links. This is the common case after a bulk import.</p>\n<p><strong>Genuinely standalone.</strong> Rare and usually a sign the material does not belong in\nthe wiki. Reference material and checklists belong in a project folder.</p>\n<p><strong>Failed ingest.</strong> A stub that never got connected. Re-ingest from the original\nin <code>raw/</code>.</p>\n<h2 id=\"preventing-both-at-ingest\">Preventing both at ingest</h2>\n<p>The rule that removes most of this work: nothing is ingested until it is linked,\nin both directions, in the same run.</p>\n<p>An ingest that ends with unlinked pages is an ingest that did not finish. Enforce\nit in the skill rather than cleaning up weekly.</p>\n<h2 id=\"after-a-big-import\">After a big import</h2>\n<p>Always lint. A large backfill reliably produces orphans and near-duplicates,\nbecause the agent was moving fast through material that overlapped.</p>\n<p>Budget for it: a thousand-source import is followed by a lint pass and a merge\nreview, and skipping that step is what leaves a vault permanently messy.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"vault-too-big.md\">The vault got too big</a></p>", "headings": ["Why renames break links", "Fixing in bulk", "Orphans", "Preventing both at ingest", "After a big import", "Next"], "words": 325, "text": "bash python3 scripts/link_check.py ~/brain Why renames break links Obsidian updates links when you rename inside the app. An agent renaming a file directly does not, and that is the most common cause of broken links in an agent-maintained vault. Prevent it with a rule in CLAUDE.md : renames update every inbound link, add the old name as an alias, and get recorded in log.md . See naming and aliases ../04-structuring/naming-and-aliases.md . Fixing in bulk Two categories, handled differently. Typos and renames get fixed: point the link at the right page. Safe to automate. Genuine gaps , where the target never existed, go into index.md under Gaps. Do not create empty pages to satisfy them; an empty page is worse than a recorded gap because it looks like coverage. Always on a clean git state, so a bad bulk fix is one command to undo. Orphans Pages nothing links to. Three cases. Should be linked and is not. Find the pages that ought to reference it and add the links. This is the common case after a bulk import. Genuinely standalone. Rare and usually a sign the material does not belong in the wiki. Reference material and checklists belong in a project folder. Failed ingest. A stub that never got connected. Re-ingest from the original in raw/ . Preventing both at ingest The rule that removes most of this work: nothing is ingested until it is linked, in both directions, in the same run. An ingest that ends with unlinked pages is an ingest that did not finish. Enforce it in the skill rather than cleaning up weekly. After a big import Always lint. A large backfill reliably produces orphans and near-duplicates, because the agent was moving fast through material that overlapped. Budget for it: a thousand-source import is followed by a lint pass and a merge review, and skipping that step is what leaves a vault permanently messy. Next The vault got too big vault-too-big.md", "links": [{"to": "04-structuring/naming-and-aliases", "label": "naming and\naliases"}, {"to": "10-troubleshooting/vault-too-big", "label": "The vault got too big"}]}, {"id": "10-troubleshooting/vault-too-big", "path": "docs/10-troubleshooting/vault-too-big.md", "section": "10-troubleshooting", "section_title": "Troubleshooting", "title": "The vault got too big", "html": "<h2 id=\"symptoms\">Symptoms</h2>\n<p>Answers get slower and vaguer. The agent reads twenty pages and returns something\ngeneral. The graph view is a hairball. You cannot remember whether a topic is\ncovered, and checking takes longer than searching the web.</p>\n<h2 id=\"what-it-usually-is-not\">What it usually is not</h2>\n<p>Disk, search speed, or Obsidian. Those all scale fine.</p>\n<p>What it actually is: retrieval economy. The index is long enough that reading it\ncosts real context, so the agent either skips it or spends its budget there\ninstead of on pages.</p>\n<h2 id=\"first-check-it-is-size-and-not-rot\">First, check it is size and not rot</h2>\n<p>Run the <a href=\"../05-graphs/metrics.md\">metrics</a>. A vault with a twenty percent orphan\nrate does not have a size problem, it has a linking problem, and splitting it\nwill not help.</p>\n<p>Genuinely large and healthy looks like: low orphan rate, one dominant component,\naverage degree in range, and an index over a few hundred entries.</p>\n<h2 id=\"summary-layers\">Summary layers</h2>\n<p>The first fix and usually enough. One index per topic area between the master\nindex and the pages, so the agent makes three cheap reads instead of one\nexpensive one. See <a href=\"../09-maintenance/scaling.md\">scaling</a>.</p>\n<h2 id=\"splitting\">Splitting</h2>\n<p>By domain, never by date. Two vaults that genuinely do not inform each other.</p>\n<p>Accept that cross-domain connections stop happening. Those are often the\ninteresting ones, which is why splitting is a late move rather than a first\nresponse.</p>\n<h2 id=\"archiving\">Archiving</h2>\n<p>Cold material to <code>archive/</code>, outside <code>wiki/</code>. Still searchable, out of the index\nand the graph, reversible.</p>\n<p>Better than deleting, because \"cold\" is a guess and archived material can come\nback.</p>\n<h2 id=\"rebuild-the-index\">Rebuild the index</h2>\n<p>Sometimes the index has simply drifted: entries for pages that moved, missing\nentries for pages added by runs that failed halfway.</p>\n<pre><code>Rebuild index.md from the actual contents of wiki/. Group by type and theme, one\nline of description per entry, and list gaps at the bottom.\n</code></pre>\n<p>Cheap, and it fixes a surprising share of \"the vault feels broken\" complaints.</p>\n<h2 id=\"next\">Next</h2>\n<p><a href=\"faq.md\">FAQ</a></p>", "headings": ["Symptoms", "What it usually is not", "First, check it is size and not rot", "Summary layers", "Splitting", "Archiving", "Rebuild the index", "Next"], "words": 322, "text": "Symptoms Answers get slower and vaguer. The agent reads twenty pages and returns something general. The graph view is a hairball. You cannot remember whether a topic is covered, and checking takes longer than searching the web. What it usually is not Disk, search speed, or Obsidian. Those all scale fine. What it actually is: retrieval economy. The index is long enough that reading it costs real context, so the agent either skips it or spends its budget there instead of on pages. First, check it is size and not rot Run the metrics ../05-graphs/metrics.md . A vault with a twenty percent orphan rate does not have a size problem, it has a linking problem, and splitting it will not help. Genuinely large and healthy looks like: low orphan rate, one dominant component, average degree in range, and an index over a few hundred entries. Summary layers The first fix and usually enough. One index per topic area between the master index and the pages, so the agent makes three cheap reads instead of one expensive one. See scaling ../09-maintenance/scaling.md . Splitting By domain, never by date. Two vaults that genuinely do not inform each other. Accept that cross-domain connections stop happening. Those are often the interesting ones, which is why splitting is a late move rather than a first response. Archiving Cold material to archive/ , outside wiki/ . Still searchable, out of the index and the graph, reversible. Better than deleting, because \"cold\" is a guess and archived material can come back. Rebuild the index Sometimes the index has simply drifted: entries for pages that moved, missing entries for pages added by runs that failed halfway. Rebuild index.md from the actual contents of wiki/. Group by type and theme, one line of description per entry, and list gaps at the bottom. Cheap, and it fixes a surprising share of \"the vault feels broken\" complaints. Next FAQ faq.md", "links": [{"to": "05-graphs/metrics", "label": "metrics"}, {"to": "09-maintenance/scaling", "label": "scaling"}, {"to": "10-troubleshooting/faq", "label": "FAQ"}]}, {"id": "10-troubleshooting/faq", "path": "docs/10-troubleshooting/faq.md", "section": "10-troubleshooting", "section_title": "Troubleshooting", "title": "FAQ", "html": "<p><strong>Do I need MCP?</strong></p>\n<p>No. Claude Code started inside the vault folder reads and writes it directly.\nMCP adds the ability to reach the vault from sessions not running in it, which\nmatters mainly for scheduled tasks. See <a href=\"../02-setup/mcp-obsidian.md\">MCP for\nObsidian</a>.</p>\n<p><strong>Does this work with agents other than Claude Code?</strong></p>\n<p>Yes. The vault is markdown and the skills are <code>SKILL.md</code> files, a format several\nagents read. Anything that can read and write files in a folder can maintain the\nvault; the instructions in <code>CLAUDE.md</code> may need renaming for other tools.</p>\n<p><strong>How much does it cost to run?</strong></p>\n<p>Depends entirely on volume. A daily ingest of a handful of articles is small. A\none-time backfill of a thousand sources is not, which is why the\n<a href=\"../03-ingestion/bulk-backfill.md\">backfill</a> page insists on batches with visible\ncosts.</p>\n<p><strong>Can I use a local model?</strong></p>\n<p>For ingestion of sensitive material, yes, with lower quality. Local models are\nweaker at the judgement calls that matter here: what deserves its own page, when\ntwo sources genuinely disagree. A workable split is a local model for private\nmaterial and a frontier model for everything else.</p>\n<p><strong>Do I need Obsidian?</strong></p>\n<p>No. The vault is a folder of markdown files. Obsidian is a good viewer for the\ngraph and has the Web Clipper, which is the strongest practical reason to use it.\nLogseq, Foam, or a plain editor all work.</p>\n<p><strong>What if I already have a Notion or Evernote full of notes?</strong></p>\n<p>Use the official <a href=\"https://github.com/obsidianmd/obsidian-importer\">Importer</a>\nplugin, which handles Notion, Evernote, Roam, Bear and Apple Notes. Then treat\nthe result as raw material: backfill oldest first. Expect the\nexport to be messy. Fix extraction before ingesting rather than hoping the agent\ncopes.</p>\n<p><strong>How is this different from a memory feature?</strong></p>\n<p>Memory features remember facts about you across sessions and belong to the tool.\nThis is a body of knowledge you own as files, that outlives the tool, and that\nyou can read, edit and publish yourself.</p>\n<p><strong>Will the agent make things up?</strong></p>\n<p>It can, which is why every rule in <a href=\"../04-structuring/README.md\">structuring</a> is\nabout attribution: claims recorded as claims, sources attached, gaps stated\nrather than filled. A page with no source behind a specific number is the thing\nto watch for.</p>\n<p><strong>Is the graph view actually useful or is it just pretty?</strong></p>\n<p>The global view is mostly pretty. The local graph is genuinely useful as a\nfive-second quality check on any page. See <a href=\"../05-graphs/obsidian-graph-view.md\">reading the graph\nview</a>.</p>\n<p><strong>How long before it is worth it?</strong></p>\n<p>Weeks two to four for the first real payoff, month six for the state people\ndescribe as the whole point.</p>\n<hr />\n<p>Something missing here? Open an issue.</p>", "headings": [], "words": 438, "text": "Do I need MCP? No. Claude Code started inside the vault folder reads and writes it directly. MCP adds the ability to reach the vault from sessions not running in it, which matters mainly for scheduled tasks. See MCP for Obsidian ../02-setup/mcp-obsidian.md . Does this work with agents other than Claude Code? Yes. The vault is markdown and the skills are SKILL.md files, a format several agents read. Anything that can read and write files in a folder can maintain the vault; the instructions in CLAUDE.md may need renaming for other tools. How much does it cost to run? Depends entirely on volume. A daily ingest of a handful of articles is small. A one-time backfill of a thousand sources is not, which is why the backfill ../03-ingestion/bulk-backfill.md page insists on batches with visible costs. Can I use a local model? For ingestion of sensitive material, yes, with lower quality. Local models are weaker at the judgement calls that matter here: what deserves its own page, when two sources genuinely disagree. A workable split is a local model for private material and a frontier model for everything else. Do I need Obsidian? No. The vault is a folder of markdown files. Obsidian is a good viewer for the graph and has the Web Clipper, which is the strongest practical reason to use it. Logseq, Foam, or a plain editor all work. What if I already have a Notion or Evernote full of notes? Use the official Importer https://github.com/obsidianmd/obsidian-importer plugin, which handles Notion, Evernote, Roam, Bear and Apple Notes. Then treat the result as raw material: backfill oldest first. Expect the export to be messy. Fix extraction before ingesting rather than hoping the agent copes. How is this different from a memory feature? Memory features remember facts about you across sessions and belong to the tool. This is a body of knowledge you own as files, that outlives the tool, and that you can read, edit and publish yourself. Will the agent make things up? It can, which is why every rule in structuring ../04-structuring/README.md is about attribution: claims recorded as claims, sources attached, gaps stated rather than filled. A page with no source behind a specific number is the thing to watch for. Is the graph view actually useful or is it just pretty? The global view is mostly pretty. The local graph is genuinely useful as a five-second quality check on any page. See reading the graph view ../05-graphs/obsidian-graph-view.md . How long before it is worth it? Weeks two to four for the first real payoff, month six for the state people describe as the whole point. --- Something missing here? Open an issue.", "links": [{"to": "02-setup/mcp-obsidian", "label": "MCP for\nObsidian"}, {"to": "03-ingestion/bulk-backfill", "label": "backfill"}, {"to": "05-graphs/obsidian-graph-view", "label": "reading the graph\nview"}]}], "sections": {"01-concepts": {"title": "Concepts", "blurb": "Why an LLM-maintained knowledge base beats the note system you abandoned, and what the pattern actually is."}, "02-setup": {"title": "Setup", "blurb": "From zero to a vault your agent maintains, in one evening. Follow the pages in order the first time. Nine steps, roughly twenty minutes of typing and however long the interview in step four takes you."}, "03-ingestion": {"title": "Ingestion", "blurb": "Getting everything you read, watch and write into `raw/` with as little friction as possible, then into the wiki without flooding it."}, "04-structuring": {"title": "Structuring", "blurb": "The rules that decide whether your vault becomes a graph or a landfill."}, "05-graphs": {"title": "Graphs", "blurb": "The part most second-brain guides skip. They tell you to open the graph view, say it looks like a brain, and move on."}, "06-agents": {"title": "Agents", "blurb": "Turning a one-off setup into a system that maintains itself."}, "07-retrieval": {"title": "Retrieval", "blurb": "How to actually ask your vault things and get answers worth trusting."}, "08-outputs": {"title": "Outputs", "blurb": "The vault earns its keep when things come out of it."}, "09-maintenance": {"title": "Maintenance", "blurb": "What keeps the thing alive after the novelty wears off."}, "10-troubleshooting": {"title": "Troubleshooting", "blurb": "Concrete failures, with fixes."}}, "order": {"01-concepts": ["01-concepts/what-is-a-second-brain", "01-concepts/the-save-for-later-paradox", "01-concepts/llm-wiki-pattern", "01-concepts/two-layers", "01-concepts/why-markdown-and-plain-text", "01-concepts/pkm-lineage", "01-concepts/wiki-vs-rag", "01-concepts/what-good-looks-like"], "02-setup": ["02-setup/obsidian-install-and-vault", "02-setup/claude-code-setup", "02-setup/mcp-obsidian", "02-setup/claude-md", "02-setup/vault-structure", "02-setup/project-scoping", "02-setup/live-data", "02-setup/obsidian-plugins", "02-setup/git-and-sync"], "03-ingestion": ["03-ingestion/web-clipper", "03-ingestion/youtube-transcripts", "03-ingestion/pdfs-and-books", "03-ingestion/chat-exports", "03-ingestion/voice-and-meetings", "03-ingestion/newsletters-and-email", "03-ingestion/bulk-backfill"], "04-structuring": ["04-structuring/atomic-pages", "04-structuring/page-types", "04-structuring/linking-rules", "04-structuring/frontmatter-schema", "04-structuring/naming-and-aliases", "04-structuring/dedupe-and-merge", "04-structuring/contradictions-and-supersession", "04-structuring/index-and-log"], "05-graphs": ["05-graphs/graph-basics", "05-graphs/obsidian-graph-view", "05-graphs/typed-links", "05-graphs/graph-vs-vectors", "05-graphs/graphrag", "05-graphs/exporting-your-graph", "05-graphs/metrics"], "06-agents": ["06-agents/agent-roles", "06-agents/scheduled-maintenance", "06-agents/subagents", "06-agents/hooks", "06-agents/skills-and-commands", "06-agents/safety-and-guardrails"], "07-retrieval": ["07-retrieval/asking-questions", "07-retrieval/query-patterns", "07-retrieval/search-tools", "07-retrieval/rag-on-top", "07-retrieval/context-budget"], "08-outputs": ["08-outputs/writing-from-the-vault", "08-outputs/research-reports", "08-outputs/publishing-and-export", "08-outputs/teaching-yourself"], "09-maintenance": ["09-maintenance/lint-and-health", "09-maintenance/review-cadence", "09-maintenance/versioning-with-git", "09-maintenance/backups-and-portability", "09-maintenance/privacy-and-secrets", "09-maintenance/scaling"], "10-troubleshooting": ["10-troubleshooting/common-failures", "10-troubleshooting/agent-writes-garbage", "10-troubleshooting/broken-links", "10-troubleshooting/vault-too-big", "10-troubleshooting/faq"]}}</script>+<script>+const D=JSON.parse(document.getElementById('data').textContent);+const P={}; D.pages.forEach(p=>P[p.id]=p);+const FLAT=[]; Object.keys(D.order).forEach(s=>D.order[s].forEach(id=>FLAT.push(id)));+const HERO=document.getElementById('hero').innerHTML;++function side(cur){+ const s=document.getElementById('side'); let h='';+ Object.keys(D.order).forEach((sec,i)=>{+ const open = cur && cur.startsWith(sec);+ h+=`<div class="sec ${open?'open':''}" data-sec="${sec}">+ <button aria-expanded="${!!open}"><span class="k">${String(i+1).padStart(2,'0')}</span>+ ${D.sections[sec].title}<span class="n">${D.order[sec].length}</span></button><ol>`;+ D.order[sec].forEach(id=>{+ h+=`<li><a href="#${id}" class="${id===cur?'cur':''}">${P[id].title}</a></li>`;+ });+ h+='</ol></div>';+ });+ s.innerHTML=h;+ s.querySelectorAll('.sec>button').forEach(b=>b.onclick=()=>{+ const d=b.parentElement; d.classList.toggle('open');+ b.setAttribute('aria-expanded', d.classList.contains('open'));+ });+}++function render(){+ const id=decodeURIComponent(location.hash.slice(1));+ const main=document.getElementById('main'), rail=document.getElementById('rail');+ if(!P[id]){+ main.innerHTML=HERO; rail.innerHTML=''; side(null);+ main.querySelectorAll('svg .node').forEach(n=>n.onclick=()=>{+ location.hash=D.order[n.dataset.sec][0];+ });+ document.title='Second Brain OS - the guide';+ window.scrollTo(0,0); return;+ }+ const p=P[id], i=FLAT.indexOf(id), prev=FLAT[i-1], next=FLAT[i+1];+ main.innerHTML=`<article class="page">+ <div class="crumb">${p.section_title} / page ${D.order[p.section].indexOf(id)+1} of ${D.order[p.section].length}</div>+ <h1>${p.title}</h1>${p.html}+ <div class="pager">+ ${prev?`<a href="#${prev}"><span class="lbl">previous</span>${P[prev].title}</a>`:'<span></span>'}+ ${next?`<a href="#${next}" style="text-align:right"><span class="lbl">next</span>${P[next].title}</a>`:'<span></span>'}+ </div>+ <div class="src">source: <a href="https://github.com/undefined-ui/second-brain-os/blob/main/${p.path}">${p.path}</a></div>+ </article>`;+ // rewrite internal links to hash routes, style them as wikilinks+ main.querySelectorAll('a[href$=".md"]').forEach(a=>{+ if(/^https?:/.test(a.getAttribute('href'))) return;+ const parts=a.getAttribute('href').replace(/^\.\//,'').split('/');+ let target=null;+ const file=parts[parts.length-1].replace('.md','');+ if(file==='README'){+ const sec=parts[parts.length-2]; if(D.order[sec]) target=D.order[sec][0];+ } else {+ const sec = parts.length>1 ? parts[parts.length-2] : p.section;+ const cand = sec+'/'+file;+ target = P[cand] ? cand : (P[p.section+'/'+file] ? p.section+'/'+file : null);+ }+ if(target){ a.setAttribute('href','#'+target); a.className='wiki'; }+ else if(a.getAttribute('href').indexOf('..')===0 || !/^https?:/.test(a.getAttribute('href'))){+ a.setAttribute('href','https://github.com/undefined-ui/second-brain-os/blob/main/'+a.getAttribute('href').replace(/^(\.\.\/)+/,''));+ }+ });+ const heads=[...main.querySelectorAll('h2')];+ const outs=[...main.querySelectorAll('a.wiki')].slice(0,8);+ rail.innerHTML=(heads.length?`<div class="grp"><h4>on this page</h4>`++ heads.map((h,n)=>{h.id='h'+n;return `<a href="#${id}" onclick="document.getElementById('h${n}').scrollIntoView();return false">${h.textContent}</a>`}).join('')+`</div>`:'')+ +(outs.length?`<div class="grp"><h4>links out</h4>`++ outs.map(a=>`<a href="${a.getAttribute('href')}">${a.textContent}</a>`).join('')+`</div>`:'');+ side(id); document.title=p.title+' - Second Brain OS'; window.scrollTo(0,0);+}++// search+const q=document.getElementById('q'), hits=document.getElementById('hits');+q.addEventListener('input',()=>{+ const v=q.value.trim().toLowerCase();+ if(v.length<2){hits.classList.remove('open');return;}+ const r=D.pages.map(p=>{+ let sc=0; const t=p.title.toLowerCase();+ if(t.includes(v)) sc+=10; if(t.startsWith(v)) sc+=6;+ const n=(p.text.toLowerCase().split(v).length-1); sc+=Math.min(n,6);+ return {p,sc};+ }).filter(x=>x.sc>0).sort((a,b)=>b.sc-a.sc).slice(0,9);+ hits.innerHTML=r.length?r.map(x=>`<a class="hit" href="#${x.p.id}"><b>${x.p.title}</b><i>${x.p.section_title}</i></a>`).join('')+ :'<div class="hit"><i>nothing in the guide matches that</i></div>';+ hits.classList.add('open');+});+q.addEventListener('keydown',e=>{if(e.key==='Escape'){q.value='';hits.classList.remove('open');q.blur();}});+document.addEventListener('click',e=>{if(!e.target.closest('.search'))hits.classList.remove('open');});+document.addEventListener('keydown',e=>{+ if(e.key==='/'&&document.activeElement!==q){e.preventDefault();q.focus();}+ if(!P[decodeURIComponent(location.hash.slice(1))])return;+ const i=FLAT.indexOf(decodeURIComponent(location.hash.slice(1)));+ if(e.key==='ArrowRight'&&FLAT[i+1])location.hash=FLAT[i+1];+ if(e.key==='ArrowLeft'&&FLAT[i-1])location.hash=FLAT[i-1];+});+hits.addEventListener('click',()=>{hits.classList.remove('open');q.value='';});+const toc=document.getElementById('toc');+if(toc){toc.onclick=()=>document.getElementById('side').classList.toggle('show');}+document.getElementById('side').addEventListener('click',e=>{+ if(e.target.tagName==='A'&&innerWidth<=860) document.getElementById('side').classList.remove('show');+});+addEventListener('hashchange',render); render();+</script></body></html>\ No newline at end of filediff --git a/resources.html b/resources.htmlnew file mode 100644index 0000000..df2a803--- /dev/null+++ b/resources.html@@ -0,0 +1,215 @@+<!DOCTYPE html><html lang="en"><head>+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">+<title>Second Brain OS - resources</title>+<meta name="description" content="86 checked links: Obsidian plugins by installs, repositories by stars, papers, tools and reading.">+<style>+:root{+ --paper:#EAEEE9; --card:#F7F9F6; --ink:#15201B; --soft:#4B5A52; --faint:#7C8A82;+ --rule:#D2DACF; --accent:#1F6B52; --accent-bg:#E1EDE5; --num:#8A6B23;+ --w:68ch;+}+*{box-sizing:border-box;margin:0;padding:0}+html{scroll-behavior:smooth}+body{background:var(--paper);color:var(--ink);+ font:17px/1.62 Charter,Georgia,"Iowan Old Style",serif;+ -webkit-font-smoothing:antialiased}+.mono{font-family:ui-monospace,SFMono-Regular,Menlo,"DejaVu Sans Mono",monospace}+a{color:var(--accent);text-decoration:none}+a:hover{text-decoration:underline;text-underline-offset:3px}+:focus-visible{outline:2px solid var(--accent);outline-offset:3px;border-radius:2px}++header{position:sticky;top:0;z-index:40;background:rgba(234,238,233,.94);+ backdrop-filter:blur(8px);border-bottom:1px solid var(--rule)}+.bar{max-width:1500px;margin:0 auto;padding:13px 22px;display:flex;gap:20px;align-items:center}+.brand{font:600 15px/1 ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--ink);letter-spacing:-.01em}+.brand span{color:var(--accent)}+nav{display:flex;gap:18px;font-size:14.5px}+nav a{color:var(--soft)} nav a.on{color:var(--ink);font-weight:600}+.search{margin-left:auto;position:relative}+.search input{font:14px/1 ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--ink);+ background:var(--card);border:1px solid var(--rule);border-radius:3px;+ padding:8px 11px;width:210px}+.search input::placeholder{color:var(--faint)}+.hits{position:absolute;right:0;top:40px;width:430px;max-height:62vh;overflow:auto;+ background:var(--card);border:1px solid var(--rule);border-radius:3px;display:none}+.hits.open{display:block}+.hit{display:block;padding:10px 13px;border-bottom:1px solid var(--rule);color:var(--ink)}+.hit:last-child{border:0}+.hit:hover{background:var(--accent-bg);text-decoration:none}+.hit b{font-weight:600;font-size:15px}+.hit i{display:block;font-style:normal;font-size:12.5px;color:var(--faint);+ font-family:ui-monospace,Menlo,monospace;margin-top:2px}++.wrap{max-width:1500px;margin:0 auto;padding:0 22px;display:grid;+ grid-template-columns:266px minmax(0,1fr) 210px;gap:44px;align-items:start}+@media(max-width:1180px){.wrap{grid-template-columns:240px minmax(0,1fr);gap:34px}.rail{display:none}}+.toc-btn{display:none;font:13px/1 ui-monospace,Menlo,monospace;background:var(--card);+ color:var(--ink);border:1px solid var(--rule);border-radius:3px;padding:8px 12px;cursor:pointer}+@media(max-width:860px){+ .bar{flex-wrap:wrap;gap:12px;padding:11px 16px}+ .brand{white-space:nowrap;font-size:14px}+ nav{gap:14px;font-size:14px}+ .toc-btn{display:block;margin-left:auto}+ nav a[href^="http"]{display:none}+ .search{margin-left:0;order:9;width:100%}+ .search input{width:100%}+ .hits{width:100%;left:0;right:auto}+ .wrap{grid-template-columns:1fr;gap:0;padding:0 16px}+ aside{position:static;height:auto;border-right:0;border-bottom:1px solid var(--rule);+ padding:14px 0 18px;display:none}+ aside.show{display:block}+ main{padding:24px 0 70px}+ body{font-size:16.5px}+}++aside{position:sticky;top:57px;height:calc(100vh - 57px);overflow:auto;+ padding:26px 18px 60px 0;border-right:1px solid var(--rule)}+.sec{margin-bottom:3px}+.sec>button{width:100%;text-align:left;background:none;border:0;cursor:pointer;+ font:600 14px/1.4 Charter,Georgia,serif;color:var(--ink);padding:6px 6px 6px 0;+ display:flex;gap:8px;align-items:baseline}+.sec>button .n{font:11px/1 ui-monospace,Menlo,monospace;color:var(--faint);margin-left:auto}+.sec>button .k{font:11px/1 ui-monospace,Menlo,monospace;color:var(--accent);width:20px}+.sec ol{list-style:none;padding:0 0 6px 28px;display:none}+.sec.open ol{display:block}+.sec ol a{display:block;padding:4px 6px 4px 10px;font-size:14px;color:var(--soft);+ border-left:1px solid var(--rule);line-height:1.35}+.sec ol a:hover{color:var(--ink);border-color:var(--accent);text-decoration:none}+.sec ol a.cur{color:var(--ink);font-weight:600;border-left:2px solid var(--accent);+ background:var(--accent-bg)}++main{padding:34px 0 90px;min-width:0}+.rail{position:sticky;top:80px;padding:38px 0;font-size:13px;color:var(--faint)}+.rail h4{font:11px/1 ui-monospace,Menlo,monospace;color:var(--faint);+ letter-spacing:.08em;margin-bottom:9px;font-weight:600}+.rail a{display:block;color:var(--soft);padding:3px 0;font-size:13px;line-height:1.35}+.rail .grp{margin-bottom:24px}++/* hero */+.hero{max-width:var(--w)}+.hero h1{font:600 clamp(34px,4.6vw,52px)/1.05 Charter,Georgia,serif;letter-spacing:-.025em;margin-bottom:14px}+.hero p{font-size:19px;color:var(--soft);margin-bottom:8px}+.figure{margin:30px 0 34px;background:var(--card);border:1px solid var(--rule);border-radius:4px;+ padding:10px 10px 4px;max-width:820px}+.figure figcaption{font:11.5px/1.5 ui-monospace,Menlo,monospace;color:var(--faint);padding:6px 8px 8px}+svg .edge{stroke:var(--accent);fill:none}+svg .node circle{fill:var(--card);stroke:var(--accent);stroke-width:1.5;cursor:pointer;+ transition:fill .15s}+svg .node:hover circle{fill:var(--accent-bg)}+svg .node text{font:12px ui-monospace,Menlo,monospace;fill:var(--ink);cursor:pointer}+svg .node .cnt{font-size:10px;fill:var(--faint)}+svg .node .idx{font-size:11px;fill:var(--accent);font-weight:600}+.stats{display:flex;flex-wrap:wrap;gap:26px;margin:26px 0 34px;padding-top:20px;border-top:1px solid var(--rule)}+.stat b{display:block;font:600 27px/1 Charter,Georgia,serif;color:var(--num)}+.stat span{font:12px/1.4 ui-monospace,Menlo,monospace;color:var(--faint)}+.seclist{max-width:var(--w)}+.seclist article{padding:16px 0;border-top:1px solid var(--rule)}+.seclist h3{font:600 18px/1.3 Charter,Georgia,serif;margin-bottom:3px}+.seclist p{font-size:15px;color:var(--soft)}+.seclist .pg{font:12px ui-monospace,Menlo,monospace;color:var(--faint);margin-top:5px}++/* article */+article.page{max-width:var(--w)}+.crumb{font:12px ui-monospace,Menlo,monospace;color:var(--faint);margin-bottom:10px}+article.page h1{font:600 clamp(28px,3.4vw,38px)/1.12 Charter,Georgia,serif;+ letter-spacing:-.02em;margin-bottom:22px}+article.page h2{font:600 21px/1.3 Charter,Georgia,serif;margin:34px 0 11px;+ padding-top:16px;border-top:1px solid var(--rule)}+article.page h3{font:600 17px/1.3 Charter,Georgia,serif;margin:22px 0 7px}+article.page p{margin-bottom:15px}+article.page ul,article.page ol{margin:0 0 16px 22px}+article.page li{margin-bottom:7px}+article.page blockquote{border-left:2px solid var(--accent);padding-left:16px;+ color:var(--soft);margin-bottom:16px}+article.page code{font-family:ui-monospace,Menlo,monospace;font-size:.86em;+ background:var(--card);border:1px solid var(--rule);border-radius:3px;padding:1px 5px}+article.page pre{background:var(--card);border:1px solid var(--rule);border-radius:4px;+ padding:14px 16px;overflow:auto;margin-bottom:17px}+article.page pre code{background:none;border:0;padding:0;font-size:13.5px;line-height:1.55}+article.page table{width:100%;border-collapse:collapse;margin-bottom:18px;font-size:14.5px}+article.page th{text-align:left;font-weight:600;padding:7px 10px 7px 0;+ border-bottom:1px solid var(--ink)}+article.page td{padding:8px 10px 8px 0;border-bottom:1px solid var(--rule);vertical-align:top}+article.page a.wiki{color:var(--accent);white-space:normal}+article.page a.wiki::before{content:"[[";color:var(--faint)}+article.page a.wiki::after{content:"]]";color:var(--faint)}+.pager{display:flex;gap:16px;justify-content:space-between;margin-top:46px;+ padding-top:18px;border-top:1px solid var(--rule);font-size:14px}+.pager a{max-width:46%}+.pager .lbl{display:block;font:11px ui-monospace,Menlo,monospace;color:var(--faint)}+.src{margin-top:34px;font:12px ui-monospace,Menlo,monospace;color:var(--faint)}++/* resources */+.rwrap{max-width:1180px;margin:0 auto;padding:34px 22px 90px}+.rwrap h1{font:600 clamp(30px,4vw,44px)/1.08 Charter,Georgia,serif;letter-spacing:-.025em}+.lede{max-width:62ch;color:var(--soft);margin:12px 0 24px;font-size:17px}+.controls{display:flex;flex-wrap:wrap;gap:9px;align-items:center;margin-bottom:8px;+ padding-bottom:18px;border-bottom:1px solid var(--rule)}+.chip{font:13px/1 ui-monospace,Menlo,monospace;background:var(--card);color:var(--soft);+ border:1px solid var(--rule);border-radius:20px;padding:7px 13px;cursor:pointer}+.chip.on{background:var(--accent);border-color:var(--accent);color:#F7F9F6}+.controls input{margin-left:auto;font:14px ui-monospace,Menlo,monospace;+ background:var(--card);border:1px solid var(--rule);border-radius:3px;padding:8px 11px;width:230px}+.count{font:12px ui-monospace,Menlo,monospace;color:var(--faint);padding:14px 0 4px}+.grp-h{font:600 15px/1 ui-monospace,Menlo,monospace;color:var(--faint);+ margin:26px 0 6px;padding-top:14px;border-top:1px solid var(--rule)}+.row{display:grid;grid-template-columns:minmax(180px,260px) 120px 1fr;gap:18px;+ padding:12px 0;border-bottom:1px solid var(--rule);align-items:baseline}+@media(max-width:760px){.row{grid-template-columns:1fr;gap:3px}}+.row .nm{font-weight:600;font-size:16px}+.row .mt{font:13px ui-monospace,Menlo,monospace;color:var(--num)}+.row .ds{color:var(--soft);font-size:15px}+.row .kd{font:11px ui-monospace,Menlo,monospace;color:var(--faint);display:block;margin-top:2px}+footer{border-top:1px solid var(--rule);padding:22px;text-align:center;+ font:12px ui-monospace,Menlo,monospace;color:var(--faint)}+@media(prefers-reduced-motion:reduce){*{transition:none!important;animation:none!important}}+</style></head><body>+<header><div class="bar">+ <a class="brand" href="index.html">[[ second<span>brain</span>os ]]</a>+ <nav>+ <a href="index.html" class="">Guide</a>+ <a href="resources.html" class="on">Resources</a>+ <a href="https://github.com/undefined-ui/second-brain-os">Repo</a>+ </nav>+++</div></header>+<div class="rwrap">+ <h1>Everything worth opening</h1>+ <p class="lede">86 links, each one checked. Plugins are ranked by installs from Obsidian's own community stats rather than by stars, because in this ecosystem the two disagree by an order of magnitude. Figures are from September 2026 and will drift.</p>+ <div class="controls" id="ctl">+ <button class="chip on" data-k="all">All</button>+ <button class="chip" data-k="Obsidian plugin">Obsidian plugin</button><button class="chip" data-k="Repository">Repository</button><button class="chip" data-k="Skills">Skills</button><button class="chip" data-k="Tool">Tool</button><button class="chip" data-k="Reading">Reading</button><button class="chip" data-k="Paper">Paper</button>+ <input id="rq" type="search" placeholder="filter" autocomplete="off">+ </div>+ <div class="count" id="count"></div>+ <div id="rows"></div>+</div>+<footer>Generated from the repository. <a href="https://github.com/undefined-ui/second-brain-os">github.com/undefined-ui/second-brain-os</a></footer>+<script id="rdata" type="application/json">[{"file": "plugins.md", "kind": "Obsidian plugin", "group": "Agents inside Obsidian", "name": "Claudian", "url": "https://github.com/yishentu/claudian", "metric": "2,035,966", "desc": "Embeds Claude Code, Codex and other local agents as collaborators in the vault"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Agents inside Obsidian", "name": "Copilot", "url": "https://github.com/logancyang/obsidian-copilot", "metric": "1,832,464", "desc": "Runs Claude Code, Codex and OpenCode inside your vault"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Agents inside Obsidian", "name": "Smart Connections", "url": "https://github.com/brianpetro/obsidian-smart-connections", "metric": "1,189,513", "desc": "Local embedding model surfaces related notes while you write. No API key"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Agents inside Obsidian", "name": "Local REST API with MCP", "url": "https://github.com/coddingtonbear/obsidian-local-rest-api", "metric": "712,443", "desc": "Vault over a secure local API, now with a built-in MCP server"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Agents inside Obsidian", "name": "Agent Client", "url": "https://github.com/rait-09/obsidian-agent-client", "metric": "261,371", "desc": "Chat with Claude Code, Codex and Gemini CLI over the Agent Client Protocol"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Agents inside Obsidian", "name": "Smart Composer", "url": "https://github.com/glowingjade/obsidian-smart-composer", "metric": "171,863", "desc": "AI chat with note context and one-click edits"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Structure and queries", "name": "Templater", "url": "https://github.com/SilentVoid13/Templater", "metric": "5,527,936", "desc": "Dynamic templates. For the pages you write by hand"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Structure and queries", "name": "Dataview", "url": "https://github.com/blacksmithgu/obsidian-dataview", "metric": "4,918,446", "desc": "Query language over your frontmatter. Answers \"which pages have property P\""}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Structure and queries", "name": "Metadata Menu", "url": "https://github.com/mdelobelle/metadatamenu", "metric": "330,430", "desc": "Manage frontmatter fields at scale. Useful once your schema is fixed"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Structure and queries", "name": "Supercharged Links", "url": "https://github.com/mdelobelle/obsidian_supercharged_links", "metric": "210,926", "desc": "Styles links by the target note's frontmatter, so page type is visible inline"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Graph", "name": "ExcaliBrain", "url": "https://github.com/zsviczian/excalibrain", "metric": "336,025", "desc": "Structured mind-map deriving five relationship types from links, Dataview fields and tags"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Graph", "name": "Juggl", "url": "https://github.com/HEmile/juggl", "metric": "135,614", "desc": "Interactive Cytoscape.js graph with typed edges and a saveable workspace mode"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Graph", "name": "Graph Analysis", "url": "https://github.com/SkepticMystic/graph-analysis", "metric": "community plugin", "desc": "Graph algorithms and similarity measures over the vault, surfaces unlinked connections"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Graph", "name": "Breadcrumbs", "url": "https://github.com/michaelpporter/breadcrumbs", "metric": "community plugin", "desc": "Typed links plus trees, matrices, Mermaid and Canvas export"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Graph", "name": "3D Graph", "url": "https://github.com/AlexW00/obsidian-3d-graph", "metric": "community plugin", "desc": "The vault as a 3D force graph. Shows cluster structure a 2D hairball hides"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Maintenance", "name": "Git", "url": "https://github.com/Vinzent03/obsidian-git", "metric": "3,110,571", "desc": "Commit and sync the vault from inside Obsidian. See versioning"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Maintenance", "name": "Omnisearch", "url": "https://github.com/scambier/obsidian-omnisearch", "metric": "1,837,484", "desc": "Better full-text search, including inside PDFs"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Maintenance", "name": "Importer", "url": "https://github.com/obsidianmd/obsidian-importer", "metric": "1,638,001", "desc": "Official importer from Notion, Evernote, Roam, Bear, Apple Notes. The first step for anyone backfilling"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Maintenance", "name": "Linter", "url": "https://github.com/platers/obsidian-linter", "metric": "1,044,521", "desc": "Formats notes to consistent rules. Set it carefully, it rewrites files"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Maintenance", "name": "Find orphaned files and broken links", "url": "https://github.com/Vinzent03/find-unlinked-files", "metric": "224,687", "desc": "Exactly what lint checks, without leaving Obsidian"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Capture and study", "name": "Excalidraw", "url": "https://github.com/zsviczian/obsidian-excalidraw-plugin", "metric": "7,795,993", "desc": "The most installed plugin in the catalog. Diagrams that live in the vault as files"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Capture and study", "name": "QuickAdd", "url": "https://github.com/chhoumann/quickadd", "metric": "2,082,182", "desc": "One-keystroke capture into a chosen folder and template"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Capture and study", "name": "Spaced Repetition", "url": "https://github.com/st3v3nmw/obsidian-spaced-repetition", "metric": "592,497", "desc": "Flashcards from your own notes. See learning from your vault"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Capture and study", "name": "Zotero Integration", "url": "https://github.com/obsidian-community/obsidian-zotero-integration", "metric": "550,881", "desc": "Citations, bibliographies and PDF annotations from Zotero"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Capture and study", "name": "ReadItLater", "url": "https://github.com/DominikPieper/obsidian-ReadItLater", "metric": "134,982", "desc": "Saves online content into the vault with a template"}, {"file": "plugins.md", "kind": "Obsidian plugin", "group": "Capture and study", "name": "Webpage HTML Export", "url": "https://github.com/KosmosisDire/obsidian-webpage-export", "metric": "152,194", "desc": "Export notes, canvases or the whole vault as HTML"}, {"file": "repositories.md", "kind": "Repository", "group": "GraphRAG and graph retrieval", "name": "HKUDS/LightRAG", "url": "https://github.com/HKUDS/LightRAG", "metric": "39,467", "desc": "Dual-layer graph plus vectors, aimed at cheap incremental updates. EMNLP 2025"}, {"file": "repositories.md", "kind": "Repository", "group": "GraphRAG and graph retrieval", "name": "microsoft/graphrag", "url": "https://github.com/microsoft/graphrag", "metric": "35,875", "desc": "The reference implementation of the paper"}, {"file": "repositories.md", "kind": "Repository", "group": "GraphRAG and graph retrieval", "name": "gusye1234/nano-graphrag", "url": "https://github.com/gusye1234/nano-graphrag", "metric": "3,983", "desc": "The same idea in about 1,100 readable lines. Open this one to understand the pipeline"}, {"file": "repositories.md", "kind": "Repository", "group": "GraphRAG and graph retrieval", "name": "OSU-NLP-Group/HippoRAG", "url": "https://github.com/OSU-NLP-Group/HippoRAG", "metric": "3,985", "desc": "The NeurIPS'24 paper's implementation. Personalised PageRank over a knowledge graph"}, {"file": "repositories.md", "kind": "Repository", "group": "GraphRAG and graph retrieval", "name": "DEEP-PolyU/Awesome-GraphRAG", "url": "https://github.com/DEEP-PolyU/Awesome-GraphRAG", "metric": "2,635", "desc": "Curated map of surveys, benchmarks and projects in the area"}, {"file": "repositories.md", "kind": "Repository", "group": "Agent memory", "name": "mem0ai/mem0", "url": "https://github.com/mem0ai/mem0", "metric": "64,863", "desc": "Drop-in memory layer for agents and apps"}, {"file": "repositories.md", "kind": "Repository", "group": "Agent memory", "name": "getzep/graphiti", "url": "https://github.com/getzep/graphiti", "metric": "30,680", "desc": "Real-time temporal knowledge graphs for agents"}, {"file": "repositories.md", "kind": "Repository", "group": "Agent memory", "name": "topoteretes/cognee", "url": "https://github.com/topoteretes/cognee", "metric": "30,568", "desc": "Turns data into knowledge graphs, combining graph and vector retrieval"}, {"file": "repositories.md", "kind": "Repository", "group": "Agent memory", "name": "doobidoo/mcp-memory-service", "url": "https://github.com/doobidoo/mcp-memory-service", "metric": "1,928", "desc": "Persistent memory over MCP, REST API plus knowledge graph"}, {"file": "repositories.md", "kind": "Repository", "group": "RAG frameworks", "name": "infiniflow/ragflow", "url": "https://github.com/infiniflow/ragflow", "metric": "90,216", "desc": "Full RAG engine with document understanding"}, {"file": "repositories.md", "kind": "Repository", "group": "RAG frameworks", "name": "run-llama/llama_index", "url": "https://github.com/run-llama/llama_index", "metric": "52,058", "desc": "Document agent and ingestion framework"}, {"file": "repositories.md", "kind": "Repository", "group": "RAG frameworks", "name": "neuml/txtai", "url": "https://github.com/neuml/txtai", "metric": "12,931", "desc": "Embeddings database and LLM workflows, small enough to read"}, {"file": "repositories.md", "kind": "Repository", "group": "MCP", "name": "punkpeye/awesome-mcp-servers", "url": "https://github.com/punkpeye/awesome-mcp-servers", "metric": "94,575", "desc": "The index of MCP servers"}, {"file": "repositories.md", "kind": "Repository", "group": "MCP", "name": "modelcontextprotocol/servers", "url": "https://github.com/modelcontextprotocol/servers", "metric": "90,141", "desc": "The official reference servers, including filesystem and memory"}, {"file": "repositories.md", "kind": "Repository", "group": "MCP", "name": "MarkusPfundstein/mcp-obsidian", "url": "https://github.com/MarkusPfundstein/mcp-obsidian", "metric": "4,376", "desc": "Third-party MCP server for Obsidian over the REST plugin"}, {"file": "skills.md", "kind": "Skills", "group": "Implementations of this pattern", "name": "AgriciDaniel/claude-obsidian", "url": "https://github.com/AgriciDaniel/claude-obsidian", "metric": "14,706", "desc": "16 skills, 3 subagents. Self-organizing vault with role presets"}, {"file": "skills.md", "kind": "Skills", "group": "Implementations of this pattern", "name": "Astro-Han/karpathy-llm-wiki", "url": "https://github.com/Astro-Han/karpathy-llm-wiki", "metric": "2,174", "desc": "1 skill covering the full ingest, compile, query, lint loop"}, {"file": "skills.md", "kind": "Skills", "group": "Implementations of this pattern", "name": "ballred/obsidian-claude-pkm", "url": "https://github.com/ballred/obsidian-claude-pkm", "metric": "1,856", "desc": "13 skills, 4 subagents. A complete starter kit"}, {"file": "skills.md", "kind": "Skills", "group": "Implementations of this pattern", "name": "coleam00/second-brain-starter", "url": "https://github.com/coleam00/second-brain-starter", "metric": "768", "desc": "1 skill that interviews you and generates a build plan"}, {"file": "skills.md", "kind": "Skills", "group": "Implementations of this pattern", "name": "NicholasSpisak/second-brain", "url": "https://github.com/NicholasSpisak/second-brain", "metric": "704", "desc": "4 skills, npm installer, close to the original gist"}, {"file": "skills.md", "kind": "Skills", "group": "Implementations of this pattern", "name": "eugeniughelbur/obsidian-second-brain", "url": "https://github.com/eugeniughelbur/obsidian-second-brain", "metric": "small", "desc": "47 commands across Claude, Codex and Gemini"}, {"file": "skills.md", "kind": "Skills", "group": "Implementations of this pattern", "name": "micuintus/llm-wiki", "url": "https://github.com/micuintus/llm-wiki", "metric": "small", "desc": "1 skill, deliberately minimal, no dependencies. Good counterpoint"}, {"file": "skills.md", "kind": "Skills", "group": "General skill libraries", "name": "obra/superpowers", "url": "https://github.com/obra/superpowers", "metric": "282,827", "desc": "14 skills. An agentic skills framework and development methodology"}, {"file": "skills.md", "kind": "Skills", "group": "General skill libraries", "name": "anthropics/skills", "url": "https://github.com/anthropics/skills", "metric": "175,035", "desc": "20 skills, 3 subagents. The official reference for the format"}, {"file": "skills.md", "kind": "Skills", "group": "General skill libraries", "name": "VoltAgent/awesome-agent-skills", "url": "https://github.com/VoltAgent/awesome-agent-skills", "metric": "33,894", "desc": "A curated index of 1,000+ community skills"}, {"file": "skills.md", "kind": "Skills", "group": "General skill libraries", "name": "hesreallyhim/awesome-claude-code", "url": "https://github.com/hesreallyhim/awesome-claude-code", "metric": "53,661", "desc": "Commands, hooks, workflows and tooling for Claude Code"}, {"file": "skills.md", "kind": "Skills", "group": "Graph builders", "name": "Graphify-Labs/graphify", "url": "https://github.com/Graphify-Labs/graphify", "metric": "115,697", "desc": "A `/graphify` skill that turns any folder of code, docs, PDFs and screenshots into a queryable graph. Every edge labelled extracted or inferred"}, {"file": "tools.md", "kind": "Tool", "group": "The core stack", "name": "Obsidian", "url": "https://obsidian.md", "metric": "", "desc": "Local markdown editor. The vault is a plain folder, which is why agents work well with it"}, {"file": "tools.md", "kind": "Tool", "group": "The core stack", "name": "Obsidian Web Clipper", "url": "https://obsidian.md/clipper", "metric": "", "desc": "Official browser extension, saves articles into `raw/`. Uses Mozilla Readability"}, {"file": "tools.md", "kind": "Tool", "group": "The core stack", "name": "Claude Code", "url": "https://code.claude.com/docs/en/setup", "metric": "", "desc": "The agent that maintains the wiki. Paid account required"}, {"file": "tools.md", "kind": "Tool", "group": "Alternative homes for a vault", "name": "AFFiNE", "url": "https://github.com/toeverything/AFFiNE", "metric": "72,292", "desc": "Docs, whiteboard and database in one. Heavier than markdown files"}, {"file": "tools.md", "kind": "Tool", "group": "Alternative homes for a vault", "name": "memos", "url": "https://github.com/usememos/memos", "metric": "62,837", "desc": "Self-hosted quick capture, markdown-native. A good `raw/` inbox"}, {"file": "tools.md", "kind": "Tool", "group": "Alternative homes for a vault", "name": "Joplin", "url": "https://github.com/laurent22/joplin", "metric": "56,264", "desc": "Privacy-focused notes with sync across every platform"}, {"file": "tools.md", "kind": "Tool", "group": "Alternative homes for a vault", "name": "SiYuan", "url": "https://github.com/siyuan-note/siyuan", "metric": "46,225", "desc": "Self-hosted knowledge workspace, block-based"}, {"file": "tools.md", "kind": "Tool", "group": "Alternative homes for a vault", "name": "Logseq", "url": "https://github.com/logseq/logseq", "metric": "44,818", "desc": "Outliner, plain markdown, block-level references"}, {"file": "tools.md", "kind": "Tool", "group": "Alternative homes for a vault", "name": "Outline", "url": "https://github.com/outline/outline", "metric": "40,483", "desc": "Team knowledge base. The right answer when it is not just you"}, {"file": "tools.md", "kind": "Tool", "group": "Alternative homes for a vault", "name": "Trilium", "url": "https://github.com/TriliumNext/Trilium", "metric": "37,762", "desc": "Hierarchical personal knowledge base with scripting"}, {"file": "tools.md", "kind": "Tool", "group": "Alternative homes for a vault", "name": "Foam", "url": "https://github.com/foambubble/foam", "metric": "17,386", "desc": "The same wikilink pattern inside VS Code"}, {"file": "tools.md", "kind": "Tool", "group": "Alternative homes for a vault", "name": "Anytype", "url": "https://github.com/anyproto/anytype-ts", "metric": "8,764", "desc": "Local-first, encrypted, object-based"}, {"file": "tools.md", "kind": "Tool", "group": "Alternative homes for a vault", "name": "Dendron", "url": "https://github.com/dendronhq/dendron", "metric": "7,465", "desc": "Hierarchical PKM in VS Code"}, {"file": "tools.md", "kind": "Tool", "group": "AI-native knowledge apps", "name": "Khoj", "url": "https://github.com/khoj-ai/khoj", "metric": "37,186", "desc": "Self-hostable AI second brain over your docs, with custom agents and scheduled automations"}, {"file": "tools.md", "kind": "Tool", "group": "AI-native knowledge apps", "name": "Quivr", "url": "https://github.com/The-Vibe-Company/quivr", "metric": "39,498", "desc": "Opinionated RAG you embed in your own app"}, {"file": "tools.md", "kind": "Tool", "group": "AI-native knowledge apps", "name": "Reor", "url": "https://github.com/reorproject/reor", "metric": "8,563", "desc": "Local-first AI note app that links notes automatically as you write"}, {"file": "tools.md", "kind": "Tool", "group": "Capture and processing", "name": "yt-dlp", "url": "https://github.com/yt-dlp/yt-dlp", "metric": "", "desc": "Subtitles and audio from video platforms"}, {"file": "tools.md", "kind": "Tool", "group": "Capture and processing", "name": "youtube-transcript-api", "url": "https://github.com/jdepoix/youtube-transcript-api", "metric": "", "desc": "Transcripts from Python"}, {"file": "tools.md", "kind": "Tool", "group": "Capture and processing", "name": "OCRmyPDF", "url": "https://github.com/ocrmypdf/OCRmyPDF", "metric": "", "desc": "Text layer for scanned PDFs"}, {"file": "tools.md", "kind": "Tool", "group": "Capture and processing", "name": "Zotero", "url": "https://github.com/zotero/zotero", "metric": "", "desc": "Reference manager, 15,184 stars, markdown export path"}, {"file": "tools.md", "kind": "Tool", "group": "Capture and processing", "name": "Readwise", "url": "https://readwise.io", "metric": "", "desc": "Kindle and read-later highlights into Obsidian. Paid"}, {"file": "tools.md", "kind": "Tool", "group": "Search and graph", "name": "ripgrep", "url": "https://github.com/BurntSushi/ripgrep", "metric": "", "desc": "Fast enough that most vaults never need an index"}, {"file": "tools.md", "kind": "Tool", "group": "Search and graph", "name": "NetworkX", "url": "https://networkx.org", "metric": "", "desc": "Graph analysis once you have exported an edge list"}, {"file": "tools.md", "kind": "Tool", "group": "Search and graph", "name": "Kuzu", "url": "https://kuzudb.com", "metric": "", "desc": "Embedded graph database, no server"}, {"file": "tools.md", "kind": "Tool", "group": "Search and graph", "name": "Neo4j", "url": "https://neo4j.com", "metric": "", "desc": "Full graph database. Overkill unless you build on top"}, {"file": "tools.md", "kind": "Tool", "group": "Search and graph", "name": "Gephi", "url": "https://gephi.org", "metric": "", "desc": "Visual graph exploration beyond Obsidian's view"}, {"file": "tools.md", "kind": "Tool", "group": "Search and graph", "name": "txtai", "url": "https://github.com/neuml/txtai", "metric": "", "desc": "12,931 stars. Semantic search and LLM workflows, if you decide you need embeddings"}, {"file": "tools.md", "kind": "Tool", "group": "Publishing", "name": "Quartz", "url": "https://github.com/jackyzha0/quartz", "metric": "13,185", "desc": "Vault to static site with backlinks, local graph and search"}, {"file": "reading.md", "kind": "Reading", "group": "The source document", "name": "Karpathy's llm-wiki gist", "url": "https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f", "metric": "", "desc": "The pattern everything in this repo builds on."}, {"file": "reading.md", "kind": "Reading", "group": "The tradition it comes from", "name": "Andy Matuschak's notes", "url": "https://notes.andymatuschak.org", "metric": "", "desc": "The Zettelkasten method. The argument for atomic notes and dense linking still holds; the manual labour it demands is the part that killed it for most people. - Building a Second Brain, Tiago Forte. Where the term comes from, and the PARA m"}, {"file": "papers.md", "kind": "Paper", "group": "GraphRAG", "name": "From Local to Global: A Graph RAG Approach to Query-Focused\nSummarization", "url": "https://arxiv.org/abs/2404.16130", "metric": "", "desc": "Edge, Trinh, Cheng, Bradley, Chao, Mody, Truitt, Metropolitansky, Ness, Larson. Microsoft Research. Implementation at microsoft/graphrag."}, {"file": "papers.md", "kind": "Paper", "group": "HippoRAG", "name": "HippoRAG: Neurobiologically Inspired Long-Term Memory for Large Language\nModels", "url": "https://arxiv.org/abs/2405.14831", "metric": "", "desc": "Guti\u00e9rrez, Shu, Gu, Yasunaga, Su."}, {"file": "papers.md", "kind": "Paper", "group": "Lost in the Middle", "name": "Lost in the Middle: How Language Models Use Long\nContexts", "url": "https://arxiv.org/abs/2307.03172", "metric": "", "desc": "Liu, Lin, Hewitt, Paranjape, Bevilacqua, Petroni, Liang. Published in TACL."}]</script>+<script>+const R=JSON.parse(document.getElementById('rdata').textContent);+let kind='all', term='';+function draw(){+ const f=R.filter(r=>(kind==='all'||r.kind===kind) &&+ (!term || (r.name+' '+r.desc+' '+r.group).toLowerCase().includes(term)));+ document.getElementById('count').textContent=f.length+' of '+R.length+' shown';+ let h='', g=null;+ f.forEach(r=>{+ const key=r.kind+' / '+r.group;+ if(key!==g){g=key; h+=`<div class="grp-h">${r.group||r.kind}</div>`;}+ h+=`<div class="row">+ <div><a class="nm" href="${r.url}">${r.name}</a><span class="kd">${r.kind}</span></div>+ <div class="mt">${r.metric||''}</div>+ <div class="ds">${r.desc||''}</div></div>`;+ });+ document.getElementById('rows').innerHTML=h||'<div class="count">nothing matches that filter</div>';+}+document.getElementById('ctl').addEventListener('click',e=>{+ const b=e.target.closest('.chip'); if(!b)return;+ document.querySelectorAll('.chip').forEach(c=>c.classList.toggle('on',c===b));+ kind=b.dataset.k; draw();+});+document.getElementById('rq').addEventListener('input',e=>{term=e.target.value.trim().toLowerCase();draw();});+draw();+</script></body></html>\ No newline at end of filediff --git a/tools/README.md b/tools/README.mdnew file mode 100644index 0000000..bd924ec--- /dev/null+++ b/tools/README.md@@ -0,0 +1,21 @@+# tools++The site at [undefined-ui.github.io/second-brain-os](https://undefined-ui.github.io/second-brain-os/)+is generated from this repository, so it cannot drift from the guide.++```bash+pip install markdown+python3 tools/extract_site.py # docs and resources -> site_data.json+python3 tools/build_site.py # -> index.html, resources.html+```++`extract_site.py` reads every page in `docs/`, keeps the reading order declared in+each section's `README.md`, resolves internal links to page ids, and parses every+table row in `resources/` that carries a link.++`build_site.py` writes two self-contained HTML files. No build step, no+framework, no external requests at runtime: the content is embedded, so the pages+work offline and from `file://`.++One dependency, `markdown`. The paths at the top of both scripts assume the repo+root.diff --git a/tools/build_site.py b/tools/build_site.pynew file mode 100644index 0000000..583ed0d--- /dev/null+++ b/tools/build_site.py@@ -0,0 +1,430 @@+#!/usr/bin/env python3+"""Builds site/index.html (the guide) and site/resources.html (the catalog)."""+import json, os, html++D = json.load(open("site_data.json"))+OUT = "."+os.makedirs(OUT, exist_ok=True)+REPO = "https://github.com/undefined-ui/second-brain-os"++CSS = """+:root{+ --paper:#EAEEE9; --card:#F7F9F6; --ink:#15201B; --soft:#4B5A52; --faint:#7C8A82;+ --rule:#D2DACF; --accent:#1F6B52; --accent-bg:#E1EDE5; --num:#8A6B23;+ --w:68ch;+}+*{box-sizing:border-box;margin:0;padding:0}+html{scroll-behavior:smooth}+body{background:var(--paper);color:var(--ink);+ font:17px/1.62 Charter,Georgia,"Iowan Old Style",serif;+ -webkit-font-smoothing:antialiased}+.mono{font-family:ui-monospace,SFMono-Regular,Menlo,"DejaVu Sans Mono",monospace}+a{color:var(--accent);text-decoration:none}+a:hover{text-decoration:underline;text-underline-offset:3px}+:focus-visible{outline:2px solid var(--accent);outline-offset:3px;border-radius:2px}++header{position:sticky;top:0;z-index:40;background:rgba(234,238,233,.94);+ backdrop-filter:blur(8px);border-bottom:1px solid var(--rule)}+.bar{max-width:1500px;margin:0 auto;padding:13px 22px;display:flex;gap:20px;align-items:center}+.brand{font:600 15px/1 ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--ink);letter-spacing:-.01em}+.brand span{color:var(--accent)}+nav{display:flex;gap:18px;font-size:14.5px}+nav a{color:var(--soft)} nav a.on{color:var(--ink);font-weight:600}+.search{margin-left:auto;position:relative}+.search input{font:14px/1 ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--ink);+ background:var(--card);border:1px solid var(--rule);border-radius:3px;+ padding:8px 11px;width:210px}+.search input::placeholder{color:var(--faint)}+.hits{position:absolute;right:0;top:40px;width:430px;max-height:62vh;overflow:auto;+ background:var(--card);border:1px solid var(--rule);border-radius:3px;display:none}+.hits.open{display:block}+.hit{display:block;padding:10px 13px;border-bottom:1px solid var(--rule);color:var(--ink)}+.hit:last-child{border:0}+.hit:hover{background:var(--accent-bg);text-decoration:none}+.hit b{font-weight:600;font-size:15px}+.hit i{display:block;font-style:normal;font-size:12.5px;color:var(--faint);+ font-family:ui-monospace,Menlo,monospace;margin-top:2px}++.wrap{max-width:1500px;margin:0 auto;padding:0 22px;display:grid;+ grid-template-columns:266px minmax(0,1fr) 210px;gap:44px;align-items:start}+@media(max-width:1180px){.wrap{grid-template-columns:240px minmax(0,1fr);gap:34px}.rail{display:none}}+.toc-btn{display:none;font:13px/1 ui-monospace,Menlo,monospace;background:var(--card);+ color:var(--ink);border:1px solid var(--rule);border-radius:3px;padding:8px 12px;cursor:pointer}+@media(max-width:860px){+ .bar{flex-wrap:wrap;gap:12px;padding:11px 16px}+ .brand{white-space:nowrap;font-size:14px}+ nav{gap:14px;font-size:14px}+ .toc-btn{display:block;margin-left:auto}+ nav a[href^="http"]{display:none}+ .search{margin-left:0;order:9;width:100%}+ .search input{width:100%}+ .hits{width:100%;left:0;right:auto}+ .wrap{grid-template-columns:1fr;gap:0;padding:0 16px}+ aside{position:static;height:auto;border-right:0;border-bottom:1px solid var(--rule);+ padding:14px 0 18px;display:none}+ aside.show{display:block}+ main{padding:24px 0 70px}+ body{font-size:16.5px}+}++aside{position:sticky;top:57px;height:calc(100vh - 57px);overflow:auto;+ padding:26px 18px 60px 0;border-right:1px solid var(--rule)}+.sec{margin-bottom:3px}+.sec>button{width:100%;text-align:left;background:none;border:0;cursor:pointer;+ font:600 14px/1.4 Charter,Georgia,serif;color:var(--ink);padding:6px 6px 6px 0;+ display:flex;gap:8px;align-items:baseline}+.sec>button .n{font:11px/1 ui-monospace,Menlo,monospace;color:var(--faint);margin-left:auto}+.sec>button .k{font:11px/1 ui-monospace,Menlo,monospace;color:var(--accent);width:20px}+.sec ol{list-style:none;padding:0 0 6px 28px;display:none}+.sec.open ol{display:block}+.sec ol a{display:block;padding:4px 6px 4px 10px;font-size:14px;color:var(--soft);+ border-left:1px solid var(--rule);line-height:1.35}+.sec ol a:hover{color:var(--ink);border-color:var(--accent);text-decoration:none}+.sec ol a.cur{color:var(--ink);font-weight:600;border-left:2px solid var(--accent);+ background:var(--accent-bg)}++main{padding:34px 0 90px;min-width:0}+.rail{position:sticky;top:80px;padding:38px 0;font-size:13px;color:var(--faint)}+.rail h4{font:11px/1 ui-monospace,Menlo,monospace;color:var(--faint);+ letter-spacing:.08em;margin-bottom:9px;font-weight:600}+.rail a{display:block;color:var(--soft);padding:3px 0;font-size:13px;line-height:1.35}+.rail .grp{margin-bottom:24px}++/* hero */+.hero{max-width:var(--w)}+.hero h1{font:600 clamp(34px,4.6vw,52px)/1.05 Charter,Georgia,serif;letter-spacing:-.025em;margin-bottom:14px}+.hero p{font-size:19px;color:var(--soft);margin-bottom:8px}+.figure{margin:30px 0 34px;background:var(--card);border:1px solid var(--rule);border-radius:4px;+ padding:10px 10px 4px;max-width:820px}+.figure figcaption{font:11.5px/1.5 ui-monospace,Menlo,monospace;color:var(--faint);padding:6px 8px 8px}+svg .edge{stroke:var(--accent);fill:none}+svg .node circle{fill:var(--card);stroke:var(--accent);stroke-width:1.5;cursor:pointer;+ transition:fill .15s}+svg .node:hover circle{fill:var(--accent-bg)}+svg .node text{font:12px ui-monospace,Menlo,monospace;fill:var(--ink);cursor:pointer}+svg .node .cnt{font-size:10px;fill:var(--faint)}+svg .node .idx{font-size:11px;fill:var(--accent);font-weight:600}+.stats{display:flex;flex-wrap:wrap;gap:26px;margin:26px 0 34px;padding-top:20px;border-top:1px solid var(--rule)}+.stat b{display:block;font:600 27px/1 Charter,Georgia,serif;color:var(--num)}+.stat span{font:12px/1.4 ui-monospace,Menlo,monospace;color:var(--faint)}+.seclist{max-width:var(--w)}+.seclist article{padding:16px 0;border-top:1px solid var(--rule)}+.seclist h3{font:600 18px/1.3 Charter,Georgia,serif;margin-bottom:3px}+.seclist p{font-size:15px;color:var(--soft)}+.seclist .pg{font:12px ui-monospace,Menlo,monospace;color:var(--faint);margin-top:5px}++/* article */+article.page{max-width:var(--w)}+.crumb{font:12px ui-monospace,Menlo,monospace;color:var(--faint);margin-bottom:10px}+article.page h1{font:600 clamp(28px,3.4vw,38px)/1.12 Charter,Georgia,serif;+ letter-spacing:-.02em;margin-bottom:22px}+article.page h2{font:600 21px/1.3 Charter,Georgia,serif;margin:34px 0 11px;+ padding-top:16px;border-top:1px solid var(--rule)}+article.page h3{font:600 17px/1.3 Charter,Georgia,serif;margin:22px 0 7px}+article.page p{margin-bottom:15px}+article.page ul,article.page ol{margin:0 0 16px 22px}+article.page li{margin-bottom:7px}+article.page blockquote{border-left:2px solid var(--accent);padding-left:16px;+ color:var(--soft);margin-bottom:16px}+article.page code{font-family:ui-monospace,Menlo,monospace;font-size:.86em;+ background:var(--card);border:1px solid var(--rule);border-radius:3px;padding:1px 5px}+article.page pre{background:var(--card);border:1px solid var(--rule);border-radius:4px;+ padding:14px 16px;overflow:auto;margin-bottom:17px}+article.page pre code{background:none;border:0;padding:0;font-size:13.5px;line-height:1.55}+article.page table{width:100%;border-collapse:collapse;margin-bottom:18px;font-size:14.5px}+article.page th{text-align:left;font-weight:600;padding:7px 10px 7px 0;+ border-bottom:1px solid var(--ink)}+article.page td{padding:8px 10px 8px 0;border-bottom:1px solid var(--rule);vertical-align:top}+article.page a.wiki{color:var(--accent);white-space:normal}+article.page a.wiki::before{content:"[[";color:var(--faint)}+article.page a.wiki::after{content:"]]";color:var(--faint)}+.pager{display:flex;gap:16px;justify-content:space-between;margin-top:46px;+ padding-top:18px;border-top:1px solid var(--rule);font-size:14px}+.pager a{max-width:46%}+.pager .lbl{display:block;font:11px ui-monospace,Menlo,monospace;color:var(--faint)}+.src{margin-top:34px;font:12px ui-monospace,Menlo,monospace;color:var(--faint)}++/* resources */+.rwrap{max-width:1180px;margin:0 auto;padding:34px 22px 90px}+.rwrap h1{font:600 clamp(30px,4vw,44px)/1.08 Charter,Georgia,serif;letter-spacing:-.025em}+.lede{max-width:62ch;color:var(--soft);margin:12px 0 24px;font-size:17px}+.controls{display:flex;flex-wrap:wrap;gap:9px;align-items:center;margin-bottom:8px;+ padding-bottom:18px;border-bottom:1px solid var(--rule)}+.chip{font:13px/1 ui-monospace,Menlo,monospace;background:var(--card);color:var(--soft);+ border:1px solid var(--rule);border-radius:20px;padding:7px 13px;cursor:pointer}+.chip.on{background:var(--accent);border-color:var(--accent);color:#F7F9F6}+.controls input{margin-left:auto;font:14px ui-monospace,Menlo,monospace;+ background:var(--card);border:1px solid var(--rule);border-radius:3px;padding:8px 11px;width:230px}+.count{font:12px ui-monospace,Menlo,monospace;color:var(--faint);padding:14px 0 4px}+.grp-h{font:600 15px/1 ui-monospace,Menlo,monospace;color:var(--faint);+ margin:26px 0 6px;padding-top:14px;border-top:1px solid var(--rule)}+.row{display:grid;grid-template-columns:minmax(180px,260px) 120px 1fr;gap:18px;+ padding:12px 0;border-bottom:1px solid var(--rule);align-items:baseline}+@media(max-width:760px){.row{grid-template-columns:1fr;gap:3px}}+.row .nm{font-weight:600;font-size:16px}+.row .mt{font:13px ui-monospace,Menlo,monospace;color:var(--num)}+.row .ds{color:var(--soft);font-size:15px}+.row .kd{font:11px ui-monospace,Menlo,monospace;color:var(--faint);display:block;margin-top:2px}+footer{border-top:1px solid var(--rule);padding:22px;text-align:center;+ font:12px ui-monospace,Menlo,monospace;color:var(--faint)}+@media(prefers-reduced-motion:reduce){*{transition:none!important;animation:none!important}}+"""++SEARCHBOX = ('<div class="search"><input id="q" type="search" '+ 'placeholder="search the guide" autocomplete="off">'+ '<div class="hits" id="hits"></div></div>')++def header(active):+ return f"""<header><div class="bar">+ <a class="brand" href="index.html">[[ second<span>brain</span>os ]]</a>+ <nav>+ <a href="index.html" class="{'on' if active=='guide' else ''}">Guide</a>+ <a href="resources.html" class="{'on' if active=='res' else ''}">Resources</a>+ <a href="{REPO}">Repo</a>+ </nav>+ {'<button class="toc-btn" id="toc">Index</button>' if active=='guide' else ''}+ {SEARCHBOX if active=='guide' else ''}+</div></header>"""++# ---------------- graph: sections on a ring in reading order, links as chords+import math+g = D["graph"]+order = list(D["sections"].keys())+CX, CY, RX, RY = 400, 232, 300, 150+pos = {}+for i, sec in enumerate(order):+ a = -math.pi/2 + 2*math.pi*i/len(order)+ pos[sec] = (CX + RX*math.cos(a), CY + RY*math.sin(a), a)++edges_svg = ""+for e in sorted(g["edges"], key=lambda e: e["w"]):+ x1, y1, _ = pos[e["a"]]; x2, y2, _ = pos[e["b"]]+ qx, qy = CX + (x1+x2-2*CX)*0.18, CY + (y1+y2-2*CY)*0.18+ edges_svg += (f'<path class="edge" d="M{x1:.0f},{y1:.0f} Q{qx:.0f},{qy:.0f} {x2:.0f},{y2:.0f}" '+ f'stroke-width="{min(0.8+e["w"]*0.42, 3.4):.2f}" '+ f'stroke-opacity="{min(0.35+e["w"]*0.12, 0.9):.2f}"/>')++nodes_svg = ""+for i, sec in enumerate(order):+ x, y, a = pos[sec]+ n = len([p for p in D["pages"] if p["section"] == sec])+ r = 8 + n*0.75+ cos = math.cos(a)+ anchor = "middle" if abs(cos) < 0.35 else ("start" if cos > 0 else "end")+ dx = 0 if anchor == "middle" else (r+9 if cos > 0 else -(r+9))+ dy = (r+18) if math.sin(a) > 0.35 else (-(r+12) if math.sin(a) < -0.35 else 5)+ nodes_svg += (f'<g class="node" data-sec="{sec}">'+ f'<circle cx="{x:.0f}" cy="{y:.0f}" r="{r:.1f}"/>'+ f'<text x="{x+dx:.0f}" y="{y+dy:.0f}" text-anchor="{anchor}">'+ f'{D["sections"][sec]["title"]}</text>'+ f'<text class="cnt" x="{x+dx:.0f}" y="{y+dy+13:.0f}" text-anchor="{anchor}">{n} pages</text>'+ f'<text class="idx" x="{x:.0f}" y="{y+3.5:.0f}" text-anchor="middle">{i+1}</text>'+ f'</g>')++GRAPH = (f'<figure class="figure"><svg viewBox="0 0 800 470" role="img" '+ f'aria-label="The ten sections of the guide and the links between them">'+ f'{edges_svg}{nodes_svg}</svg>'+ f'<figcaption>The ten sections, in reading order, with the '+ f'{len(g["edges"])} places they reference each other. Thicker where they lean on '+ f'each other hardest. Click one to start there.</figcaption></figure>')++s = D["stats"]+STATS = f"""<div class="stats">+ <div class="stat"><b>{s['pages']}</b><span>pages</span></div>+ <div class="stat"><b>{s['sections']}</b><span>sections</span></div>+ <div class="stat"><b>{s['words']//1000}k</b><span>words</span></div>+ <div class="stat"><b>{s['links']}</b><span>vetted links</span></div>+ <div class="stat"><b>0</b><span>lock-in</span></div>+</div>"""++import re as _re+def inline(t):+ t = html.escape(t)+ return _re.sub(r"`([^`]+)`", r"<code>\1</code>", t)++seclist = ""+for sec, meta in D["sections"].items():+ first = D["order"][sec][0]+ seclist += (f'<article><h3><a href="#{first}">{html.escape(meta["title"])}</a></h3>'+ f'<p>{inline(meta["blurb"])}</p>'+ f'<div class="pg">{len(D["order"][sec])} pages</div></article>')++GUIDE = f"""<!DOCTYPE html><html lang="en"><head>+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">+<title>Second Brain OS - the guide</title>+<meta name="description" content="A {s['pages']}-page guide to building a knowledge base your AI agent maintains, in plain markdown you own.">+<style>{CSS}</style></head><body>+{header('guide')}+<template id="hero"><div class="hero"><h1>A knowledge base your agent maintains</h1>+<p>Everything you read, watched and wrote, turned into linked pages and kept current by an agent. Plain markdown on your own machine.</p>+{GRAPH}{STATS}</div><div class="seclist">{seclist}</div></template>+<div class="wrap">+ <aside id="side"></aside>+ <main id="main"></main>+ <div class="rail" id="rail"></div>+</div>+<footer>Generated from the repository. <a href="{REPO}">github.com/undefined-ui/second-brain-os</a></footer>+<script id="data" type="application/json">{json.dumps({k:D[k] for k in ['pages','sections','order']})}</script>+<script>+const D=JSON.parse(document.getElementById('data').textContent);+const P={{}}; D.pages.forEach(p=>P[p.id]=p);+const FLAT=[]; Object.keys(D.order).forEach(s=>D.order[s].forEach(id=>FLAT.push(id)));+const HERO=document.getElementById('hero').innerHTML;++function side(cur){{+ const s=document.getElementById('side'); let h='';+ Object.keys(D.order).forEach((sec,i)=>{{+ const open = cur && cur.startsWith(sec);+ h+=`<div class="sec ${{open?'open':''}}" data-sec="${{sec}}">+ <button aria-expanded="${{!!open}}"><span class="k">${{String(i+1).padStart(2,'0')}}</span>+ ${{D.sections[sec].title}}<span class="n">${{D.order[sec].length}}</span></button><ol>`;+ D.order[sec].forEach(id=>{{+ h+=`<li><a href="#${{id}}" class="${{id===cur?'cur':''}}">${{P[id].title}}</a></li>`;+ }});+ h+='</ol></div>';+ }});+ s.innerHTML=h;+ s.querySelectorAll('.sec>button').forEach(b=>b.onclick=()=>{{+ const d=b.parentElement; d.classList.toggle('open');+ b.setAttribute('aria-expanded', d.classList.contains('open'));+ }});+}}++function render(){{+ const id=decodeURIComponent(location.hash.slice(1));+ const main=document.getElementById('main'), rail=document.getElementById('rail');+ if(!P[id]){{+ main.innerHTML=HERO; rail.innerHTML=''; side(null);+ main.querySelectorAll('svg .node').forEach(n=>n.onclick=()=>{{+ location.hash=D.order[n.dataset.sec][0];+ }});+ document.title='Second Brain OS - the guide';+ window.scrollTo(0,0); return;+ }}+ const p=P[id], i=FLAT.indexOf(id), prev=FLAT[i-1], next=FLAT[i+1];+ main.innerHTML=`<article class="page">+ <div class="crumb">${{p.section_title}} / page ${{D.order[p.section].indexOf(id)+1}} of ${{D.order[p.section].length}}</div>+ <h1>${{p.title}}</h1>${{p.html}}+ <div class="pager">+ ${{prev?`<a href="#${{prev}}"><span class="lbl">previous</span>${{P[prev].title}}</a>`:'<span></span>'}}+ ${{next?`<a href="#${{next}}" style="text-align:right"><span class="lbl">next</span>${{P[next].title}}</a>`:'<span></span>'}}+ </div>+ <div class="src">source: <a href="{REPO}/blob/main/${{p.path}}">${{p.path}}</a></div>+ </article>`;+ // rewrite internal links to hash routes, style them as wikilinks+ main.querySelectorAll('a[href$=".md"]').forEach(a=>{{+ if(/^https?:/.test(a.getAttribute('href'))) return;+ const parts=a.getAttribute('href').replace(/^\\.\\//,'').split('/');+ let target=null;+ const file=parts[parts.length-1].replace('.md','');+ if(file==='README'){{+ const sec=parts[parts.length-2]; if(D.order[sec]) target=D.order[sec][0];+ }} else {{+ const sec = parts.length>1 ? parts[parts.length-2] : p.section;+ const cand = sec+'/'+file;+ target = P[cand] ? cand : (P[p.section+'/'+file] ? p.section+'/'+file : null);+ }}+ if(target){{ a.setAttribute('href','#'+target); a.className='wiki'; }}+ else if(a.getAttribute('href').indexOf('..')===0 || !/^https?:/.test(a.getAttribute('href'))){{+ a.setAttribute('href','{REPO}/blob/main/'+a.getAttribute('href').replace(/^(\\.\\.\\/)+/,''));+ }}+ }});+ const heads=[...main.querySelectorAll('h2')];+ const outs=[...main.querySelectorAll('a.wiki')].slice(0,8);+ rail.innerHTML=(heads.length?`<div class="grp"><h4>on this page</h4>`++ heads.map((h,n)=>{{h.id='h'+n;return `<a href="#${{id}}" onclick="document.getElementById('h${{n}}').scrollIntoView();return false">${{h.textContent}}</a>`}}).join('')+`</div>`:'')+ +(outs.length?`<div class="grp"><h4>links out</h4>`++ outs.map(a=>`<a href="${{a.getAttribute('href')}}">${{a.textContent}}</a>`).join('')+`</div>`:'');+ side(id); document.title=p.title+' - Second Brain OS'; window.scrollTo(0,0);+}}++// search+const q=document.getElementById('q'), hits=document.getElementById('hits');+q.addEventListener('input',()=>{{+ const v=q.value.trim().toLowerCase();+ if(v.length<2){{hits.classList.remove('open');return;}}+ const r=D.pages.map(p=>{{+ let sc=0; const t=p.title.toLowerCase();+ if(t.includes(v)) sc+=10; if(t.startsWith(v)) sc+=6;+ const n=(p.text.toLowerCase().split(v).length-1); sc+=Math.min(n,6);+ return {{p,sc}};+ }}).filter(x=>x.sc>0).sort((a,b)=>b.sc-a.sc).slice(0,9);+ hits.innerHTML=r.length?r.map(x=>`<a class="hit" href="#${{x.p.id}}"><b>${{x.p.title}}</b><i>${{x.p.section_title}}</i></a>`).join('')+ :'<div class="hit"><i>nothing in the guide matches that</i></div>';+ hits.classList.add('open');+}});+q.addEventListener('keydown',e=>{{if(e.key==='Escape'){{q.value='';hits.classList.remove('open');q.blur();}}}});+document.addEventListener('click',e=>{{if(!e.target.closest('.search'))hits.classList.remove('open');}});+document.addEventListener('keydown',e=>{{+ if(e.key==='/'&&document.activeElement!==q){{e.preventDefault();q.focus();}}+ if(!P[decodeURIComponent(location.hash.slice(1))])return;+ const i=FLAT.indexOf(decodeURIComponent(location.hash.slice(1)));+ if(e.key==='ArrowRight'&&FLAT[i+1])location.hash=FLAT[i+1];+ if(e.key==='ArrowLeft'&&FLAT[i-1])location.hash=FLAT[i-1];+}});+hits.addEventListener('click',()=>{{hits.classList.remove('open');q.value='';}});+const toc=document.getElementById('toc');+if(toc){{toc.onclick=()=>document.getElementById('side').classList.toggle('show');}}+document.getElementById('side').addEventListener('click',e=>{{+ if(e.target.tagName==='A'&&innerWidth<=860) document.getElementById('side').classList.remove('show');+}});+addEventListener('hashchange',render); render();+</script></body></html>"""++open(f"{OUT}/index.html","w").write(GUIDE)++# ---------------- resources page+R = D["resources"]+kinds = []+for r in R:+ if r["kind"] not in kinds: kinds.append(r["kind"])++RES = f"""<!DOCTYPE html><html lang="en"><head>+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">+<title>Second Brain OS - resources</title>+<meta name="description" content="{len(R)} checked links: Obsidian plugins by installs, repositories by stars, papers, tools and reading.">+<style>{CSS}</style></head><body>+{header('res')}+<div class="rwrap">+ <h1>Everything worth opening</h1>+ <p class="lede">{len(R)} links, each one checked. Plugins are ranked by installs from Obsidian's own community stats rather than by stars, because in this ecosystem the two disagree by an order of magnitude. Figures are from September 2026 and will drift.</p>+ <div class="controls" id="ctl">+ <button class="chip on" data-k="all">All</button>+ {"".join(f'<button class="chip" data-k="{html.escape(k)}">{html.escape(k)}</button>' for k in kinds)}+ <input id="rq" type="search" placeholder="filter" autocomplete="off">+ </div>+ <div class="count" id="count"></div>+ <div id="rows"></div>+</div>+<footer>Generated from the repository. <a href="{REPO}">github.com/undefined-ui/second-brain-os</a></footer>+<script id="rdata" type="application/json">{json.dumps(R)}</script>+<script>+const R=JSON.parse(document.getElementById('rdata').textContent);+let kind='all', term='';+function draw(){{+ const f=R.filter(r=>(kind==='all'||r.kind===kind) &&+ (!term || (r.name+' '+r.desc+' '+r.group).toLowerCase().includes(term)));+ document.getElementById('count').textContent=f.length+' of '+R.length+' shown';+ let h='', g=null;+ f.forEach(r=>{{+ const key=r.kind+' / '+r.group;+ if(key!==g){{g=key; h+=`<div class="grp-h">${{r.group||r.kind}}</div>`;}}+ h+=`<div class="row">+ <div><a class="nm" href="${{r.url}}">${{r.name}}</a><span class="kd">${{r.kind}}</span></div>+ <div class="mt">${{r.metric||''}}</div>+ <div class="ds">${{r.desc||''}}</div></div>`;+ }});+ document.getElementById('rows').innerHTML=h||'<div class="count">nothing matches that filter</div>';+}}+document.getElementById('ctl').addEventListener('click',e=>{{+ const b=e.target.closest('.chip'); if(!b)return;+ document.querySelectorAll('.chip').forEach(c=>c.classList.toggle('on',c===b));+ kind=b.dataset.k; draw();+}});+document.getElementById('rq').addEventListener('input',e=>{{term=e.target.value.trim().toLowerCase();draw();}});+draw();+</script></body></html>"""++open(f"{OUT}/resources.html","w").write(RES)+print("index.html", os.path.getsize(f"{OUT}/index.html")//1024, "KB |",+ "resources.html", os.path.getsize(f"{OUT}/resources.html")//1024, "KB")diff --git a/tools/extract_site.py b/tools/extract_site.pynew file mode 100644index 0000000..42207cf--- /dev/null+++ b/tools/extract_site.py@@ -0,0 +1,125 @@+#!/usr/bin/env python3+"""Extracts guide pages, the doc link graph, and the resource catalog into JSON."""+import os, re, json, glob+import markdown++ROOT = "."+md = markdown.Markdown(extensions=["tables", "fenced_code", "toc", "attr_list"])++SECTION_TITLES = {}+pages = [] # {id, section, section_title, title, html, headings, links}++for secdir in sorted(glob.glob(f"{ROOT}/docs/*/")):+ sec = os.path.basename(secdir.rstrip("/"))+ idx = open(secdir + "README.md").read()+ stitle = re.search(r"^# (.+)$", idx, re.M).group(1)+ sblurb = ""+ m = re.search(r"^#[^\n]+\n\n([^\n].*?)\n\n", idx, re.S)+ if m: sblurb = " ".join(m.group(1).split())+ SECTION_TITLES[sec] = {"title": stitle, "blurb": sblurb}+ listed = re.findall(r"^- \[[^\]]+\]\(([a-z0-9-]+)\.md\)", idx, re.M)+ files = [f + ".md" for f in listed]+ for extra in sorted(os.path.basename(x) for x in glob.glob(secdir + "*.md")):+ if extra != "README.md" and extra not in files: files.append(extra)+ for name in files:+ p = secdir + name+ if not os.path.exists(p): continue+ raw = open(p).read()+ title = re.search(r"^# (.+)$", raw, re.M).group(1)+ body = re.sub(r"^# .+\n", "", raw, count=1)+ # collect internal links before converting+ links = []+ for lm in re.finditer(r"\[([^\]]+)\]\((?!https?://)([^)#]+\.md)\)", body):+ tgt = os.path.normpath(os.path.join(secdir, lm.group(2)))+ links.append((lm.group(1), tgt))+ heads = [h for h in re.findall(r"^## (.+)$", body, re.M)]+ md.reset()+ html = md.convert(body)+ pages.append({+ "id": f"{sec}/{name[:-3]}",+ "path": os.path.relpath(p, ROOT),+ "section": sec, "section_title": stitle,+ "title": title, "html": html, "headings": heads,+ "raw_links": links,+ "words": len(body.split()),+ "text": " ".join(re.sub(r"[`*#>\[\]()]", " ", body).split())[:4000],+ })++by_path = {p["path"]: p["id"] for p in pages}+sec_index = {}+for p in pages:+ sec_index.setdefault(p["section"], []).append(p["id"])++# resolve links to page ids+for p in pages:+ out = []+ for label, tgt in p["raw_links"]:+ rel = os.path.relpath(tgt, ROOT)+ if rel in by_path:+ out.append({"to": by_path[rel], "label": label})+ p["links"] = out+ del p["raw_links"]++# ---- section-level cross-reference weights for the hero figure+w = {}+for p in pages:+ for l in p["links"]:+ a, b = p["section"], l["to"].split("/")[0]+ if a != b:+ k = tuple(sorted((a, b)))+ w[k] = w.get(k, 0) + 1+nodes = [{"id": s, "title": SECTION_TITLES[s]["title"], "n": len(sec_index[s])}+ for s in SECTION_TITLES]+edges = [{"a": a, "b": b, "w": n} for (a, b), n in w.items()]++# ---- resources: parse every markdown table row that carries a link+res = []+CAT = {"plugins.md": "Obsidian plugin", "tools.md": "Tool", "skills.md": "Skills",+ "repositories.md": "Repository", "papers.md": "Paper", "reading.md": "Reading"}+for f in sorted(glob.glob(f"{ROOT}/resources/*.md")):+ fn = os.path.basename(f)+ if fn == "README.md": continue+ group = ""+ for line in open(f):+ h = re.match(r"^## (.+)$", line)+ if h: group = h.group(1).strip(); continue+ if not line.startswith("|"): continue+ cells = [c.strip() for c in line.strip().strip("|").split("|")]+ if len(cells) < 2 or set("".join(cells)) <= set("-: "): continue+ link = re.search(r"\[([^\]]+)\]\((https?://[^)]+)\)", cells[0])+ if not link: continue+ rest = cells[1:]+ metric = ""+ desc = ""+ for c in rest:+ if re.fullmatch(r"[\d,.]+[KM]?|community plugin|small", c.strip()):+ metric = c.strip()+ else:+ desc = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", c)+ res.append({"file": fn, "kind": CAT.get(fn, "Link"), "group": group,+ "name": link.group(1), "url": link.group(2),+ "metric": metric, "desc": desc.strip()})++# extra links that live in prose, not tables+for f in [f"{ROOT}/resources/reading.md", f"{ROOT}/resources/papers.md"]:+ txt = open(f).read()+ group = ""+ for block in txt.split("\n\n"):+ h = re.search(r"^## (.+)$", block, re.M)+ if h: group = h.group(1).strip()+ for m in re.finditer(r"\*\*\[([^\]]+)\]\((https?://[^)]+)\)\*\*", block):+ if any(r["url"] == m.group(2) for r in res): continue+ clean = re.sub(r"\s+", " ", re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", block))+ clean = re.sub(r"[*#>]", "", clean).strip()+ desc = clean.split(". ", 1)[1] if ". " in clean else clean+ res.append({"file": os.path.basename(f), "kind": CAT[os.path.basename(f)],+ "group": group, "name": m.group(1), "url": m.group(2),+ "metric": "", "desc": desc[:240]})++data = {"pages": pages, "sections": SECTION_TITLES, "order": sec_index,+ "graph": {"nodes": nodes, "edges": edges}, "resources": res,+ "stats": {"pages": len(pages), "words": sum(p["words"] for p in pages),+ "sections": len(SECTION_TITLES), "links": len(res)}}+json.dump(data, open("site_data.json", "w"))+print("pages:", len(pages), "| resources:", len(res), "| section edges:", len(edges),+ "| words:", data["stats"]["words"])