For Humans: What This Is

This document is designed to be fed directly to Claude Code as context for navigating your knowledge base.

If you use Claude Code with an Obsidian vault (or similar markdown-based knowledge base), you can:

  1. Structure your vault with “hub files” that act as indexes for different domains (photography, work, health, projects, etc.)
  2. Point Claude Code to this document in your CLAUDE.md or similar orientation file
  3. Claude Code will then navigate your vault efficiently - reading hub files first, following explicit links to detailed pages, rather than randomly searching or loading everything upfront

This solves the “context pollution” problem where AI agents either read too little (making generic assumptions) or too much (wasting tokens on irrelevant content).

The pattern is analogous to MCP tool search (announced by Anthropic on January 15, 2026) but applied to knowledge retrieval instead of tool discovery.

To use: Copy this document into your vault, adapt the “Typical Vault Structure” section to match your folder organisation, and reference it from your CLAUDE.md.

Purpose (For Claude Code Agents)

Instructions for Claude Code agents on how to navigate knowledge bases structured with hub files and hierarchical linking. Optimised for Obsidian vaults but applicable to any markdown-based knowledge base.

Core Pattern

Hierarchical lazy loading - analogous to MCP tool search, but for knowledge retrieval.

Principle

Do not load all files in a directory upfront. Navigate through intentional structure:

  1. Read orientation file (e.g., CLAUDE.md)
  2. When task involves specific domain, read hub file for that domain
  3. Follow explicit links from hub files to detailed pages
  4. Continue following links until context is sufficient

Bias

Bias toward reading MORE context, not less. Insufficient context leads to incorrect assumptions and wasted rework. Token cost of reading 2-3 extra files < time cost of fixing incorrect actions.

Three-Tier Structure

Tier 1: CLAUDE.md (or equivalent orientation file)
  - Always loaded by default
  - Points to hub files for specific domains
  - Contains high-level navigation instructions

Tier 2: Hub files (e.g., 07 System/Context - [Domain].md)
  - Entry point for domain-specific context
  - Contains overview + links to detailed pages
  - Does NOT contain exhaustive detail

Tier 3: Detailed pages (Projects/Areas/Resources)
  - Specific implementation details
  - Referenced by hub files via explicit links
  - Read when hub file points to them

Hub File Structure

Each hub file should follow this pattern:

  1. Overview - Current state in domain
  2. Key information - Critical details (gear, people, systems, practices)
  3. Links to detailed pages - Explicit references to where more information lives
  4. Current priorities - What’s active right now

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

When to Read Hub Files

  • User asks about specific domain (photography, travel, health, technical infrastructure, etc.)
  • Task requires understanding user’s preferences/context in that domain
  • Need to understand existing structure before making changes
  • Uncertain about domain-specific conventions
  • Hub file explicitly references detailed page with “See [[Page]]” or similar
  • Hub file overview insufficient for task completion
  • Need specific implementation details not in hub file
  • When uncertain after reading hub file

When to Stop

  • Read hub file + 2-3 linked detailed pages (typical stopping point)
  • Further reading clearly tangential to task
  • Starting to read archive files or distant connections
  • Have sufficient context to answer question or complete task

Stopping Criteria Decision Tree

After each file read, evaluate:

  1. Can I answer user’s question or complete task with current context?

    • YES → Stop
    • NO → Continue to step 2

  2. Does hub file or 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/context in this domain?

    • YES → Follow available links, read 1-2 more files
    • NO → Stop

Anti-Patterns

❌ Loading Everything Upfront

Bad: Glob all files in 04 Areas/Photography/, read all matches
Good: Read Context - Photography.md, follow links to specific topics

Reading all files in a directory = context pollution. Navigation should be guided by hub structure, not directory structure.

❌ Stopping Too Early

Bad: Skim CLAUDE.md, see path reference, stop
Good: Read referenced hub file, follow links to workflow details

Insufficient context leads to generic recommendations that don’t fit user’s actual system.

