grapefruit The field manual · 7 patterns

Keeping a Vault

A vault is a personal knowledge base built from plain markdown in a git repo, structured so an agent can file, find, triage, and maintain it with you. These steps build one from scratch, one habit at a time.

Distilled from one practitioner's measured usage: logged sessions, the incidents that recurred, and the patterns that stopped them. v0. Step slugs are stable; chapters may be cut or reordered before 1.0.

The steps

Ordered by leverage-per-effort, but every step stands alone: start where it hurts. In a hurry, step 0 is the baseline in one paste.

00 The one-paste vault
Optional full-package setup: a plain-file vault with lifecycle directories, an inbox, a daily log, and project instructions that teach the agent the shape.
01 Plain files in a repo
Markdown files in a Git repository give people and agents the same searchable, versioned, portable source of truth.
02 Location is state
Four lifecycle directories (inbox, active, later, archived) where moving a file IS the workflow, and the agent can read project status off the filesystem.
03 Capture now, sort later
An inbox with zero-friction capture and agent-assisted triage: getting a thought out of your head must cost nothing at the moment it happens.
04 The daily log
Append-only day notes at log/YYYY/MM/. The agent writes session summaries, and months later the log answers 'what did I decide and why.'
05 Teach the agent the shape
A supported project-instructions file at the vault root teaches every future agent session the structure, conventions, and working agreements.
06 Run a doctor
Use a small advisory script to find broken links, naming drift, and stale active work, then verify the checker on known bad input.

← The field manual · for agents: raw chapters at /guides/vault/*.md