ReadyCIO
Menu

MyVault

Build your own knowledge vault

A complete, step-by-step guide to building a personal "second brain" for AI-assisted development — a git-backed markdown vault written by your Claude Code sessions, for your Claude Code sessions. Every prompt you need is here, ready to copy and paste. Nothing from my vault's contents is included; this is the functional process to build the same system yourself, empty and ready for your own knowledge.

For both Updated August 30, 2026

Shortcut for the impatient: the whole build prompt is served as plain text at readycio.com/vault-guide/prompt.txt. In Claude Code, say "Fetch https://readycio.com/vault-guide/prompt.txt and follow it to build my vault in this repo" and it does the rest. The guide below is what it follows.

Why I built this

I kept solving the same hard problems twice. My AI coding sessions would crack something genuinely difficult — a row-level-security authorization trap, a realtime subscription that connected but silently delivered nothing, a migration playbook for porting an app off a no-code platform — and three weeks later a fresh session would solve it again from scratch. Sometimes differently. Sometimes worse. Chat history doesn’t transfer between sessions, my own memory doesn’t scale, and the knowledge existed once and then evaporated.

So I built a vault: a private GitHub repo of small, linked markdown notes that my Claude Code sessions write and read. When a session solves something hard, one command distills it into a note. When a future session starts a task, the vault’s index is already in its context and it pulls the relevant notes before designing anything — even when I don’t think to ask. The vault has caught bugs before they were written, recalled migration playbooks I’d forgotten existed, and turned one-off lessons into standing conventions.

The whole thing is plain markdown and git. No database, no Notion, no Obsidian dependency, no infrastructure. That’s a deliberate decision, and this guide explains why.

What it does

The vault runs on four self-maintaining loops, each one a Claude Code skill:

  1. Save (/vault-save) — after solving something, one command distills it into a typed, linked note: the what, the why, the gotchas, the hard-won specifics. Not a transcript. A mandatory conflict check stops the save if the new knowledge contradicts an existing note — you decide whether you changed your mind or the new info is wrong.
  2. Surface (ambient recall) — a session-start hook injects the vault’s index (one line per note) into every session, and a standing rule obliges the model to recall relevant notes before designing from scratch, even when the vault wasn’t mentioned. This is the piece most setups miss: you can’t recall what you don’t know exists, and you will forget what you’ve saved. /vault-recall also works on demand.
  3. Wrap (/vault-wrap) — end of a build session, one command writes the retrospective: what was built, the route taken, dead ends worth not repeating, “do it this way next time.” Draft shown to you before saving — the vault only gets reviewed knowledge.
  4. Sweep (/vault-garden) — a periodic audit for near-duplicates, contradictions, broken links, one-way backlinks, and stale index lines, because write-time discipline alone drifts. Report-first: it proposes, you approve.

On top of the loops, optional upgrades this guide also covers:

  • /vault-wire — stamps any project repo so its future sessions (including cloud sessions) automatically recall from and save to the vault, and distributes shared skills into the repo.
  • /vault-atlas — a visual map of the vault: every note a node, every link an edge, published as a Claude artifact. Seeing the real link graph exposes structural gaps that reading notes never does.
  • A CI audit — a small script plus a GitHub Action that mechanically enforces the linking and index conventions on every push.

Everything — conventions, skills, templates — lives inside the vault repo, so cloning the repo installs the whole system. Any machine, any cloud session, any AI tool that can reach the repo gets the vault and its automation with it.

One design, solo or team. The vault you build here is team-capable from day one — every note names its author, conflicts route to that author, five people can push to it without stepping on each other — and all of that collapses to nothing extra when the contributors file has one line. So there is one guide, not two: wherever a choice differs for a team, a Just you? note says what to skip. (Why this is a superset rather than a fork, and what the team pieces are, is in the “A vault for a team” section below.)

Why plain markdown + git

Decided on day one, after debating Obsidian, Google Drive, and a database:

  • A second brain’s value is atomic notes + links + traversal. Markdown with [[wikilinks]] gives all three for free; anything heavier adds friction to the save path, and friction kills capture.
  • Git is the interoperability layer: every machine, every cloud session, every AI tool — even a different AI account — can read and write it. Access is a GitHub permission question, nothing more.
  • History is free: superseded knowledge is preserved in git without cluttering the live notes.
  • Claude Code reads, greps, and edits files natively. No retrieval infrastructure to build before reaching parity.

Revisit only if grep-and-link-traversal recall stops being good enough — likely threshold is several hundred notes needing fuzzy semantic search, at which point add a search index on top, never as the source of truth.