❌ Ignoring Links in Hub Files

Bad: Read hub file overview section, stop
Good: Follow links hub file explicitly mentions for relevant topics

Hub files point to detailed pages for a reason. Links are intentional navigation cues.

❌ Making Assumptions Without Context

Bad: User asks about training plan, provide generic advice
Good: Read Context - Health & Optimisation.md, follow links to current training protocol

Generic advice from LLM training data < specific advice based on user’s documented preferences.

❌ Guessing File Locations

Bad: Try reading /path/to/guessed/file.md
Good: Read hub file which explicitly lists/links relevant files

Hub files are the index. Use them.

Cache Levels Analogy

Think of context like CPU cache:

  • L1 (always loaded): CLAUDE.md orientation
  • L2 (load on domain access): Hub files in 07 System
  • L3 (load on specific need): Detailed pages in Projects/Areas
  • L4 (load rarely): Individual notes, resources, archives

Fetching from L4 without checking L1→L2→L3 first = inefficient navigation.

Missing L2 entirely and jumping to L3 (reading random detailed files) = worst outcome. You get fragments without the map that connects them.

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

Key Distinction

“Loading everything” vs “Following links”:

  • Loading everything = Reading all files in directory before understanding structure (brute force, context pollution)
  • Following links = Navigating through intentional structure hub files provide (guided exploration, efficient)

“Minimize context” vs “Bias toward more”:

  • Minimize context = Stop at first minimal viable information (risks incorrect assumptions, generic advice)
  • Bias toward more = Read hub + linked pages to understand thoroughly (costs tokens, saves rework, enables specific advice)

Token Cost vs Correctness

Context consumption costs tokens. Incorrect actions from insufficient context cost user time.

Token cost is O(cents). User’s time is expensive (regardless of dollar value).

Reading 2-3 extra files costs ~$0.10 in tokens. Rework from incorrect assumptions costs minutes to hours of user time.

Optimise for correctness, not token minimisation.

Typical Vault Structure

Example structure (adapt to your vault organisation):

/your/vault/path/
├── System/              # Meta-docs, context files, vault config
│   ├── Context - [Domain A].md
│   ├── Context - [Domain B].md
│   ├── Context - [Domain C].md
│   └── README - Context Navigation.md
├── Projects/            # Active work with defined end states
├── Areas/               # Ongoing responsibilities (no end state)
├── Resources/           # Reference material
└── Archive/             # Historical, completed, cold storage

Hub files (the Context - [Domain].md files) live in a System/Meta directory. They contain:

  • Overview of that domain
  • Key information (gear, tools, processes, people)
  • Links to detailed pages elsewhere in vault
  • Current priorities

Hub file naming examples:

  • Context - Work.md or Context - [Your Job].md
  • Context - Photography.md or Context - [Your Hobby].md
  • Context - Health.md or Context - Fitness.md
  • Context - Technical Setup.md or Context - Infrastructure.md
  • Context - Travel.md or Context - [Interest Area].md

Adapt to your domains. The pattern matters more than the specific names.

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 hub file)
  • Glob: When looking for files matching pattern (use sparingly, prefer hub file references)
  • Task + Explore agent: When navigating unfamiliar territory or answering open-ended questions about knowledge base structure

Summary

Navigation pattern: CLAUDE.md → hub file → linked detailed pages → stop when sufficient.

Bias: Read more rather than less. Hub files are indexes. Links are intentional navigation cues. Insufficient context costs more than extra tokens.

Anti-patterns: Loading everything upfront, stopping too early, ignoring links, guessing file locations, making assumptions without reading documented context.

Typical stopping point: Hub file + 2-3 linked detailed pages.

Implementation reference: See 07 System/README - Context Navigation.md in your vault for extended implementation details, examples, and anti-pattern demonstrations.

Related: CLAUDE.md contains navigation philosophy at high level. This document provides technical implementation details.

Series: Claude Code + Obsidian