obsidian-graph-query — Let your AI agent query your vault's knowledge graph (BFS, shortest path, bridges, hubs, orphans)

Share & showcase
1

Your vault has a graph. But you can only stare at it.

Graph view is great for exploring, but it can’t answer questions — “Which notes have the most links?” “How many hops
between these two concepts?” “Which notes would break the network if removed?” “How many notes are completely isolated?”

I built an AI agent skill that runs graph algorithms directly on your vault’s link structure via the Obsidian CLI, and
explains the results in natural language.

What you can ask

┌───────────────────────────────────────────────────┬────────────────────────────────────────────────────────┐
│ You say │ What happens │
├───────────────────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ “Which notes have the most links?” │ Degree analysis, ranks hub nodes by link count │
├───────────────────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ “How are [[Note A]] and [[Note B]] connected?” │ BFS shortest path with full route │
├───────────────────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ “What’s around [[this note]]?” │ N-hop neighbor expansion │
├───────────────────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ “Which notes would break the network if removed?” │ Tarjan bridge detection + articulation points │
├───────────────────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ “Find orphan notes” │ Full vault scan, zero-link notes with frontmatter info │
└───────────────────────────────────────────────────┴────────────────────────────────────────────────────────┘

How it works

The skill has 7 JS query templates (BFS neighbors, shortest path, connected components, iterative Tarjan, degree
calculation, orphan scan, frontmatter relations). Your AI agent picks the right template, substitutes your vault config
(excluded folders, relationship fields), and runs it via obsidian cli eval. Data source is
app.metadataCache.resolvedLinks — Obsidian’s live link index.

Tested on a 2,000+ note vault.

Requirements

  • Obsidian with CLI enabled (Settings > General > Command-line interface)
  • Any supported AI agent — Claude Code, OpenClaw, Cursor, Cline, GitHub Copilot, Windsurf, and 30+ more

Install

npx skills add azuma520/obsidian-graph-query

Then restart your agent and say “help me set up graph query vault config” — the agent will walk you through excluded
folders, relationship fields, etc.

GitHub: GitHub - azuma520/obsidian-graph-query: Let your AI agent query your Obsidian vault's knowledge graph directly.

Open source, MIT licensed. Feedback and contributions welcome.

1 Like
2

Love the bridge detection and orphan scan - those are exactly the queries I always wanted but couldn’t run from the graph view. I found bridge detection especially useful for spotting which notes are actually load-bearing in your knowledge structure. I’m testing this with OpenClaw + Obsidian CLI today.

3

Thanks for the feedback! Here’s how to get more out of the results:
Bridge notes — A high bridge score means this note is the only path between two knowledge clusters. Think of it as a diagnostic signal:

  • Use neighbors on that note to see which clusters it connects
  • If those clusters should be related but only this one note links them, you might have unexplored conceptual connections worth thinking about
  • If they shouldn’t be related, then the bridge is just naturally doing its job — no action needed

Orphan notes — An orphan isn’t necessarily a problem. It might be a fresh idea that hasn’t found its place yet. suggest-links surfaces potential connections based on shared
tags and properties — a good starting point to think about whether these notes are conceptually related.

Big picture — Try the /health workflow (vault-stats + bridges + suggest-links combined). It gives you a KPI dashboard — useful for spotting trends over time rather than
one-off fixes.

Pairing with semantic search — Have you tried qmd?? It adds semantic search to your vault — graph-query finds structural connections (links, paths,
bridges), qmd finds meaning-based connections (similar content even without links). The two complement each other well: qmd surfaces notes that should be connected,
graph-query shows how they are connected.

For OpenClaw setup, make sure your vault-config.md has the correct excluded folders to keep system folders out of your results.

1 Like