Skip to content

adr-001-plain-markdown-git.md

Latest commit

 

History

History
28 lines (21 loc) · 1.14 KB

adr-001-plain-markdown-git.md

File metadata and controls

28 lines (21 loc) · 1.14 KB
Raw

ADR-001: Plain Markdown + git as the storage substrate

  • Status: accepted
  • Date: 2026-08-06
  • Related: ADR-004 (secrets), ADR-006 (regenerable indexes)

Context

The knowledge system needs a storage format that an agent can read and write reliably, a human can edit by hand, and that will not trap the data in a proprietary format. Candidates considered: a database (SQLite), a SaaS note product with an API, and plain Markdown files in a git repository.

Decision

The vault is a folder of plain Markdown files with YAML frontmatter, versioned with git. No database is the source of truth for notes. Derived indexes (embeddings, tree index) are regenerated from the files.

Consequences

  • No lock-in: any editor, any agent, any OS can read the brain.
  • Diffable: every change is reviewable; rollback is a git command.
  • Portable: the whole brain is a folder you can copy, back up, or gift.
  • Durable: Markdown will outlive proprietary formats.
  • The cost — no query language, no constraints — is paid back by the consolidation layer (ADR-003), which reorganizes the mess nightly. Structure is a process, not a schema.