Step 0 — Prerequisites

  • A GitHub account and git installed locally.
  • Claude Code — the CLI on your machine, and/or cloud sessions at claude.ai/code with the GitHub connector authorized against the account that will own the vault.
  • 30–60 minutes. Most of the work is done by the build prompt below.

Just you? A personal GitHub account is the right home. A team? The repo must live in the company GitHub org — a vault under an individual’s account leaves with them, which is the exact failure a team vault exists to prevent — and every engineer’s Claude GitHub connector is authorised against that org (Step 3 covers the rest).

Multi-account gotcha (cost me real time): if your machine’s gh CLI is authenticated as a different GitHub account than the one owning the vault repo, operations fail confusingly. Check gh auth status first; gh auth login the owning account and gh auth switch --user <owner> if needed.

Fresh-machine gotcha: on a Mac (or any machine) that has never talked to GitHub before, git clone git@github.com:... — or gh repo create --clone before gh itself is authenticated — fails with Permission denied (publickey). That error means the machine has no SSH key registered with GitHub yet; it is not a sign anything is broken. Don’t hunt for or generate an SSH key to fix it — run gh auth login first, before any clone attempt:

brew install gh   # if gh isn't already installed
gh auth login      # GitHub.com → HTTPS → "Yes" to authenticate git with your
                   # GitHub credentials → login with a web browser

That sets up an HTTPS git credential helper, so every clone after it — gh repo create --clone or a plain git clone https://github.com/<owner>/<repo> — works with no SSH key involved. If you’ve already hit the publickey error, this same login step fixes it; no need to start over.

Step 1 — Create the repo

Once gh auth login has run (Step 0), one command creates and clones the repo:

gh repo create MyVault --private --clone && cd MyVault

(Or create an empty private repo in the GitHub UI and clone it over HTTPS: git clone https://github.com/<owner>/MyVault.git.) For a team, gh repo create <org>/<name> --private --clone — same command, org prefix. Open Claude Code in that directory.

Step 2 — Build the vault core (Prompt 1)

Paste the whole prompt below into Claude Code, replacing <GITHUB_USER> (your user, or the org for a team) and <VAULT_REPO> throughout. It builds the structure, the constitution (CLAUDE.md), the four core skills, the ambient-recall kit, a local-machine installer, and runs an end-to-end test. The prompt asks for your GitHub handle: that becomes the first CONTRIBUTORS.md line and the vault-owner.

Shortcut — skip the pasting. This prompt (with the optional upgrade prompts appended) is served as plain text at https://readycio.com/vault-guide/prompt.txt. In Claude Code, just say: “Fetch https://readycio.com/vault-guide/prompt.txt and follow it to build my vault in this repo — my GitHub user is <you>.” Claude reads the instructions itself; the text below is exactly what it will follow.

Build my personal knowledge vault in this repo. Work through the steps in
order, committing as you go (`vault: <what>` messages, push directly to
main — this repo is notes, not an app; no branches, no PRs).

### 1. Structure

raw/          # inbox/archive for original sources — read once at ingestion, provenance only
wiki/
  features/   # app features built (what, how, gotchas, reuse notes)
  patterns/   # reusable code/design/architecture patterns
  decisions/  # decisions made and the reasoning behind them
  learnings/  # general knowledge distilled from ingested sources
templates/    # copy-paste kits (hooks, CLAUDE.md blocks) for wiring the vault in
index.md      # the map: one line per note — `- [[slug]] — hook`
CONTRIBUTORS.md   # one line per writer: `- handle — Name — active | left YYYY-MM-DD`
.github/CODEOWNERS  # routes CLAUDE.md, .claude/, tools/, templates/, .github/ to the owner — never wiki/
.claude/skills/   # the vault's own automation (step 3)

Per-person raw drops go in raw/inbox/<handle>/ (document it; don't create
per-person or per-team folders anywhere under wiki/ — that is the project
silo with a new name). Ask me for my GitHub handle; seed CONTRIBUTORS.md
with it.

### 2. CLAUDE.md — the vault's constitution

Write the repo's CLAUDE.md with these conventions (these exact rules, in
your own clean wording):

- Header: declare `vault-repo: <GITHUB_USER>/<VAULT_REPO>` once (every
  skill and template reads it) and `vault-owner: <my handle>` — the
  fallback adjudicator when a note's author has left; owns the machinery
  via CODEOWNERS, never the notes.
- Note format: kebab-case slug filenames; one note = one idea; YAML
  frontmatter (title, date, type: feature|pattern|decision|learning,
  author — the GitHub handle of the person whose work the note distils,
  bare with no @ because @ cannot start a YAML scalar, listed in
  CONTRIBUTORS.md, filled by the skills from git identity and never typed
  as a display name; tags, source; plus an
  optional roi field on feature notes — a low-high hours/week band, e.g.
  "~2-4 hrs/week per engineer, X vs manual Y", never a false-precision
  point number);
  sections: one-paragraph summary, then "## Details" (distilled
  enough to reapply without the original source), then "## Related"
  ([[slug]] links).
