Vault capture

<!-- CANONICAL SOURCE: this repo (jayantak/vaultmem). The dotfiles copy under agents-source/skills/ is synced FROM here — edit this file, not that one. -->

vault-capture — write it down so the next session doesn't re-derive it

The write side of the vault. Finding what's already there is vault-recall; keeping the vault healthy and deciding what's missing is vault-curate; per-thread working state is session.

Picking the vault

Never hardcode a vault path or id. vaultmem vaults prints the registry (id, root, sessions root, MOC, roles, routing rules); vaultmem which guesses the one that routes for the current repo/cwd. Work content → the work vault. Personal/generalizable learning → the personal vault. Ambiguous → state your inference and confirm before writing the first note, so a personal project never lands in the work vault or vice-versa.

Workflow B: Capture

Triggered when something worth documenting happens — debug root cause, architecture decision, incident response, meeting recap, project milestone, tool/infra setup, people context, generalizable learning, or explicit "make a note".

1. Pick the vault (above).

2. Check for an existing home first. vaultmem <keywords> from the topic. If a related note exists and the new content is on-topic for it, extend it (append a dated ### YYYY-MM-DD — <subtopic> section to the appropriate part of the note). Do not create a sibling.

3. If no good home exists, create a new note — see § Where notes go below for how to pick the folder. Do not assume a folder exists; discover the layout.

4. Update the Agent Index in Home.md in the same operation:

   • New note → add a row to the relevant ### <Section>: | [[Folder/Note]] | one-line summary |. Keep the summary terse — the index is a triage pointer, not a place to read the note.
   • Extended note where the summary line is no longer accurate → refresh the existing row's summary.

   The index update is part of the definition-of-done. A capture without an index update is incomplete.

5. If the vault keeps a daily log, append to today's entry. Not every vault has one — see § Where notes go.

6. Verify every link you wrote resolves — see § Definition of done below. This is not optional; it is what separates a real capture from a reported one.

Read before you edit. The Edit tool rejects writes to files you have not read with the Read tool in this conversation — the top recorded tool error in past sessions. vaultmem cat/bookmark do not satisfy that precondition: they are separate processes, so the Edit tool does not count them as a read. Use them for cheap inspection (checking what a note already says before deciding to extend it), then Read the file itself before the first edit.

Where notes go

Never assume a folder exists. Folder names are configurable per vault, and the guaranteed contract (SCHEMA.md) is small:

<vault-root>/
  Home.md       # the Agent-Index hub
  MOCs/         # Maps of Content — one "MOC - <Topic>.md" per domain hub
  Projects/     # one <name>.md per project (epic); type: project
  Sessions/     # one <thread>/_index.md per session (task)
  Templates/    # excluded from search + resolution

That is what vaultmem init scaffolds and all this skill can count on. Anything else is that vault's own convention, so discover the layout instead of guessing it: vaultmem vaults (roots, sessions root, MOC, routing), vaultmem index (the section names this vault actually uses — sections generally mirror folders, making this the cheapest read of the layout), vaultmem mocs (how it carves up topics even when folders are flat). If the vault root has a CLAUDE.md/AGENTS.md, follow it — the owner's own naming/template rules win over anything here. Many vaults have none; don't hunt twice.

Choosing a home:

• A note about an epic → Projects/. One task's working state → Sessions/ (the session skill owns that tier — don't hand-roll it).
• A domain hub with 8+ related notes under it → MOCs/MOC - <Topic>.md.
• Anything else → the existing section whose siblings look most like your note. Matching an established section beats inventing a folder. If nothing fits and there is no catch-all, put the note at the vault root and index it — a findable note in the wrong place beats a perfect folder nobody searches.

Optional layouts — only if your vault already has them

Richer vaults often add topical folders such as Debug/, Incidents/, Meetings/, Architecture/, People/, Areas/, Resources/, or an Inbox/. These are examples, not requirements — none is part of the schema. Use one only when vaultmem index or the vault's own CLAUDE.md shows it exists. When they are present: event-shaped notes (Meetings/, Incidents/) date-prefix the filename YYYY-MM-DD - <Title>.md so the folder sorts chronologically (an aggregator uses the earliest date it covers); state-tracking notes (Debug/, Architecture/, People/) use plain descriptive titles; extending an existing un-prefixed note leaves the filename alone unless asked. If the vault keeps a daily log (Daily/YYYY-MM-DD.md), append - **HH:MM** — Brief description → [[Folder/Note Title]] under ## Notes, creating today's entry from its daily template if missing.

The Zettelkasten pattern (optional)

