Connection Agent: Stop Losing Ideas in Your Obsidian Vault

Every developer who uses Obsidian seriously eventually hits the same wall. You have hundreds — maybe thousands — of notes about technologies, projects, people, and ideas. You know the connections are there. That note about LangChain from three months ago almost certainly relates to the architecture decision you documented last week. That person you met at the conference is probably mentioned in both your meeting notes and your research on a specific domain. But finding and linking all of this manually is tedious work that almost never gets done.

The result is a knowledge graph that looks rich on the surface but is actually a collection of isolated islands. Notes sit orphaned, never surfaced when they’d be most useful. Maps of Content (MOCs) point to some things but miss others. The promise of a second brain quietly fails.

The Connection Agent exists to fix this. It’s a Claude Code subagent specialized for the VAULT01 knowledge management system that proactively analyzes your vault, runs link discovery scripts, identifies orphaned notes, and generates actionable reports — all without requiring you to manually inspect hundreds of files. For developers who treat their knowledge base as infrastructure, this agent is the automated maintenance job you never got around to writing.

When to Use the Connection Agent

This agent is designed to be invoked proactively, not just when you remember to run it. Here are the concrete scenarios where it delivers the most value:

After a Heavy Research Sprint

You’ve spent two weeks deep-diving on a technical topic — reading papers, taking notes, dumping ideas into your vault. Now you have 40 new notes that exist in isolation. The Connection Agent can sweep through them, identify entity overlaps with existing content, and generate a prioritized list of links to review. What would take you an afternoon takes the agent minutes.

Weekly Vault Maintenance

Treat vault hygiene the same way you treat code hygiene. Add a standing task to run the Connection Agent as part of your weekly review. It identifies orphaned nodes — notes with no incoming or outgoing links — that have likely fallen through the cracks. These are almost always notes worth either connecting or consciously archiving.

Before Writing a Major Document

You’re about to write a long-form technical design doc or a deep-dive blog post. Run the Connection Agent first to surface all the related notes in your vault. You’ll often find you’ve already written substantial content on adjacent topics that should inform or be referenced by the new document.

Onboarding Related Topics

You’re moving into a new technical area — say, moving from general ML work into specifically studying transformer architectures. The Connection Agent can identify which of your existing notes touch on this domain and show you what’s already connected versus what’s isolated, giving you a real map of your existing knowledge before you start adding to it.

Auditing MOC Coverage

Maps of Content are only useful if they’re comprehensive. The Connection Agent’s structural analysis checks whether your MOCs are actually linking to the relevant content that exists in the same conceptual neighborhood, flagging gaps that make your navigation layer incomplete.

What Makes This Agent Powerful

The Connection Agent isn’t just a wrapper around a script. Its system prompt encodes a sophisticated understanding of how knowledge graphs should be built and maintained. Several capabilities stand out:

Multi-Strategy Connection Discovery

The agent uses three distinct approaches simultaneously. Entity extraction catches explicit references — when two notes both mention “Andrej Karpathy” or “Claude,” they probably should be connected. Semantic similarity analysis looks at shared terminology and concepts even when explicit entities aren’t mentioned. Structural analysis uses directory proximity and note type (daily note, MOC, project note) as signals about likely relationships. Running all three strategies gives it a much higher recall rate than any single approach.

Confidence-Scored Suggestions

Not all potential connections are equal. The agent prioritizes its suggestions by confidence score and number of shared entities, so you’re reviewing the highest-value links first. This prevents the common failure mode of link suggestion tools: burying the obviously correct links in a sea of marginal ones.

Orphaned Note Detection

Finding notes with no incoming or outgoing links is deceptively important. These are the notes most likely to be forgotten, and they’re often notes that got created during a productive session but never integrated into the broader graph. The agent generates a dedicated orphaned content report, giving you a specific action list rather than a vague sense that something might be missing.

Actionable Report Generation

The agent is built around generating reports that support manual curation rather than automatically modifying your vault. This is the right design decision. Automatic link insertion is fragile and often wrong in ways that are hard to undo. Instead, you get structured markdown reports — Link_Suggestions_Report.md, Orphaned_Content_Connection_Report.md, Orphaned_Nodes_Connection_Summary.md — that you can review, accept, or reject with full context.

Quality Over Quantity Orientation

The agent’s instructions explicitly prioritize quality connections over maximum connection count. This matters. A knowledge graph cluttered with weak, low-confidence links is actually worse than one with fewer, stronger connections because it degrades navigation and discovery. The agent is tuned to surface meaningful relationships, not to maximize a link count metric.

How to Install the Connection Agent

Claude Code supports subagents defined as markdown files in a specific directory. Installation is straightforward:

Step 1: In your project root (or your home directory if you want the agent available globally), create the directory structure:

mkdir -p .claude/agents

Step 2: Create the agent file:

.claude/agents/connection-agent.md

Step 3: Paste the full system prompt into that file. The file should contain the complete agent body, including the core responsibilities, available scripts, connection strategies, workflow, and important notes sections.

Step 4: Claude Code loads agents from .claude/agents/ automatically. The next time you open a Claude Code session, the Connection Agent will be available. You can invoke it directly by referencing it in your prompt or let Claude use it proactively when you’re working on vault-related tasks.

One configuration step you’ll need to handle: the agent references specific paths under /Users/cam/VAULT01/. Update the script path in the agent file to match your actual vault location and username before using it. The Python script referenced (link_suggester.py) should exist at that path — if you don’t have it yet, you can ask Claude to help you generate a version appropriate for your vault structure.

Practical Next Steps

Getting the agent installed is the easy part. Here’s how to actually integrate it into your workflow in a way that compounds over time:

• Run it on your existing vault immediately. Don’t wait for a clean state. The value is in discovering connections in your existing content, and the first run on a mature vault is typically the most revealing. Expect the orphaned notes report to be longer than you’d like.
• Set a recurring reminder. Weekly is reasonable for an active vault. Monthly works if you’re a lighter user. The key is making it a scheduled habit rather than something you remember to do occasionally.
• Work through the reports systematically. Start with the high-confidence suggestions. Spend 15–20 minutes after each run accepting or rejecting suggestions before the list grows stale. Don’t let reports accumulate without acting on them.
• Refine the link_suggester.py script over time. As you review suggestions, you’ll develop a sense of which entity types and keyword patterns generate the most useful connections for your specific vault. Update the script to reflect that. The agent is only as good as the underlying analysis.
• Use orphaned note reports as a forcing function. Every orphaned note is a decision: connect it, archive it, or delete it. Don’t leave notes in limbo indefinitely. The Connection Agent makes this decision explicit rather than letting notes quietly fade into irrelevance.

A well-maintained knowledge graph is a genuine competitive advantage for developers. It’s the difference between a vault you actively use for thinking and one you accumulate notes in without ever synthesizing them. The Connection Agent automates the maintenance work that makes the difference — letting you focus on the thinking instead of the bookkeeping.

Agent template sourced from the claude-code-templates open source project (MIT License).