- Linking: link with [[slug]], liberally — a link to a note that doesn't
  exist yet marks something worth writing, not an error. On every save,
  grep the wiki for related notes, link them, AND add backlinks in their
  Related sections, saying why the notes connect. Never silo by project —
  projects are sources and examples, not boundaries; link across them
  wherever topics genuinely touch, and extract general ideas into their own
  pattern/learning notes that project notes link to.
- Writing: distill, don't dump; absolute dates only ("2026-08-18", never
  "last week"); update existing notes instead of creating near-duplicates;
  delete notes proven wrong. Index hooks are the retrieval surface — write
  each note's index line for a stranger searching by problem: symptom,
  mechanism, stack — not just the title.
- Save mid-session, not just at wrap-up: when a significant decision or
  hard-won gotcha is settled mid-session, save it then — a wrap-up-only
  habit loses decisions to context compaction before the wrap happens.
- Conflict rules, in order: before saving, search existing notes for
  contradictions, not just links. (1) Reconcile as scope first — if both
  notes can be true under different conditions, write the boundary into
  both and carry on. (2) A real contradiction is put to the standing
  note's author:, not to whoever is in the session: if that is the current
  user, STOP and ask — supersede in place or reject; if it is someone
  else, save the new note with a dated "## Disputed" block quoting the
  standing claim and open a GitHub issue on the vault assigned to that
  author (fall back to vault-owner when CONTRIBUTORS.md marks them left)
  — never block the save waiting for a person. (3) Never resolve
  silently: supersede lines read "Superseded YYYY-MM-DD by <handle>
  (author <handle> confirmed): previously X; now Y because Z". Never two
  notes disagreeing; if recall surfaces notes that disagree, flag it
  instead of silently picking one. No review or approval workflow on
  notes — it kills mid-session saving; CODEOWNERS covers the machinery
  only.
- Git rules: always `git pull --rebase` before reading or writing
  (multiple sessions — and people — push here); commit messages
  `vault: add|update|ingest|wrap <slug>`; commit and push straight to
  main immediately — never leave unpushed commits; on a rejected push,
  pull --rebase and push again up to three times (an index.md conflict is
  two appended lines: keep both); never
  mix vault commits with another repo's git state. In a cloud session that
  hands you a disposable branch (claude/<task>), make the first git action
  `git fetch origin main && git checkout -B main origin/main` and push
  `main` itself — committing on the session branch and pushing HEAD:main
  lands the notes fine but leaves that branch's own upstream behind, so
  any stop-hook git check warns "unpushed commits" every turn.

### 3. The skills (.claude/skills/<name>/SKILL.md)

