obsidian-vault-context v1.0.0

name: obsidian-vault-context description: "Pull bounded, citation-ready context packs from any personal Markdown knowledge vault (Obsidian-style) for a downstream agent: token budgets, source-grounded extraction, and a handoff contract. Triggers when an agent needs vault context for a follow-up agent, when a handoff needs every claim traceable to a note, or when note context must fit a hard token budget."

Obsidian Vault Context

Purpose

Given a query and a token budget, extract exactly the vault notes that answer the query, assemble them into a self-contained context pack, and attach a handoff contract so the downstream agent knows what the pack contains, what it does not, and which note every claim came from. Works on any Markdown vault that uses YAML frontmatter, tags, and wikilinks (Obsidian, Logseq-exported, plain Markdown notes).

Workflow

1. Read the request. Pull the query, the downstream agent's task, and the token budget. If no budget is given, default to 2000 tokens and say so in the handoff.
2. Map the vault. Walk the vault directory for .md files. For each note, parse the YAML frontmatter (title, tags, aliases, date, status) and the body. Resolve wikilink [[Note#Heading]] and ^block-id references so quotes can point at a section or block, not just a file.
3. Retrieve. Score sections against the query: exact term hits count most, then title/tag/alias matches, then wikilink neighborhood (notes linked to/from a hit get a small boost). Grade each candidate relevant, partial, or off-topic and keep only the first two. Cut anything dated, tagged archive, or with status: draft unless the requester asked for it.
4. Budget. Estimate tokens as characters / 4. Fill the budget greedily from the top-ranked section down. Put the single best section first and the second best last, weaker ones in the middle (long contexts get under-read in the middle). Stop when the next section would exceed the budget. Never silently overflow.
5. Extract quotes. For each kept section, copy 1-3 verbatim spans (the actual sentences that answer the query). Quotes are copied, never paraphrased, and never trimmed mid-sentence. Label every span with note path, section, and date from frontmatter.
6. Write the handoff. Emit the pack plus a handoff contract. Hand both to the downstream agent.

For the grading rubric, scoring details, and the full handoff schema, read references/method.md. For quick local packs, use the CLI: `bin/pack.py <vault> <query> --budget 2000`.

Output Contract

A finished pack always has four parts:

1. PACK: the quoted sections in rank order, each labeled with a stable source id (S1, S2, ...), note path, section heading, and frontmatter date.
2. COVERAGE: one line per sub-question of the query: covered by which source ids, or marked GAP when no note answers it.
3. GAPS: explicit list of what the vault did not contain, so the downstream agent does not mistake absence for evidence.
4. HANDOFF: the contract block below.

HANDOFF contract fields:

json
{
  "query": "the original question",
  "token_budget": 2000,
  "tokens_used": 1730,
  "source_count": 4,
  "vault_path": "/path/to/vault",
  "built_at": "2026-10-08",
  "instruction": "Answer only from the PACK. Cite claims as [S1], [S2]. A claim you cannot cite is uncertainty: say so."
}

Operating Rules

1. No citation, no claim. A fact in the downstream answer must trace to a source id in the pack. If the pack lacks it, the answer says so. This is the whole point.
2. Quotes are verbatim. Copy from the note. If you must shorten a span, cut whole sentences and mark the cut with [...].
3. Dates ride along. Every section label carries the note's frontmatter date (or undated). An old note next to a new one must be visibly old.
4. Budget is a ceiling, not a target. Stop early when the sections run out of relevance. Padding with weak sections wastes the downstream agent's attention.
5. Metadata is not evidence. Frontmatter tags and titles guide retrieval, but a claim needs a quote from the body, never just a tag.
6. Stay tool-agnostic. Never assume an Obsidian plugin, a Dataview query, or an embedding service. Plain file reads and string matching are the baseline; anything fancier is an optimization the method does not depend on.