---
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.