Some vaults keep a flat folder of atomic notes where structure comes from links rather than hierarchy — one idea per note, timestamp-named (YYYYMMDDHHMM <Title>.md), frontmatter type: zettel, a ## Related footer. If a vault has one, it is the right home for generalizable insight: a pattern, mental model, or trade-off framework you'd want again in six months, as distinct from a project-specific fact. A debug session's durable lesson ("socket exhaustion causes OOM under backpressure") is a zettel; the ticket it came from is not. If the vault has no such folder, don't create one unprompted — capture the insight as an ordinary note and link it from the relevant MOC. The value is the atomicity and the links, not the folder name.

Cross-vault rule: no cross-vault wikilinks — they always dangle. Reference the other vault as plain text.

Don't Document

• Routine git commits with no insight beyond the diff
• Ephemeral conversation state (questions asked, tool calls made)
• Facts trivially re-discoverable in under 30 seconds via search

When in doubt, capture it. An extra note is cheap; a lost insight is not.

Linking Rules

Obsidian wikilinks are not free text — they resolve to a real file or they dangle. Get this wrong and the link is dead (red in the graph, no backlink).

How resolution works — the rule that matters most:

• [[Target]] resolves only if some note's exact basename (filename minus .md, case-insensitive) OR a frontmatter alias equals Target. There is no fuzzy match. [[Payments]] does NOT find MOC - Payments.md unless that note has aliases: [Payments].
• Never invent or paraphrase a link target. Before writing [[X]], confirm X is a real basename/alias — vaultmem mocs (exact MOC names), vaultmem index (Agent Index), or vaultmem <X>. If you just created the note, copy its exact title into the pointer; do not retype it from memory (this is the #1 source of dangling links — the note gets one name, the pointer another).
• [[Folder/Note]] and [[Note]] resolve to the same file (Obsidian matches on basename); the path prefix is optional and only disambiguates duplicate basenames. Either is fine as long as the basename matches.
• Display text: [[Real Basename|shown text]] — the part before | must resolve; the part after is cosmetic.

Conventions:

• All internal vault links use [[wikilinks]]. Never markdown-style links for vault notes.
• MOCs are linked by their real filename [[MOC - <Topic>]], or by a short alias the MOC declares (e.g. a MOC - Payments.md that declares aliases: [Payments]). Do not link a bare topic name unless that alias exists.
• People links: [[Name]] only if a note for that person exists (some vaults keep a People/ folder, many don't). If there is none, create a stub from the vault's person template if it has one, or use plain text — don't leave a dangling link.
• Repo artifacts are NOT vault notes. ADR IDs (ADR-00093), source paths (packages/…), PR numbers (#3383) live in the repo, not Obsidian — write them as inline code or a real URL, never as [[wikilinks]]. [[ADR-00093]] will always dangle.
• External links (Jira, Datadog, GitHub) use plain URLs or markdown links.
• No cross-vault wikilinks — a work↔personal [[link]] always dangles. Reference the other vault as plain text.
• Project ↔ Session. A session links its epic as **Project:** [[<name>]] where <name> is the exact basename of Projects/<name>.md. The Project's ## Sessions index links back as [[<thread>]]. That back-link resolves only because the session declares aliases: [<thread>] — the session file is Sessions/<thread>/_index.md, so its basename is _index, not the thread name. A session without that alias is unlinkable: every [[<thread>]] to it dangles. Verify both directions — vaultmem resolve "<name>" and vaultmem resolve "<thread>" — before collapsing or committing. Never wikilink a Linear issue id or URL (plain text: PROJ-1234).

Definition of done for any link you write: the target resolves

When you finish a capture, verify it — don't eyeball it:

• vaultmem resolve "<Target>" — confirms a single [[link]] you wrote (e.g. the MOC you filed under, a note you cross-linked) points at a real file. Non-zero exit means it dangles; fix the basename or create the target.
• vaultmem dangling <note> — lists every broken outbound link in a note you just wrote or edited. Run it before declaring the capture done.
• vaultmem verify <file> — the same dangling check plus the doctor schema lints, scoped to one file. Useful on a Session or Project note, where the frontmatter contract is enforced and a missing aliases: makes the note unlinkable.

This catches the most expensive failure mode in this system: an agent (often a background capture subagent) reports creating a note it never wrote, leaving the index/MOC wikilinks dangling. If you write → promoted to [[X]] or add a [[X]] to a MOC, X.md must exist on disk — resolve/dangling prove it. Never trust a subagent's "created the note" claim without a resolve check.

Frontmatter

At minimum:

---
title: Descriptive Title
date: YYYY-MM-DD
tags:
  - relevant-tag
---

Sessions and Projects carry additional required fields — thread/status/ updated and aliases on a Session, type/status on a Project. SCHEMA.md is normative there, and vaultmem doctor enforces it (see vault-curate). If the vault root has a CLAUDE.md/AGENTS.md, follow any further conventions it documents (tag prefixes, type fields); many vaults have none.

Workflow C: Session Capture (subagent)

Triggered when a parent agent spawns you at a logical stopping point to capture session work. The parent passes a structured summary (what happened, key details, category, vault). This is the most common invocation path — agents are instructed to spawn capture subagents proactively.

1. Invoke this skill. The subagent must load vault-capture to get vault routing, conventions, and the verification contract.
2. Parse the parent's summary. Extract: what happened, category, vault.
3. Follow Workflow B from step 1 (pick vault) onward. Treat the parent's category as a hint, not a folder name: resolve it against the sections this vault actually has (vaultmem index) per § Where notes go. project maps to the schema's Projects/; the rest (debug, architecture, incident, meeting, people, zettel, …) only have a folder if this vault made one.
4. Check for generalizable insight. If the work produced a lesson that outlives the project (not just a project-specific fact), capture it as its own note — in the personal vault if that's where durable learning lives, even when the primary capture goes to the work vault.
5. Complete all three artifacts: note (new or extended), Agent Index update, daily note append — then run the resolve/dangling verification above. A subagent that reports a note it did not verify is the documented failure mode.

Multiple captures in one invocation

If the parent's summary covers multiple distinct topics (e.g. "fixed a bug AND decided on a new architecture"), create separate notes for each. Don't merge unrelated content into one note — atomicity matters.

Workflow D: Repo onboarding (project memory)

Triggered by "build project memory", "set up agent memory for this repo", "onboard this project into Obsidian", "remember this project", starting work in an unfamiliar repo, or noticing an agent re-derive the same project context every session. This is a capture with a specific shape: a pointer-based Map of Content for one repository, so any future session starts warm.

The one principle: signpost, don't duplicate

The repository is on disk and is the source of truth for how the code works. Obsidian must hold only what the repo can't tell you:

• WHY — decisions, rejected alternatives, constraints, the rationale a diff never captures.
• WHERE — a map: where things live in the repo + the external systems (Linear, Datadog, AWS, dashboards, datalake).
• GOTCHAS — operational traps, footguns, "this will bite you" that aren't visible in the code.
• WHO — owners, stakeholders, who to ask about what.
• GLOSSARY — domain terms and acronyms a newcomer won't know.
• STATE — what's in flight right now and where it's heading. Active work groups under a Project note (Projects/<name>.md — the epic tier that owns the repo list and whose sessions distill upward; see the session skill). The MOC is the domain map (top tier); link the relevant [[<Project>]] from the MOC's state section rather than duplicating its session log here.

Never restate code, API shapes, file contents, or anything regenerable by reading the repo. Every note points to the authoritative source (a repo path, a PR, a ticket, a URL) and adds the context that source lacks. If a fact is trivially re-discoverable in the repo in under a minute, it does not belong in Obsidian — point at it instead.

Steps

1. Orient + pick the vault (cheap, before asking anything). Identify the repo: name, git remote, primary languages, top-level layout, and existing docs (README, docs/, adr/, CLAUDE.md/AGENTS.md). Read what's there; don't ask the user anything the repo already answers.

   First-run vs. re-sync. Check whether MOCs/MOC - <Project>.md already exists in the chosen vault. If it does, this is a re-sync, not a first run — do NOT re-interview from scratch and do NOT rewrite the hub. Read its drift anchor, diff the repo against it, and update only what moved. See § Re-syncing (diff, don't rewrite) and skip the full grill (step 2) in favor of the much shorter re-sync interview there.

   Choose the target vault — route by the registry's match rules (vaultmem vaults / vaultmem which): a work repo (git remote under your work org, or clearly work-related) → the work vault; a personal / side project → the personal vault; ambiguous → ask, stating your inference first.

   Then read the chosen vault's CLAUDE.md + Home.md and follow its conventions (each vault's folders and Home differ). If that vault has no MOCs/ folder + ## Maps of Content layer yet, create it.

2. Grill — extremely detailed, one question at a time. Walk the question tree in references/question-tree.md. Ask one question at a time, always offer a recommended/default answer, and skip any branch the repo already answered in step 1. The goal is to extract the non-obvious, in-your-head knowledge — not to transcribe the code.

3. Decide the structure and detail level. Size the footprint to the project using references/structure-rubric.md. A small/stable repo may warrant only a MOC + a gotchas note. A large, active one warrants the full set. Default to fewer, denser, pointer-first notes.

4. Write to the chosen vault. Use the conventions above (frontmatter, Linking Rules, folders, the Agent Index = definition-of-done). Create:

   • MOCs/MOC - <Project>.md — the entry-point hub (always).
   • A small set of signpost notes only where step 3 says they're warranted (decisions, gotchas/field-guide, glossary, people, where-truth-lives).
   • Stamp the drift anchor (always, first run and every re-sync): record where the memory was last reconciled with the repo so the next run can diff instead of re-deriving. See § Re-syncing.
   • Update the target vault's Home.md: add the MOC to the ## Maps of Content section (one line of orientation) and add rows to the Agent Index for any new notes.
   • Append to today's daily note in that vault, if it keeps one.

5. Confirm and hand off. Verify the links resolve (§ Definition of done), tell the user what was created, and run vaultmem mocs so they can see it registered.

Re-syncing (diff, don't rewrite)

A MOC is a snapshot. The repo moves; the snapshot rots. A first run with no way to tell what rotted forces the next run to re-read everything or, worse, to trust stale "as of" claims. The fix is a drift anchor: a small, machine- checkable record of where the memory was last reconciled with the repo, so any later run can diff forward and touch only what changed.

Every MOC carries a drift anchor (first run included — so re-runs have something to diff against). Put the machine-readable part in frontmatter and a human/agent-readable "how to re-sync" block in the body:

# frontmatter
last_synced: 2026-06-01
synced_commit: ad452a08f      # short SHA the body claims were reconciled to

The body block records the baselines a re-run should diff against — pick the handful that actually signal drift for this repo (counts, a release line, the HEAD it was synced to, the active ticket areas) and the exact command to check each. Generic skeleton (adapt per repo — see an existing filled-in MOC in your vault for an example):

## Drift anchor — re-sync before trusting "as of" claims

Last synced **2026-06-01 @ `ad452a08f`** · <N ADRs> · <release line> · <active areas>.
On a re-run, **diff first, update only what moved, then re-stamp this anchor**:

- Changes since:  `git log ad452a08f..HEAD --oneline`
- New ADRs/docs:  `git diff --name-only ad452a08f..HEAD -- docs/adr/`
- New release line: newest `Production Release: X.Y.Z` vs the one above
- Active-work shift: `git log ad452a08f..HEAD --oneline | grep -oE '\(<TICKET-RE>\)'`

The re-sync interview is short. Most drift is in the repo (git answers it). Ask the user only what git can't: "since <last_synced>, what changed in the why / who / direction that wouldn't show up in a diff?" (a re-org, a new owner, a killed initiative, a constraint that lifted). Then:

1. Run the anchor's diff commands; map each changed area to the MOC section it affects (new ADRs → Gotchas/decisions; new release line → Active work; new ticket prefixes → Active work; moved files → Where-the-truth-lives).
2. Edit in place, surgically. Update the drifted lines; do not rewrite untouched sections; never duplicate a section "as an update."
3. Re-stamp the anchor (frontmatter last_synced/synced_commit + the body baselines) and bump any "as of YYYY-MM-DD" you touched.
4. If a whole subsystem appeared since last sync, then promote it to its own signpost note (per the rubric) and link it from the MOC.

Same frugality bias as a first run: point, don't paste; surgical, not wholesale.

What to create (detail tiers)

Artifact	Always?	Detail level
MOCs/MOC - <Project>.md	Yes	Map. 1–2 lines of orientation per linked note/section so an agent knows where to dig. Dense pointers, no code.
Drift anchor (frontmatter + section in the MOC)	Yes	last_synced/synced_commit + a "how to re-sync" block with the diff baselines & commands. Lets the next run diff instead of re-deriving. See § Re-syncing.
Where-truth-lives section (in the MOC)	Yes	Terse routing: repo (+ how to fetch), Linear, Datadog, AWS targets, datalake, dashboards.
Decisions / why	If real trade-offs exist	Medium: the decision, the why, what was rejected & why, link to ADR/PR/ticket. No implementation detail.
Gotchas / field guide	If operational traps exist	Medium: terse bullets, each "symptom → cause → where to look (repo path)".
Glossary	If domain jargon is heavy	Terse: term → one-line meaning → where it lives in code.
People / ownership	If >1 stakeholder	Terse: name → role → owns → when to ping. Use [[People/Name]].

Full rubric (when to create each, how to size by project complexity) is in references/structure-rubric.md.

Frugality rules (repo onboarding)

• Point, don't paste. A note that reproduces a repo file has failed.
• One MOC per project is the entry point; everything hangs off it.
• Promote, don't pre-build. Start with the MOC; add signpost notes only as the interview surfaces real, durable, non-obvious knowledge.
• Date what rots. Anything that will drift (current state, "as of") gets a date so a future agent knows to re-verify against the repo.
• Re-running is a diff, not a rewrite. On a second pass, read the drift anchor, diff the repo against it, and edit only the drifted lines in place — then re-stamp the anchor. Never re-interview from scratch or duplicate a section.

Handing off

• Need to find what's already written before capturing? → vault-recall.
• Wondering what to write next, or whether the vault is rotting? → vault-curate.
• Capturing per-thread working state that must survive /clear? → session.