Vault Query

Vault Query — Karpathy-Style Knowledge Synthesis

Based on the "compile, don't retrieve" philosophy: look up the index first, read full text to synthesize, write back high-value answers.

Workflow

Step 1: Environment Detection & Query Parsing

1a. Detect vault root — follow [../../shared/common-steps.md](../../shared/common-steps.md) "Vault Detection" section.

1b. Parse user query intent:

Extract from user input:

• query: core question or keywords
• scope: whether a directory scope was specified (e.g., user mentions a topic that maps to a configured directory)
• depth: simple lookup ("which article covers X") vs deep synthesis ("compile everything about X")

Step 2: Index Lookup

2a. Read index.md:

Read("$VAULT_ROOT/index.md")

Scan all entries in index.md — titles, summaries, and tags — to find candidate articles related to the query (typically 3-8).

2b. Supplementary search:

index.md may miss content. Use Grep to supplement:

Grep("{keyword}", path="$VAULT_ROOT", glob="**/*.md")

Exclude results from .claude/, .git/, reviews/, index.md.

2c. Determine reading list:

Merge index lookup and Grep results, sort by relevance, finalize the list of articles to read in full.

Step 3: Deep Read & Synthesis

3a. Read relevant articles in full:

For each article on the reading list, use Read to get full text. Read in parallel for efficiency.

3b. Synthesize the answer:

Choose synthesis mode based on depth:

• Simple lookup: list relevant articles and their key points, point the user to read directly
• Deep synthesis:

1. Extract key information from multiple articles
2. Integrate into a complete knowledge picture, citing sources (see [[article-name]])
3. Surface connections, contradictions, or complementary relationships between articles
4. Identify knowledge gaps ("no article covers aspect Y of topic X")

Step 4: Write-Back Decision

After synthesizing, evaluate whether writing back is warranted:

Worth writing back:

• Synthesized new insights across 3+ articles
• Discovered undocumented connections between articles
• The user's question reveals a knowledge gap worth filling
• Produced a reusable comparison analysis or decision matrix

Not worth writing back:

• Simple lookup ("which article covers X")
• Answer comes entirely from a single article
• One-off question

4a. If worth writing back, use AskUserQuestion to ask:

> "This query produced valuable synthesized knowledge: {brief description}. Save as a new note? Suggested title: {title}, directory: {dir}/"

Upon user confirmation:

1. Determine directory per the Directory Mapping Rules in [../../shared/common-steps.md](../../shared/common-steps.md)
2. Search for bidirectional links per Bidirectional Link Search
3. Write the new note with complete frontmatter:

• title: synthesis note title
• date: today's date
• tags: 3-8 relevant tags
• type: inferred per Type Inference Rules in [../../shared/common-steps.md](../../shared/common-steps.md)
• confidence: cross-article synthesis is typically medium
• related: source article list ("[[article-name]]" format)
• summary: 1-3 sentence synthesis summary
• source: "Vault Query synthesis"

1. Update index.md: per the Index Update steps in [../../shared/common-steps.md](../../shared/common-steps.md), append the new article to the corresponding section

Step 5: Report

Output to user:

• Synthesized answer (with [[wikilink]] citations)
• List of referenced articles
• If written back, report the save location
• If knowledge gaps were found, suggest topics to add

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Howie126313
• Source: Howie126313/obsidian-vault-kit
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.