Helping My AI Agent Make Better Use Of My Obsidian Vault

1 Apr

  
TL;DR 

Core Thesis: A two-part system using frontmatter summaries and Context sections allows AI agents to efficiently navigate a knowledge vault without reading full notes.

Content Type: Tutorial · How-To 

Primary Audience: Knowledge management enthusiasts using Obsidian with AI agents like Claude Code or ChatGPT 

Key Takeaways:
  If you can't summarise a note in 2–3 sentences, it probably isn’t atomic enough — the system acts as a writing quality gate.
An outdated summary is actively worse than no summary — it gives agents false ground truth.
The Context section captures details that aren’t obvious from reading the note itself and helps both agents and future readers understand its purpose and implications.

      Technical Dependencies: A CLAUDE.md or equivalent agent instruction file to guide the AI on using the two-part system 

Bottom Line: Stop telling agents which notes to read — give them the protocol and let them self-navigate by checking summaries first.

A few years ago, I started using Obsidian as my second brain. It’s been incredibly helpful. But as I began working more with AI agents like Claude Code, ChatGPT, and a local LLM stack, I kept running into the same problem. The agents can read my notes, but they read everything or nothing, which wastes tokens and time. Instead of skimming for relevance, the agent reads the whole note before deciding if it’s useful. With thousands of notes, this becomes so inefficient that it defeats the purpose. Using agents with my knowledge base was supposed to save time, but it ended up taking more.

The solution proved quite simple. I now use a two-part pattern. Adopting this approach has transformed how I write notes.

The Problem With People-Centric Notes

I don’t usually read my notes from start to finish. I scan the main ideas, pick out what's relevant, and only read the whole thing if I need more details.

AI agents don’t work that way. They read the whole note or skip it, unless told otherwise. When I connected Claude to my vault, it sometimes skipped useful notes or wasted time on unhelpful ones. Neither worked well.

I needed a mechanism for the agent to determine a note’s relevance before committing to read it.

The Two-Part System

Now, every note in my vault has two new parts: a frontmatter summary and a Context section.

Frontmatter Summary

Each note has a summary field in its YAML frontmatter. It’s just two or three sentences that cover the main topic, the note’s purpose, and any key conclusions or current status.

---
summary: "This note covers the setup plan for a local AI stack using Ollama and AnythingLLM. It outlines a four-phase approach from model installation through to MCP integration with Claude Code. The goal is a fully private RAG system connected to the Obsidian vault."
---

That’s all there is to it. The agent checks the frontmatter first. If the summary aligns with its needs, it reads the note in full. If not, it moves to the next one. For large-scale tasks, such as identifying all notes on a topic, the agent can scan hundreds of summaries quickly before reviewing any full notes.

This has benefited me as the writer as well. If I can't summarise your note in two to three sentences, then the note probably isn't as atomic and focused as it should be, and I may need to consider splitting it up.

The summary explains what the note contains. The Context section covers things an agent might miss by just reading the note; it’s the extra details between the lines.

Context is drafted to contain things like:

Why does this note exist? What question or decision prompted it?
What did this note inform? What got built, changed, or decided because of it?
What’s still open or unresolved?

What other notes or external systems does this depend on?

Context

Created to capture research before a decision about which local LLM stack to adopt. The four-phase plan was approved and is now in progress — see [[Local AI Stack Setup]] for current status. The AnythingLLM option was chosen over Open WebUI due to better MCP support at the time. Still open: whether to replace AnythingLLM once native Obsidian plugin matures.

Don’t summarise the note here—that’s for the frontmatter. The Context section contains information that isn't obvious, such as motivation, follow-up decisions, and unresolved issues.

Why This Split Matters

There’s a reason for keeping these two things separate.

Frontmatter is machine-readable by default. Obsidian plugins, query tools, or RAG systems can grab fields without reading the whole note. When an agent scans your vault, it quickly reads all summaries. This is far more efficient than opening every note.

The Context section is for an agent, or my future self, who already knows the note is relevant and wants to understand its reasons. It captures details that might be forgotten if I didn’t write them down at the time.

Together, these two sections offer both the agent and me two entry points: a quick scan or a deeper exploration of the context. Most of the time, the summary suffices, but sometimes accessing both is necessary.

I started with this pattern in my Projects folder, which had about 64 notes. Then, I updated the rest of the vault bit by bit as I worked, so I didn’t need to do a big migration all at once.

The rules I follow:

Creating a note: always add both before saving.
Reading a note as an agent: check the summary first, only go deeper if needed
When updating a note, keep both sections up to date. An outdated summary is worse than no summary at all because it can mislead.
Bulk operations: scan all summaries first, then selectively read full notes

Now, instead of specifying which notes to read, I prompt agents to scan a folder, identify relevant topics from summaries, and only read full notes as needed, making the workflow efficient and natural.

Telling the Agent About the System

Setting up this pattern is important, but it’s not enough on its own. The agent also needs to know the pattern exists and how to use it. Otherwise, it will keep reading full notes.

For Claude Code, I use a CLAUDE.md file in the vault root, or an AGENTS.md file linked from it. Claude reads this file at each session’s start. It acts as a standing brief, explaining the vault before Claude does anything.

Here’s the instruction I use:

## Agent Navigation System
    
    All notes in this vault use a two-part system to allow efficient navigation
    without reading full notes.
    
    ### Frontmatter Summary
    
    Every note includes a `summary` field in its YAML frontmatter — 2-3 sentences
    capturing the core subject, purpose, and any key conclusions or status.
    
    ### End-of-Note Context Section
    
    Every note ends with a `## Context` section containing information that cannot
    be derived from reading the note itself: why it exists, what decision it informed,
    open questions, dependencies on other notes.
    
    ### Rules
    
    1. **Creating a note** — always add both the frontmatter `summary` and the
       `## Context` section.
    2. **Reading a note** — always read the frontmatter `summary` first. Only read
       the full note if more detail is needed. For bulk operations across multiple
       notes, read all frontmatter summaries before diving into full content.
    3. **Updating a note** — whenever the content changes, update both the
       frontmatter `summary` and the `## Context` section to reflect the current state.
    4. **Summaries must stay accurate** — a stale or inaccurate summary is worse
       than no summary.

Once the agent has these instructions, the two-part pattern becomes a shared protocol. The agent reads summaries first, reads full notes when needed, and keeps both sections up to date. I do the same when I make changes.

For other tools, like local LLMs with AnythingLLM or custom GPTs, add the same instructions to the system prompt. The details might change, but the idea is the same: the agent needs clear rules, not just hints from note structure.

The Unexpected Benefit

Adding the Context section has made my notes more useful for both agents and me. Months later, I often forget a note’s purpose or the decisions it entails. The Context section records my motivations and ensures that, whether for an agent or my future self, the note remains meaningful.

The Spec

If you want to adopt this in your own vault, here’s the full spec for implementing this method effectively.

Frontmatter summary:

2–3 sentences
Covers: core subject, purpose, key conclusions or status
Keep it accurate and update it if the note changes.

Context section (end of note):

Why the note exists
What was informed or decided
Open questions or unresolved threads
Dependencies on other notes or external systems
Anything an agent would need to act on this note correctly, without asking

What doesn’t go in Context:

A summary of the content (that’s the frontmatter)
Things that are obvious from reading the note

That’s the whole system, just two fields. It works for any vault size and only adds a little time to note writing. Once it’s a habit, it takes almost no extra effort.

Martyn Hodge