LLM Best Practices

Vault Architecture

4 min read

View markdown source

Overview

A vault is a folder of plain Markdown notes whose structure is declared, not improvised. The architecture is four artifacts: a folder tree, a naming convention table, a frontmatter schema per note type, and link and tag policies. Everything downstream (templates, queries, audits, agent workflows) reads those four. This page covers the tree and the note-type scoping; the schema itself is in vault-frontmatter-schema and the link rules are in linking-and-tags.

Number the folders so the tree sorts itself

Prefix every top-level folder with a two-digit number. Sort order becomes stable across every file browser, and the number encodes the pipeline stage.

00-Inbox/          # Fleeting captures, processed within 7 days
10-Sources/        # One note per book, paper, podcast, talk, dataset
20-Atoms/          # Permanent atomic notes, the core
30-Maps/           # Maps of Content, grown from clusters
40-Projects/       # Active workspaces
45-Decisions/      # Decision journal entries
50-Frameworks/     # Methodologies and mental models
60-Claims/         # Specifically attributed factual claims
70-Questions/      # Open questions and research gaps
75-Contradictions/ # Unresolved tensions between atoms
80-Synthesis/      # Long-form drafts assembled from atoms
90-Templates/      # Templater files
99-Archive/        # Completed and deprecated, never deleted
99-Tools/          # Auditor and generated reports
_attachments/      # Images and PDFs, excluded from the graph

Annotate each folder with three facts: what goes in, what does not go in, and the lifecycle. Inbox notes are processed and removed within seven days. Archive notes are never deleted. Without the lifecycle note, folders silently become junk drawers. The shallow-tree rule in folder-hierarchy applies inside each folder too: two levels deep is the ceiling.

Scope the note types to the work, then drop the rest

The folder list above is a menu, not a requirement. Ship only the note types the work actually produces.

  • No decisions in scope: drop 45-Decisions/ and its schema, templates, and queries entirely.
  • No active disagreement in the literature: drop 75-Contradictions/ but keep the habit of capturing tensions.
  • Sources fold their claims inline: drop 60-Claims/.

A dead folder with a template nobody fills teaches the user that the schema is optional, which is the failure that ends vaults. Cut layers against the maintenance budget, not against ambition. See vault-maintenance for how to size that budget honestly.

Declare the architecture in a spec file at the vault root

Write vault-spec.yaml at the vault root and treat it as the single source of truth for structure.

vault:
  name: "Macro Research"
  framework_primary: mece-pyramid
note_types:
  atom:
    folder: 20-Atoms
    filename_pattern: "^[a-z0-9-]+$"
    required: [id, title, type, status, created, sources, confidence]
  source:
    folder: 10-Sources
    filename_pattern: "^@[a-z0-9-]+$"
    required: [id, title, type, source_type, author, year]
rules:
  atomicity_max_bytes: 4000
  stale_verification_days: 180

The spec is what makes the vault machine-checkable. The auditor in vault-audit reads it to know which fields are required per type and which folder each type belongs in, so adding a note type is a spec edit rather than a code change.

Generate the vault from the spec instead of hand-building it

Hand-built vaults drift from their own documentation on day one. Generate the tree, the schema reference files, the templates, the starter MOC, and the query dashboard from the spec, then verify the generated vault audits clean against that same spec. A bootstrap step that self-audits proves the architecture before any real note exists.

Refuse to write into a non-empty directory without an explicit override. Bulk filesystem writes are the one operation in vault work with no undo outside version control.

Keep the vault plain Markdown so it outlives its editor

Use plain .md files, YAML frontmatter, and wikilinks. Nothing proprietary beyond what the editor itself reads. The test: if the editor disappeared tomorrow, every note is still readable in a terminal and every relationship is still greppable. That constraint is also what makes the vault legible to agents and publishable through a static site generator such as quartz without a transform step.

Backlinks