My Obsidian vault hit 580 notes. I’d been linking concepts for months, feeling pretty good about my “second brain.” Then I started noticing problems: stuff I’d definitely written about, but couldn’t find by following links. Notes that led nowhere. Topics that should be connected but weren’t.

Gut feeling wasn’t enough. I wanted numbers. So I wrote a script to give my knowledge base a proper checkup.

It found 102 problems. Then it fixed all of them.

What Does a “Healthy” Knowledge Base Look Like?

Think of your vault like a city’s road network. A good city has:

1. Neighborhoods — related streets cluster together (your notes on React hooks link to state management, useEffect, component lifecycle)
2. Highways — you can get from any neighborhood to any other in a few turns, not twenty
3. Multiple routes — if one road is closed, you can still get where you need to go

Network scientists call this a small-world network. It’s the same structure behind social networks (“six degrees of separation”), the internet, and your brain’s neural pathways. Tight local clusters, short global paths, a few key hubs connecting everything.

There’s a single number that captures this — the small-world coefficient σ:

σ = (C / C_random) ÷ (L / L_random)

C is the clustering coefficient — how tightly your neighborhoods stick together. L is the average path length — how many hops to get between any two notes. You divide each by what a random graph of the same size would produce. σ > 1 = small-world. Higher is better.

My vault scored σ = 9.67: clustering 12× higher than random, path lengths only 1.2× longer. The big picture was fine. But the details were a mess.

What the Checkup Found

The script analyzed two things: what my notes say (content) and how they’re connected (structure). Here’s what came back.

21 pairs of notes that should know about each other, but don’t

The script builds a TF-IDF vector for every note — a fingerprint of which words matter most in each one — then computes the cosine similarity between every pair. When two notes score above 0.5 (meaning they share significant vocabulary) but have no link between them, that’s a gap in your knowledge web. I had 21 of these — notes about the same concept written weeks apart, each unaware the other exists.

20 dead ends

Notes you can arrive at, but can’t leave. You follow a link, land on the page, and… there’s nowhere to go next. Twenty of my notes were like cul-de-sacs with no exit.

8 orphan notes

The opposite problem: notes that link out to other things, but nothing links to them. The only way to find them is to search by name. If you don’t remember the exact title, they’re invisible.

15 single points of failure

This was the scariest finding. In graph theory they’re called articulation points — nodes whose removal splits the graph into disconnected pieces. In plain English: fifteen notes where, if you deleted just that one note, entire topic areas would become unreachable from each other. Imagine a bridge that’s the only connection between two halves of a city — lose it, and you can’t get across.

My worst offender was a note called system-architecture. It had the highest betweenness centrality in the entire graph — meaning more shortest paths ran through it than any other node. Every route between frontend and infrastructure topics depended on it. One note, holding the whole thing together.

5 topic silos with almost no cross-links

Using community detection (modularity optimization), the algorithm found five natural topic clusters in my vault. The problem: they were barely connected to each other. Each cluster was a self-contained island. You could navigate freely within “deployment,” but getting from “deployment” to “data modeling” meant hopping through the same overloaded hub notes every time.

23 broken links

Notes pointing to raw file paths ([[report.pdf]]) instead of actual concepts ([[quarterly-review]]). These create phantom nodes in the graph — destinations that don’t really exist.

What the Script Fixed

Diagnosis without action is useless. The script runs six repair passes, from most critical to least:

1. Bypass routes around every single-point-of-failure. For each dangerous hub note, connect two of its neighbors directly. Now if the hub disappears, there’s still a path. 51 bypass links added.
2. Fix the 23 broken links. Map each bad link to its correct target. Done.
3. Give every orphan note an incoming link. Find the most relevant connected note and add a backlink. 8 orphans rescued.
4. Connect the 21 “should-be-linked” pairs. Add bidirectional links between notes that discuss the same topic but didn’t reference each other. 13 pairs connected (the rest fell below the confidence threshold).
5. Cross-reference near-duplicates. Instead of merging similar notes (which loses nuance), add “see also” links so you know both exist. 1 cross-reference.
6. Build bridges between topic silos. Pick the most important note in each cluster and connect it to the most important note in the next cluster. 6 bridges built.

Total: 102 fixes, one run, zero manual editing.

Before and After

Tighter clusters, faster navigation, backup routes everywhere. The vault went from “works if you already know where everything is” to “you can actually discover things by browsing.”

What I Took Away

1. Every knowledge base rots if you don’t maintain it. Bottlenecks, dead ends, and orphans are the natural byproduct of organic growth. You won’t notice until it’s already bad.
2. The scariest problems are invisible. I had no idea 15 of my notes were single points of failure. It felt fine. The numbers told a different story.
3. Machines catch what humans miss. Two notes about the same topic, written in different words, weeks apart? I’d never have connected them manually. The algorithm did it in seconds.
4. “Organizing my notes” can be engineering, not vibes. Measure, diagnose, fix, re-measure. Same loop as any other system.