Create four skills. Each SKILL.md gets YAML frontmatter (name, description
— write descriptions that trigger on natural phrases like "save this to
the vault", "what do I know about X", "wrap this session", "garden the
vault") and numbered steps. All of them start by locating the vault
(~/<VAULT_REPO> locally; in cloud sessions shallow-clone
https://github.com/<GITHUB_USER>/<VAULT_REPO>.git to a scratch dir),
pulling, and reading the vault's CLAUDE.md.

- vault-save — distill a feature/pattern/decision/learning from the current
  conversation, codebase, or source file into a note. Steps: locate vault →
  resolve the author handle from the session's git identity against
  CONTRIBUTORS.md (ask if unlisted) → if the input is a raw file, copy to
  raw/inbox/<handle>/ first → distill →
  MANDATORY conflict check (the three-step rule above, including the
  Disputed-block-plus-issue path when the author is someone else) → pick
  type, write note (update if one exists) →
  cross-link with backlinks → index line → run `python3 tools/audit.py
  --check` and fix anything it reports (usually a missed backlink) BEFORE
  pushing — this is the same check the CI runs, so catch it locally instead
  of turning the vault-audit Action red → commit & push → confirm to the
  user (path, links, pushed), reporting push failures plainly rather than
  leaving silent commits.
- vault-recall — pull relevant notes into the current task: search index.md
  + wiki/ by the task's problem/stack keywords AND their synonyms; read
  only matching notes (never bulk-load the vault); follow [[related]] links
  one hop; apply, don't recite; cite each note used by path AND author so
  stale ones get noticed (and say when CONTRIBUTORS.md marks that author
  as left — a departed author's note being applied is the stale-knowledge
  signal a team needs); if nothing relevant exists, say so plainly and
  note the gap as a likely future save.
- vault-wrap — end-of-session retrospective note with sections: what we
  worked on / what was created / process (including dead ends worth not
  repeating) / solution / do it this way next time. SHOW THE DRAFT TO THE
  USER BEFORE SAVING — the vault only gets reviewed knowledge. One session
  = one wrap note; a later "wrap" the same day amends it. If a session
  yields a feature AND a reusable pattern, split into linked notes.
- vault-garden — periodic audit, report-first: near-duplicate scan (merge
  proposals need user approval), contradiction sweep (user decides), link
  integrity (exclude [[..]] inside backticks — that's prose), backlink
  symmetry (Related sections only; body citations may stay one-way — safe
  to auto-fix missing backlinks), index consistency, raw/ orphans, and
  ownership: notes by contributors marked left (propose re-own or leave
  attributed, delete nothing) and "## Disputed" blocks older than 14 days
  (escalate to vault-owner). Run after 3+-note sessions or monthly.
  Duplication's real cost is split knowledge: recall surfaces one half and
  misses the other.

### 4. Ambient recall — the piece that makes it automatic

Create templates/ambient-recall-kit.md containing three copy-paste blocks,
then remind me to apply blocks 1–2 on each of my machines (you can't reach
~/.claude from a cloud session):

1. A SessionStart hook for ~/.claude/settings.json — kicks off a background
   `git -C ~/<VAULT_REPO> pull` and cats index.md into context, prefixed
   with one line telling the model to scan these notes for task relevance
   and recall before designing from scratch.
2. A global CLAUDE.md rule for ~/.claude/CLAUDE.md — before proposing an
   approach for any non-trivial build/design/debug task, scan the injected
   index lines; if any note plausibly relates, recall and apply it even
   when the vault wasn't mentioned, and say which notes were applied. Also:
   save mid-session when significant knowledge is settled, don't wait for
   the wrap.
3. A per-project pointer block to paste into each project repo's CLAUDE.md
   (this is what covers cloud sessions, which never see local hooks):
   consult https://github.com/<GITHUB_USER>/<VAULT_REPO> before non-trivial
   tasks — clone/pull it, read index.md, pull relevant notes into context;
   save hard-won knowledge back per the vault's conventions.

Also note in the kit: on each local machine, symlink the vault's skills so
they work in every repo (rerun after new skills appear; skills are
discovered at session start, so restart the session after linking):

for d in ~/<VAULT_REPO>/.claude/skills/*/; do ln -sfn "$d" ~/.claude/skills/"$(basename "$d")"; done

### 5. The installer — tools/install.sh

Write an idempotent tools/install.sh that automates the local-machine
setup (the three things a cloud session can't reach), so each new machine
is one command plus a session restart:

- symlink every .claude/skills/*/ dir into ~/.claude/skills/ (the loop
  from step 4);
- merge the SessionStart index-injection hook into ~/.claude/settings.json
  — use python3 for the JSON merge, create the file if missing, never
  clobber existing hooks, and skip cleanly if the hook is already there;
- append the ambient-recall rule to ~/.claude/CLAUDE.md unless a marker
  line shows it's already present;
- warn if the machine's git user.name is not on a CONTRIBUTORS.md line,
  since the first save will need a listed handle.

Safe to re-run any time (rerun after pulling new skills). Print what was
done and remind the user to restart their Claude Code session. This script
is the entire per-engineer setup on a team — keep it that way.

### 6. Seed and verify

- Write the vault's first note yourself: a decisions/ note recording why
  this vault is plain markdown + git, so the reasoning survives.
- Then run a real end-to-end test: vault-save one piece of genuine
  knowledge from a recent session, confirm the note + backlinks + index
  line + push all landed, then simulate recall in a fresh context.
- Tell me what's left for me to do by hand (run tools/install.sh on each
  of my machines + restart the session, and paste the pointer block into
  my project repos; for a team: set the org's Claude GitHub App to include
  this repo, add it to every cloud environment's allowed repositories,
  and have each engineer clone + install.sh + one seed save).

### Known gotchas (bake awareness of these into the skills)

- Cloud sessions can't see local ~/.claude — repo-level pointers are the
  only ambient layer there.
- Claude artifacts are account-scoped and read as "not found" cross-account
  — never rely on them to transfer knowledge; git is the transfer layer.
- Multiple sessions (even concurrent ones) push to this repo — that's why
  pull-before-write and push-immediately are non-negotiable.
- Republishing a Claude artifact from a new conversation is refused with
  "a newer version is live" or "identical content" until you have read the
  live artifact in full (action: read, then read every line of the file it
  saves). Do that before the first publish attempt, never force.

Step 3 — Set up your Claude environment

The build prompt created the pieces; this step installs them. This is what makes the vault ambient instead of something you have to remember to use.

Two roles. The vault owner does the once-only work: Steps 0–2, and for a team, the org’s Claude GitHub App scope (must include the vault repo), the vault in every cloud environment’s allowed repositories, and inviting the engineers to the repo. Each engineer — you included — does the per-machine part below: clone, tools/install.sh, restart, one seed save under their own handle so the author field is proven before it matters. Just you? You’re both roles; it’s the same five minutes.

Local machine (each machine you code on)

If you used the build prompt above, it wrote tools/install.sh — run it, restart Claude Code, done. It’s idempotent: rerun it after the vault gains new skills. The three steps below are what it does, for reference or manual setup:

  1. Symlink the skills so /vault-save etc. work in every repo, not just inside the vault:

    for d in ~/MyVault/.claude/skills/*/; do ln -sfn "$d" ~/.claude/skills/"$(basename "$d")"; done

    Skills are discovered at session start — restart Claude Code after linking. Rerun the loop whenever the vault gains a new skill (it’s idempotent). Keeping the canonical copies inside the vault repo and only linking them locally means the skills version with the vault.

  2. SessionStart hook — merge into ~/.claude/settings.json (keep any existing hooks). It injects the vault’s index into every session’s context, after kicking off a background pull so the next session is fresh without this one waiting on the network:

    {
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "sh -c '(git -C ~/MyVault pull -q --ff-only >/dev/null 2>&1 &); if [ -f ~/MyVault/index.md ]; then echo \"## Vault index (personal knowledge vault). Scan these notes for relevance to the task; recall with /vault-recall before designing from scratch.\"; cat ~/MyVault/index.md; fi'"
          }
        ]
      }
    ]
  }
}

  3. Global CLAUDE.md rule — append to ~/.claude/CLAUDE.md. The hook makes every session aware of the vault; this makes acting on it an obligation:

    ## Knowledge vault — ambient recall

The vault index is injected at session start (SessionStart hook). Before
proposing an approach for any non-trivial build, design, or debug task:
scan those index lines, and if any note plausibly relates to the task's
problem, mechanism, or stack, run /vault-recall on it (or read the note
in ~/MyVault/wiki/) and apply it before designing from scratch — even
when the vault hasn't been mentioned. Say which vault notes you applied,
so stale ones get noticed and fixed.

Save in the other direction too, mid-session: when a significant
decision or hard-won gotcha is settled, run /vault-save on it right then
rather than waiting for a wrap-up — decisions left in the chat die in
context compaction before the wrap happens.

Cloud sessions (claude.ai/code)

Cloud sessions never see your machine’s ~/.claude — they only get what’s committed in the repo they check out. Two things cover them:

  • Sessions started on the vault repo itself get everything automatically: the vault’s CLAUDE.md and .claude/skills/ travel with the clone. This is the self-describing-repo payoff.
  • Sessions on your project repos need the pointer block from the ambient-recall kit pasted into each project’s CLAUDE.md (Step 5 automates this). Make sure the vault repo is in the cloud environment’s allowed repositories, or the session can’t clone it.

claude.ai chat (web/mobile)

Recall works from plain Claude chat too, via the GitHub connector — no MCP server needed. Two requirements that both bit me on first setup: the connector must be authorized against the GitHub account that owns the vault, and the Claude GitHub App’s repository access must include the vault repo (github.com/settings/installations → Configure — a “selected repos” install predating the vault won’t include it). Then “check my vault at github.com// for notes on X” works from any chat.

Step 4 — Verify before calling it done

The mistake to avoid: testing only from inside the vault repo, where everything works by construction. Verify the layers:

  1. Open a fresh Claude Code session in a different repo on your machine — confirm the index appears in context and /vault-save autocompletes.
  2. Start a cloud session on the vault repo — confirm the skills load and a test save pushes.
  3. Ask a session to recall something you saved — confirm it finds the note from the index line alone. If it doesn’t, the index hook is written like a title instead of like a search query; rewrite it (symptom, mechanism, stack).

Step 5 — Wire your project repos (Prompt 2)

Manual wiring is a paste-per-repo; this skill automates it and keeps shared skills in sync. Paste into a Claude Code session in the vault repo:

Create a new skill in this vault at .claude/skills/vault-wire/SKILL.md.
Purpose: make a project repo vault-aware. It targets the project repo in
the current session (never the vault itself). Steps it should perform:

1. Pull the vault (local path or shallow-clone in cloud sessions) and read
   templates/ambient-recall-kit.md.
2. Stamp the target repo's CLAUDE.md: if it has no CLAUDE.md, create one
   containing the vault pointer block from the kit; if CLAUDE.md exists,
   grep it for the vault name first and append only the pointer section if
   missing (report, don't duplicate, if already wired — but continue, since
   re-running is how skills get synced).
3. Sync portable skills: maintain a "portable skills" list in the SKILL.md
   (skills every wired project should carry — general-purpose ones, NOT the
   vault-* infrastructure skills, which must never be copied into project
   repos). Copy each from the vault's .claude/skills/ into the target's
   .claude/skills/; vault copy wins on conflict (it's canonical; the
   target's git history preserves the old version) — call out overwrites.
4. Optional: if the repo is used heavily from cloud sessions AND the vault
   is in that environment's allowed repos, merge a repo-level SessionStart
   hook into the target's .claude/settings.json that shallow-clones the
   vault and cats index.md into context. Skip silently when unsure — the
   CLAUDE.md pointer alone is enough.
5. Commit in the target repo following that repo's conventions; never mix
   with vault git state.
6. Record the wired repo (name, date, what was applied) in an
   "applied so far" list inside templates/ambient-recall-kit.md, commit to
   the vault, push to main.
7. Report exactly what was written where.

The skill description should trigger on "wire this repo to the vault",
"vault-wire", "set up the vault in this project", and when scaffolding a
brand-new project repo. Commit and push.

From then on, run /vault-wire once in any project repo — and make it part of scaffolding every new project.

Step 6 — Optional upgrades

The atlas — a visual map of the vault (Prompt 3)

Worth it once you pass ~15 notes. Drawing the real link graph exposes structure that reading notes never does — mine revealed two disconnected “continents” of knowledge, which directly produced the never-silo-by-project rule. Paste into a session on the vault repo:

Create a visual atlas of this vault, and a skill to keep it truthful.

1. Build atlas/vault-atlas.html: an SVG link graph of the vault — every
   note a node (colored by type, sized by link count), every mutual
   [[wikilink]] an edge, links to not-yet-written notes as dashed hollow
   "stub" nodes. Below the map: card shelves per note type (title + index
   hook + link count), the stub list, and a stats row (note count, link
   count, stubs). Extract ALL data from the repo (frontmatter, index.md,
   grep for [[links]]) — never from memory, and have the map generator
   splice every graph-derived number (stats row, each card's link count,
   each shelf's note count) into the page the same way it splices the
   SVG: numbers typed by hand went stale on two consecutive resurveys
   before this was automated. Cross-project links get a
   highlighted treatment with an italic label saying why the notes connect.
   Publish it as an artifact and record the fixed artifact URL in the
   skill.
2. Create .claude/skills/vault-atlas/SKILL.md: on each run, pull the vault,
   re-extract the real data (never trust the previous drawing), update
   atlas/vault-atlas.html in place, republish to the SAME artifact URL, and
   commit — the committed source and the published page must never
   diverge. Generate node positions programmatically and run a
   label-collision check (label bounding boxes vs node circles) on
   EVERYTHING that renders before publishing; verify edge counts against
   the extraction. Route edges programmatically too: a straight line if
   clear, otherwise a bend that grows until it clears every node, trying
   several points along the edge — a well-linked note reaching across the
   whole map cannot be placed by hand. Before republishing from a new
   conversation, read the live artifact in full first (the platform refuses
   otherwise). Verify the published result by fetching the artifact URL and
   diffing it against the committed source — a cloud session has no browser
   to screenshot with, so curl+diff is the only way to confirm the publish
   actually matches. Trigger phrases: "update the atlas", "refresh the
   vault map", after a batch of saves.
3. Add a drift nudge to vault-save's final step: if 5+ notes have been
   added since the atlas was last built, suggest running /vault-atlas
   (don't run it unasked — it republishes an artifact). The audit script
   (Prompt 4) enforces the same threshold from the other side: it reads
   the generator's LAYOUT and lists every note without a position.

Mechanical audit + CI (Prompt 4)

Converts the linking conventions from “remember to” into an enforcement surface. Paste into a session on the vault repo:

Write tools/audit.py: a dependency-free python script that
deterministically checks the vault's conventions — one-way Related links
(A links B but B's Related section doesn't link A), notes missing from
index.md and index lines pointing at missing notes, frontmatter gaps
(title/date/type/author/tags/source), an author: that is not a handle
listed in CONTRIBUTORS.md, a Superseded line that names no confirmer,
secret-shaped strings in wiki/ or raw/ (private-key headers, sk_/pk_
keys, JWTs, AKIA, password=), [[links]] whose target note doesn't exist
(report as "wanted note" stubs, not errors), orphan notes with no links in
or out, notes by contributors marked left (informational), notes with no
position in the atlas generator's LAYOUT (informational up to four, a
violation from five — the same lag the atlas drift nudge tolerates, so a
note saved without an atlas run is named on that push, not discovered
when the generator refuses weeks later), and tag
statistics. Ignore [[..]] inside backticks (that's prose,
not a link). Give it a --check mode that exits non-zero on hard violations.
Then add a GitHub Action that runs `python3 tools/audit.py --check` on
every push to main. Finally, make it vault-garden's first step, so the
skill spends its judgment on what the script can't see: duplication and
contradiction.

A vault for a team, not just you

A small company’s vault is departure insurance: the reasoning behind AI-built code — which git never records — survives the coder leaving, and the next coder (human or AI) gets it in the room automatically through ambient recall instead of a handover meeting. In practice the first payoff is cross-person: two engineers on different projects hitting the same gotcha is a daily event; someone leaving is rare.

Nothing extra to build. Prompt 1 already produced every team piece, and I kept it that way on purpose after checking each one against the solo case — every one is a no-op or a small improvement when CONTRIBUTORS.md has one line, so one guide serves both and never drifts into two:

  • author: is a GitHub handle, filled from git identity. Not credit; routing — the person to ask when a note is questioned. Solo, it’s always you, and you never type it.
  • vault-owner: + CONTRIBUTORS.md — the fallback adjudicator and the handle→name→status list the audit reads. Solo: one line each.
  • The conflict rule routes to the author, not the room. Scope first; then the author; and when the author isn’t in the session, the save skill writes a ## Disputed block and opens an issue assigned to them rather than asking whoever is present or dropping the knowledge. Solo, the author is you, so it collapses to “stop and ask” — the rule says so explicitly.
  • pull --rebase + retry on a rejected push. Strictly better solo too: concurrent cloud sessions already push to one repo. index.md is the merge hotspot; appends rebase cleanly, so don’t split it until conflicts actually happen.
  • CODEOWNERS on the machinery only. Notes never need a PR — friction on the save path kills mid-session saving, and git history is the audit trail. A team adds branch protection on those paths; solo it’s inert.
  • A secrets grep in the audit, because more writers means more pasted env vars. Good for anyone.
  • tools/install.sh is the whole per-engineer setup. Solo users want it too.

The only genuinely team-only decision is where the repo lives (the org, Step 1), plus the org’s Claude GitHub App scope and cloud allowed-repos (Step 3). Client and project names are fine in an internal vault — the public-share leak check this vault’s atlas carries is a personal-vault concern, not a team one.

Leaver’s runbook: change their CONTRIBUTORS.md line to left YYYY-MM-DD, run /vault-garden (it lists their notes), re-own or leave attributed — delete nothing; the notes were the point.

Saving from other machines and accounts

Vault access is a GitHub question, never an AI-account question. Three routes, in order of preference:

  1. Any machine, local Claude Code — a fine-grained GitHub PAT scoped to only the vault repo (Contents: read/write), then git clone https://<PAT>@github.com/<you>/<vault>.git. The skills travel inside the repo, so /vault-save works immediately. Revoke the PAT when done with that machine.
  2. Cloud sessions on another Claude account — connect that account’s GitHub connector to an identity that can reach the vault (invite it as a repo collaborator if needed).
  3. No git access at all — distill the knowledge in chat, then commit it into raw/ via the GitHub web UI as an inbox, and ingest later from your main setup. Never rely on Claude artifacts to transfer knowledge between accounts — they’re account-scoped and read as “not found” cross-account, indistinguishable from deleted.

The details that cost real mistakes

Everything above was learned the hard way across the build sessions. The compressed list, so you don’t repeat them:

  • Friction kills capture. Every storage option heavier than markdown+git (database, Notion, sync services) adds a step to the save path. The save path must be one command or it won’t happen.
  • You can’t recall what you don’t know exists. On-demand recall has a bootstrap problem — the session only checks the vault when someone thinks to ask. The index-injection hook is the fix, and it’s the single highest-value piece of the system.
  • The index line is the retrieval surface. “Kanban board feature” finds nothing; “for push-less APIs: one central fetch per tick into a shared cache + tiny poke broadcasts to clients” gets found by the right task. Write hooks for a stranger searching by problem.
  • Save mid-session. Long sessions compact their context; a decision settled at 10am is gone from the conversation by the 6pm wrap. Save it when it’s settled.
  • Conflicts stop the presses. Two notes silently disagreeing is worse than no note — recall will surface one and you won’t know the other exists. Supersede in place with a dated reversal line; git keeps the old version.
  • Never silo by project. Projects are sources and examples, not boundaries. Extract the general pattern into its own note that project notes link to; otherwise it’s buried where only that project can find it.
  • Skills are discovered at session start. The most common “skill is missing” false alarm is a session opened before the skill was installed. Restart first, debug second.
  • Cloud sessions can’t see ~/.claude. Repo-level CLAUDE.md pointers and in-repo skills are the only ambient layer there. Test from a fresh session in a different repo before calling any of it done.
  • “Permission denied (publickey)” on a brand-new machine is an auth-order problem, not a broken machine. It means git/gh tried SSH before any GitHub credentials existed locally — normal on a Mac that’s never talked to GitHub. Run gh auth login (HTTPS, browser login) before the first gh repo create --clone or git clone, not after debugging SSH keys.
  • Run a new skill once for real before trusting it. My first garden sweep surfaced real findings and three false-positive classes that got folded back into the skill’s spec. The validation run makes the tool better, not just proves it.
  • Convention → mechanism is the recurring upgrade. Every durable fix converted a “remember to” into a hook, script, CI check, or skill step. If a rule matters, give it an enforcement surface.
  • Institutionalize immediately. A preference stated in chat is lost; the same preference as a CLAUDE.md rule or a skill step is permanent. Write it down the moment it’s decided.
  • Multiple sessions push to the vault, sometimes concurrently. That’s why pull-before-anything and push-immediately-after-commit are non-negotiable, and why the vault commits straight to main — notes accumulating don’t need branches or PRs.
  • A warning that fires every turn is a mismatch, not a flake. The “unpushed commits” stop-hook warning was correct about the branch it was looking at: the harness’s disposable session branch, not main. Check out local main first in cloud sessions; prefer a repo-level rule over a machine-level patch, because the rule works in every session.
  • Read the artifact before the first publish, not after the refusal. The atlas publish was refused on nearly every run until the read step moved ahead of the publish. It turned a three-round failure into one clean publish, and the fix lives in both a note and the skill step — a note is recallable, a skill step is unavoidable.
  • The guide drifts unless something checks it. Everything that improves the vault’s own machinery (a convention, a skill, a tool) has to land in this guide in the same commit, or new vaults inherit last month’s version. The garden skill now diffs the infrastructure files against the guide’s last edit and reports the gap.
  • Design for the team, then check it collapses for one. The team version of every rule turned out to be a superset of the solo one — author routing, rebase-retry, CODEOWNERS, the secrets grep all cost nothing with one writer. That is what let the guide stay one guide instead of a personal and a team fork that would drift apart. (One detail it surfaced: @handle can’t start a YAML scalar, so author: is the bare handle.)
  • A public copy of a private source drifts the moment the sync is a manual step. The guide and atlas are published on a site whose repo cannot see the vault, so a script copies them across. The day the guide was edited three minutes after that script last ran, CI went red for three pushes in a row and nobody could tell why from the commit messages. Two fixes, both needed: a CI check that fetches the live pages and compares the hash they were built from (so drift is loud), and a one-command sync (tools/sync_site.sh) that every skill runs whenever its commit touches the guide or the share edition (so drift is rare). A check without the sync just makes the failure visible; the sync without the check fails silently the first time someone forgets. Make the check compare survey date and note/link counts, not just that the published page exists — presence-only checks pass on a stale copy.

How this vault was actually built

For calibration on effort: the system above took two focused sessions plus incremental upgrades during a week of real use.

  • Session 1 (one sitting): concept debate (markdown+git won), repo scaffold, CLAUDE.md constitution, the save/recall/wrap skills, local symlinks + global CLAUDE.md, first end-to-end save, cloud verification — which found the “skills invisible outside this repo” gap and produced the layered discovery fix.
  • Session 2: the upgrade from passive store to self-maintaining system — ambient recall (hook + rule + per-repo pointer), the garden audit skill, the atlas, cross-account saving routes, and three new conventions that the atlas’s link graph exposed the need for.
  • Ongoing: the wire skill to automate project onboarding, the audit script + CI action, the mid-session-save rule, a de-identified public edition of the atlas, then (2026-09-06) the cloud-only branch rule, the artifact read-before-publish step, the author field + team conflict rule, (2026-09-10/11) the team-capable conventions folded into the core build, and (2026-09-12) the atlas coverage check in the audit and generated atlas counts, after a note saved without an atlas run sat unmapped for a day and hand-typed card link counts went stale twice in two days. Each upgrade followed the same pattern: hit a gap in real use → fix it → institutionalize the fix as a skill or convention.

Written 2026-08-30, last updated 2026-09-12, distilled from the working MyVault system after two build sessions and a week of daily use. The guide deliberately contains the process and the system, not the vault’s contents — your vault should fill with your knowledge.

Built by Darren Humphries. If you build your own vault from this guide, I’d genuinely like to hear how it goes — reach out on LinkedIn.