LLM Best Practices

Vault Architecture

3 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

A vault is a folder of plain Markdown notes whose structure is declared, not improvised. Four artifacts define it: a folder tree, a naming table, a frontmatter schema per note type, and link and tag policies. Templates, queries, audits, and agent workflows all read those four. This page covers the tree, the note-type scope, and the spec file; the fields are in vault-frontmatter-schema and link rules in linking-and-tags. For a plain publishing vault with no schemas, use obsidian.

Number the top-level folders

Prefix each folder with two digits so the sort order is stable in every file browser and 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 what goes in, what does not, and its lifecycle: inbox notes are processed and removed within seven days, archive notes are never deleted. Without the lifecycle line, folders become junk drawers. Two levels deep is the ceiling (folder-hierarchy).

Ship only the note types the work produces

The list above is a menu. Drop what the work does not need.

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

A dead folder with a template nobody fills teaches that the schema is optional, which is how vaults end. Size layers to the maintenance budget (vault-maintenance).

Declare the architecture in vault-spec.yaml

Put the spec at the vault root as the single source of truth.

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_byte_threshold: 5000
  stale_verification_days: 180

The auditor reads this file for required fields, folders, filename patterns, and thresholds, so adding a note type is a spec edit and not a code change (vault-audit).

Generate the vault from the spec

Hand-built vaults drift from their documentation on day one. Generate the tree, schema reference files, templates, starter map, and Dataview dashboard from the spec, then audit the result against the same spec; a bootstrap that audits clean proves the architecture before any real note exists. Refuse to write into a non-empty directory without an explicit override, since bulk file writes have no undo outside version control. The step-by-step is in bootstrap-a-research-vault.

Keep the vault plain Markdown

Use .md files, YAML frontmatter, and wikilinks, with nothing proprietary beyond what the editor reads. If the editor disappeared, every note would still read in a terminal and every relationship would still grep. The same property makes the vault legible to agents and publishable through quartz without a transform step.

Backlinks