aaronsb_obsidian-mcp-plugin/docs/tools/graph.md

Graph Tool Documentation

The graph tool enables AI to navigate and analyze your vault's link structure, understanding connections between notes.

Core Concepts

Your Obsidian vault is a knowledge graph where:

• Nodes are your notes
• Edges are links between notes (both explicit links and tag connections)
• Paths are routes through the graph connecting concepts

Actions

Basic Navigation

neighbors

Get immediate connections of a note.

{
  "action": "neighbors",
  "sourcePath": "concepts/machine-learning.md",
  "includeUnresolved": false  // Include links to non-existent notes
}

traverse

Explore connections up to a certain depth.

{
  "action": "traverse",
  "sourcePath": "projects/current-project.md",
  "maxDepth": 3,  // How many hops from source
  "maxNodes": 50,  // Limit total nodes returned
  "followBacklinks": true,
  "followForwardLinks": true,
  "followTags": true
}

Path Finding

path

Find connection paths between two notes.

{
  "action": "path",
  "sourcePath": "philosophy/consciousness.md",
  "targetPath": "neuroscience/neural-networks.md"
}

Analysis

statistics

Get graph statistics for a note or the entire vault.

{
  "action": "statistics",
  "sourcePath": "index.md"  // Optional - omit for vault stats
}

Returns:

• Total links (in/out)
• Connectivity score
• Central nodes
• Orphaned notes

backlinks

Find all notes linking TO a specific note.

{
  "action": "backlinks",
  "sourcePath": "concepts/important-idea.md"
}

forwardlinks

Find all notes linked FROM a specific note.

{
  "action": "forwardlinks",
  "sourcePath": "index.md"
}

Advanced Traversal

search-traverse

Combine search with graph traversal - find related content across connected notes.

{
  "action": "search-traverse",
  "startPath": "research/ml-optimization.md",
  "searchQuery": "gradient descent",
  "maxDepth": 2,
  "maxSnippetsPerNode": 2,
  "scoreThreshold": 0.5
}

advanced-traverse

Sophisticated traversal with multiple search queries and strategies.

{
  "action": "advanced-traverse",
  "sourcePath": "projects/thesis.md",
  "searchQueries": ["methodology", "results", "conclusion"],
  "strategy": "best-first",  // breadth-first, best-first, beam-search
  "beamWidth": 5,  // For beam-search
  "maxDepth": 4
}

tag-traverse

Navigate through tag connections.

{
  "action": "tag-traverse",
  "sourcePath": "daily/2024-01-15.md",
  "tagFilter": ["#project", "#important"],
  "maxDepth": 3
}

tag-analysis

Analyze tag relationships and co-occurrences.

{
  "action": "tag-analysis",
  "sourcePath": "index.md"  // Optional
}

shared-tags

Find notes sharing tags with a source note.

{
  "action": "shared-tags",
  "sourcePath": "research/paper-1.md",
  "minSharedTags": 2  // Minimum tags in common
}

Traversal Strategies

Breadth-First

Explores all nodes at current depth before going deeper.

• Use when: You want comprehensive coverage
• Best for: Finding all related content

Best-First

Prioritizes nodes with highest relevance scores.

• Use when: You want most relevant connections
• Best for: Focused research on specific topics

Beam Search

Keeps only top N candidates at each level.

• Use when: You need balanced coverage with quality
• Best for: Large vaults where full traversal is expensive

Filtering Options

By Path

{
  "fileFilter": "^research/.*\\.md$",  // Regex pattern
  "folderFilter": "projects/"  // Only include from this folder
}

By Tags

{
  "tagFilter": ["#important", "#review"],
  "tagWeight": 0.8  // How much to prioritize tag connections
}

By Link Type

{
  "followBacklinks": true,
  "followForwardLinks": true,
  "followTags": false,
  "includeUnresolved": false,
  "includeOrphans": false
}

Use Cases

Research Synthesis

Find all content related to a research topic across connected notes:

{
  "action": "search-traverse",
  "startPath": "research/main-topic.md",
  "searchQuery": "key finding",
  "maxDepth": 3,
  "strategy": "best-first"
}

Knowledge Mapping

Understand the structure around a concept:

{
  "action": "traverse",
  "sourcePath": "concepts/central-idea.md",
  "maxDepth": 2,
  "followTags": true
}

Missing Link Discovery

Find potential connections between unlinked notes:

{
  "action": "shared-tags",
  "sourcePath": "ideas/new-idea.md",
  "minSharedTags": 3
}

Impact Analysis

See what would be affected by changing a note:

{
  "action": "backlinks",
  "sourcePath": "definitions/key-term.md"
}

Best Practices

Performance Optimization

1. Limit depth for large vaults: Start with depth 2-3
2. Use filters aggressively: Folder and tag filters reduce search space
3. Set maxNodes appropriately: Balance completeness with performance

Effective Navigation

1. Start from hub notes: Index pages or MOCs (Maps of Content)
2. Use multiple strategies: Try different traversal strategies for different goals
3. Combine with search: search-traverse is powerful for topic exploration

Graph Health

1. Check for orphans regularly: Use statistics to find disconnected notes
2. Analyze backlinks: High backlink counts indicate important notes
3. Monitor link depth: Very deep requirements might indicate poor organization