obsidian-graph

Obsidian Graph Analysis

Use obsidian_search and obsidian_read_file to gather vault data, then run Python/networkx analysis via Bash.

Citation Network

Steps:

1. obsidian_search with query="", extensions=".md" — get all notes.
2. For each note, obsidian_read_file and extract:
   • Outgoing links: regex \[\[([^\]|#]+) on the file body.
   • Zotero citekey from frontmatter citekey field.
3. Write a Python script and run with Bash:

import json, re, pathlib, sys

vault = sys.argv[1]
notes = {}
for md in pathlib.Path(vault).rglob("*.md"):
    rel = str(md.relative_to(vault))
    text = md.read_text(encoding="utf-8", errors="ignore")
    links = re.findall(r'\[\[([^\]|#\n]+)', text)
    notes[rel] = links

edges = []
for src, targets in notes.items():
    for tgt in targets:
        edges.append({"source": src, "target": tgt + ".md"})

print(json.dumps({"nodeCount": len(notes), "edgeCount": len(edges), "edges": edges[:100]}, indent=2))

Run: python graph_build.py "<vault_path>"

Community Detection

import networkx as nx, json, sys

data = json.loads(sys.argv[1])
G = nx.DiGraph()
for e in data["edges"]:
    G.add_edge(e["source"], e["target"])

U = G.to_undirected()
communities = list(nx.community.greedy_modularity_communities(U))
result = [{"community": i, "nodes": list(c)[:10], "size": len(c)}
          for i, c in enumerate(communities)]
print(json.dumps(result, indent=2))

Connectivity Metrics

From the directed graph, compute:

• Hub nodes: high in-degree (most-cited notes).
• Authority nodes: high out-degree (index/survey notes).
• Orphans: in-degree = 0 and out-degree = 0.
• Weakly connected components: isolated clusters.

import networkx as nx
hubs = sorted(G.in_degree(), key=lambda x: x[1], reverse=True)[:10]
orphans = [n for n in G.nodes if G.in_degree(n) == 0 and G.out_degree(n) == 0]
components = list(nx.weakly_connected_components(G))

Graph Improvement Suggestions

After computing metrics, suggest:

1. Create missing notes: For each dead link target, suggest obsidian_write_file to create a stub.
2. Convert markdown links: Find [text](file.md) patterns → suggest converting to [[file]].
3. Connect isolated clusters: Find thematically related notes between clusters (by tag overlap) and suggest wikilinks.
4. Remove orphans: List orphan notes and ask the user if they should be linked or deleted.

---

中文说明

通过 obsidian_search + obsidian_read_file 收集 vault 数据，用 Bash 运行 Python/networkx 脚本完成引用网络构建、社区检测和连通性分析。分析结果转化为可操作的 obsidian_write_file 建议。

Knowledge Gap Detection

Run after building the graph (see "Citation Network" above). Identifies notes and clusters that are under-connected.

import networkx as nx

# 1. Isolated nodes — no edges at all
gaps = [n for n in G.nodes if G.degree(n) == 0]
print(f"Isolated notes ({len(gaps)}):", gaps[:20])

# 2. Sparse communities — single-node or two-node clusters after community detection
sparse = [list(c) for c in communities if len(c) <= 2]
print(f"Sparse communities ({len(sparse)}):", sparse)

# 3. Bridge nodes — their removal would disconnect the graph
bridges = list(nx.bridges(G.to_undirected()))
bridge_nodes = {u for u, v in bridges} | {v for u, v in bridges}
print(f"Bridge nodes ({len(bridge_nodes)}):", list(bridge_nodes)[:10])

Report to the user:

• Isolated notes → suggest obsidian_search by tag overlap to find candidate notes to link, or ask whether to delete.
• Sparse single-paper communities → these topics have no neighbors; suggest importing related Zotero items.
• Bridge notes → held two clusters together; flag as candidates to expand into proper index notes with obsidian_write_file.

Surprising Connections

Run after community detection. Finds high-value cross-community edges that may represent unexpected interdisciplinary links.

# Map each node to its community index
node_to_community = {}
for i, c in enumerate(communities):
    for n in c:
        node_to_community[n] = i

# Cross-community edges
cross_edges = [
    (u, v) for u, v in G.edges()
    if node_to_community.get(u) != node_to_community.get(v)
]

# Rank by combined degree — high-degree cross-community links are most surprising
cross_edges.sort(
    key=lambda e: G.degree(e[0]) + G.degree(e[1]),
    reverse=True
)

print("Top surprising connections:")
for u, v in cross_edges[:10]:
    print(f"  [{node_to_community[u]}] {u}  →  [{node_to_community[v]}] {v}")

Report to the user: For each of the top 10 cross-community connections, describe which two thematic clusters they bridge (using community member note names as cluster labels). Suggest:

• Adding a wikilink annotation explaining the connection, or
• Creating a new bridge note that synthesizes the two lines of work.

Eval Scenarios

• Trigger: "Find isolated literature notes." Expected: build a wikilink graph from vault Markdown and report isolated nodes. Must not delete or edit notes.
• Trigger: "Where are the knowledge gaps in this research vault?" Expected: compute isolated notes, sparse communities, and bridge nodes, then recommend candidate links or new index notes. Must mark recommendations as suggestions unless the user asks to apply them.
• Trigger: "Show surprising interdisciplinary links." Expected: detect cross-community edges and explain why they bridge clusters. Must not invent relationships that are not supported by existing links/tags.