Connection Agent Consultant

Knowledge graph discovery agent for identifying, scoring, and suggesting meaningful connections between notes in Obsidian-based knowledge management vaults.

When to Use This Agent

Choose this agent when you need to:

• Discover hidden relationships between notes that share entities, concepts, or terminology
• Identify orphaned notes that lack incoming or outgoing links and need integration
• Generate prioritized link suggestion reports for manual curation
• Analyze knowledge graph topology to find clusters, gaps, and structural weaknesses

Consider alternatives when:

• You need to create new notes rather than connect existing ones
• Your task is vault-wide restructuring or taxonomy redesign rather than link discovery

Quick Start

Configuration

Copy
name: connection-agent-consultant
type: agent
category: obsidian-ops-team

Example Invocation

Copy
claude agent:invoke connection-agent-consultant "Analyze my vault for orphaned notes and suggest connections based on shared entity mentions"

Example Output

Connection Discovery Report
=============================
Vault: VAULT01 | Notes Analyzed: 1,247 | Orphaned: 83

Top Connection Suggestions:
  1. [[LangChain Overview]] <-> [[RAG Pipeline Design]]
     Shared entities: LangChain, vector embeddings, retrieval
     Confidence: 94% | Type: Bidirectional

  2. [[Sam Altman Interview Notes]] <-> [[OpenAI Strategy 2025]]
     Shared entities: Sam Altman, GPT-5, safety research
     Confidence: 89% | Type: Bidirectional

  3. [[Kubernetes Networking]] <-> [[Service Mesh Patterns]]
     Shared entities: Istio, sidecar proxy, ingress controller
     Confidence: 87% | Type: Directional (K8s -> Service Mesh)

Orphaned Notes Requiring Attention:
  - Meeting Notes 2025-03-01.md (no links, mentions "Project Atlas")
  - Docker Compose Cheatsheet.md (no links, relates to 4 container notes)
  - Book Notes - Thinking Fast and Slow.md (no links, shares concepts with 7 notes)

Knowledge Gaps Detected:
  - Cluster "AI/ML" has no links to cluster "Infrastructure"
  - 12 notes mention "Claude" but no MOC exists for Anthropic topics

Core Concepts

Connection Discovery Overview

Aspect	Details
Entity Extraction	People, technologies, companies, projects from note text
Keyword Analysis	TF-IDF scoring for terminology overlap between notes
Structural Analysis	Directory proximity, MOC membership, tag co-occurrence
Orphan Detection	Notes with zero incoming and zero outgoing wikilinks
Confidence Scoring	Weighted combination of entity, keyword, and structural signals
Output Format	Markdown reports with actionable link suggestions

Knowledge Graph Analysis Architecture

┌─────────────┐     ┌─────────────┐
│  Vault       │────▶│  Entity      │
│  Scanner     │     │  Extractor   │
└─────────────┘     └─────────────┘
        │                   │
        ▼                   ▼
┌─────────────┐     ┌─────────────┐
│  Orphan      │────▶│  Connection  │
│  Detector    │     │  Ranker      │
└─────────────┘     └─────────────┘

Configuration

Parameter	Type	Default	Description
vaultPath	string	"~/VAULT01"	Absolute path to the Obsidian vault root directory
minConfidence	number	70	Minimum confidence score (0-100) for link suggestions
entityTypes	string[]	["people","tech","companies"]	Entity categories to extract and match
includeDaily	boolean	false	Include daily notes in analysis (can be noisy)
maxSuggestions	number	50	Maximum number of link suggestions per report

Best Practices

1. Prioritize Bidirectional Links for Concept Notes When two permanent notes share multiple entities and keywords, create bidirectional links. Unidirectional links are appropriate for hierarchical relationships (MOC to detail note), but concept-to-concept connections benefit from bidirectional navigation.

2. Review Orphaned Notes Weekly Orphaned notes accumulate quickly from meeting notes, quick captures, and imported content. Schedule a weekly review of the orphan report to either connect them into the knowledge graph or archive them. An unconnected note provides diminishing value over time.

3. Use MOCs as Connection Hubs, Not Flat Lists Maps of Content should be structured with contextual annotations explaining why each linked note is relevant. A MOC that is merely a bullet list of links adds navigational overhead without adding understanding. Include brief relationship descriptions.

4. Tune Confidence Thresholds to Your Vault's Density Sparse vaults with few notes benefit from lower confidence thresholds (50-60) to surface any potential connections. Dense vaults with thousands of notes should use higher thresholds (80+) to avoid overwhelming suggestion reports.

5. Separate Entity-Based from Semantic Connections Two notes mentioning "Kubernetes" share an entity, but two notes discussing "container orchestration trade-offs" share a semantic theme. Track both connection types separately because they serve different navigation purposes in the knowledge graph.

Common Issues

1. Entity extraction produces false positives from common words Short entity names like "Go" (the language) or "Ray" (the framework) match ordinary English words. Add a domain-specific stop list to the entity extractor configuration and require entity matches to appear in a technical context (code blocks, tool references, or tagged sections).

2. Orphan report includes intentionally standalone notes Templates, checklists, and reference cards are designed to be self-contained. Exclude specific directories (like Templates/ or References/) from orphan detection by adding them to the ignore list, so the report surfaces only genuinely disconnected content.

3. Suggestion report is too large to review in one session When analyzing a vault with over 1,000 notes, the report can contain hundreds of suggestions. Use the maxSuggestions parameter to cap output, sort by confidence score descending, and process suggestions in batches of 10-15 per review session.