Once your vault hits hundreds of files, Claude Code can’t read everything and shouldn’t try. Loading a whole directory wastes tokens on irrelevant content and drowns the signal in noise.

The solution is hierarchical lazy loading - navigate through intentional structure rather than brute-force search.

The Pattern

Think of your vault like CPU cache levels:

LevelWhatExampleWhen to load
L1Orientation fileCLAUDE.mdAlways (auto-loaded)
L2Hub files07 System/Context - Photography.mdWhen task involves that domain
L3Detailed pages04 Areas/Photography/Portfolio Strategy.mdWhen hub file links to it and you need specifics
L4Individual notesRandom files in Resources/ArchiveRarely - only when L1-L3 point there

Fetching from L4 without checking L1→L2→L3 first is like reading random files and hoping they’re relevant. Reading L2 (the hub file) first gives you the map.

How It Works in Practice

  1. Claude starts a session, reads CLAUDE.md (always loaded)
  2. You ask about photography
  3. Claude reads Context - Photography.md (the hub file)
  4. The hub file links to Portfolio Strategy.md, Gear Notes.md, Workflow.md
  5. Claude reads the 1-2 linked pages relevant to your question
  6. Stops - typically hub + 2-3 linked pages is enough

Hub files are indexes, not encyclopaedias. They point to where information lives; they don’t contain all of it.

Anti-Patterns

Don’tDo instead
Glob all files in 04 Areas/Photography/, read all matchesRead Context - Photography.md, follow links to specific topics
Skim CLAUDE.md, see a path reference, stopRead the referenced hub file, follow links to relevant detail
Read hub file overview section, stopFollow the links the hub file explicitly provides
Ask about training plan, give generic adviceRead Context - Health.md, follow links to current protocol
Guess file pathsUse hub files as the index - they list what exists and where

The common thread: hub files are the navigation layer. Use them.

Bias Toward More Context, Not Less

Reading 2-3 extra files costs cents in tokens. Acting on incorrect assumptions from insufficient context costs minutes to hours of rework.

When uncertain, read another file. The cost of over-reading is low; the cost of under-reading is high.

Agent reference: implementation details for Claude Code

Stopping Criteria Decision Tree

After each file read, evaluate:

  1. Can I answer the user’s question with current context?
    • YES → Stop
    • NO → Continue to step 2
  2. Does the current page explicitly link to additional detail I need?
    • YES → Read linked page
    • NO → Continue to step 3
  3. Am I uncertain about user’s preferences in this domain?
    • YES → Follow available links, read 1-2 more files
    • NO → Stop

Tool Selection

  • Read: When you know exact file path from hub file or CLAUDE.md
  • Grep: When searching for keywords across unknown files (use to find hub file, then read it)
  • Glob: When looking for files matching a pattern (prefer hub file references)
  • A sub-agent: When navigating unfamiliar territory or answering open-ended questions

Implementation Checklist

When task involves domain-specific knowledge:

  • Check CLAUDE.md for reference to hub file for that domain
  • Read hub file (e.g., Context - Photography.md)
  • Note which topics hub file explicitly links to
  • Read linked pages for topics relevant to current task
  • Stop when context sufficient (typically hub + 2-3 linked pages)

When uncertain where to start:

  • Use Grep to search for keywords in markdown files
  • Identify hub file from search results
  • Read hub file to understand structure
  • Follow links from hub file rather than reading all search results

Typical Vault Structure

/vault/
├── 07 System/
│   ├── Context - [Domain A].md
│   ├── Context - [Domain B].md
│   └── Context - [Domain C].md
├── 03 Projects/
├── 04 Areas/
├── 05 Resources/
└── 06 Archive/

Hub files live in System. They contain: overview of that domain, key information, links to detailed pages elsewhere, current priorities.

Series: Claude Code + Obsidian