The db.md spec
A db.md store is one directory with two folders and a single config file. Every markdown file carries YAML frontmatter.
The shape
Two folders, two data models
The hard boundary is evidence vs. agent-authored: sources/ vs.
records/. Inside records/, a meta-type field carries the finer
distinction (atomic data vs. synthesis) rather than a separate folder.
sources/holds evidence the agent did not author, preserved verbatim. Two kinds: documentary artifacts from outside the operator's hand (emails, transcripts, exports, PDFs, scrapes) and testimonialnotesources (with atold_byfield) that capture "a human told the agent X" when there is no document behind the fact. Sources are immutable and carry nometa-type. At scale,dbmd writeplaces high-volume sources into date shards automatically (sources/emails/2026/05/,sources/notes/2026/05/).records/holds everything the agent authors, separated by themeta-typefrontmatter field:meta-type: fact(the default) — atomic typed data: one file per contact, company, expense, meeting, decision, or invoice, with frontmatter the agent queries.meta-type: operational— operating state the agent maintains (a running counter, a task list, a status board).meta-type: conclusion— the curator-synthesized narrative. Every meaningful entity the operator cares about gets a page that links back to its records and sources.
A single entity often has both: a records/contacts/sarah-chen.md
holding the atomic facts (meta-type: fact), and a
records/profiles/sarah-chen.md page (meta-type: conclusion) that
synthesizes across her meetings, emails, and the company she works for.
The meta-type field, not a separate folder, tells them apart.
The single config file
DB.md is the store's only configuration: one file at the store root.
It is markdown with frontmatter for identity and three optional
sections for behavior:
All three sections are optional; absence means canonical defaults.
## Schemas is parseable and enforced. Each ### <type> heading
lists one field per line as - <name> (<modifiers>), where modifiers
include required, shape checks (string, int, date, email,
url), link to <prefix>/, default <value>, and enum: a, b, c.
Universal frontmatter
Every content file (everything under sources/ and records/)
carries YAML frontmatter:
Type-specific fields layer on top. summary is the single source of
truth for what a file is about; every index.md reads it directly to
build its catalog. Meta files (DB.md, index.md, log.md) have
their own contracts and need no summary.
The id field
id is the record's stable identity — the one value that survives
rename and reorganization, where filename identity does not. It is
recommended, not required: dbmd write mints a lowercase ULID (26
chars of Crockford base32) for each new record, a record without one
stays fully valid, and filename identity remains the wiki-link
fallback. Ids are minted by tooling, never composed by hand. On top of
id, db.md reserves one cross-store address shape, @brain/id — the
shape only; registration and resolution are out of scope for the
format.
Meta-type
meta-type is a records-only, closed-enum field that separates the
roles a records/ file can play. It carries what an earlier wiki/
folder used to carry as a separate layer.
- Closed set. The only valid values are
fact,operational, andconclusion. Any other value is a hard error (FM_BAD_META_TYPE).typestays open;meta-typedoes not. - Default
fact. Absent ⇒fact. The effective value is what the index records and what--where meta-type=factmatches, so an un-annotated record is a fact for every query.operationalandconclusionare always explicit. - Field, not folder. Folders stay organized by
type(contacts,playbooks,synthesis);meta-typeis a cross-cutting queryable field. By convention a store keeps its conclusion types in their own folders (records/profiles/,records/synthesis/), butmeta-type, not the path, is what makes a file a conclusion. - Sources have no
meta-type. Evidence is mono-role; the documentary-vs-testimonial distinction insidesources/is atypedistinction (email,pdf-source,note). conclusionis single-voice. Records withmeta-type: conclusioncarry the single-writer synthesis contract; one curator reconciles them.
Query the synthesis layer with --in records --where meta-type=conclusion.
Example types
An illustrative vocabulary, split by folder. db.md has no built-in type
vocabulary — every type is the store's own; an unrecognized type: is
read as ambient context. The meta-type column applies to records/
only (sources/ rows have none); absent ⇒ fact.
The conclusion types (profile, concept, playbook, theme,
synthesis, account) carry the synthesis that an earlier wiki-page
type carried; wiki-page is retired. Synthesis now carries a domain
type in records/ plus meta-type: conclusion, not a single generic
type in a wiki/ folder.
The table is illustration, not lock-in. Every type is the store's own,
and schemas become enforced only when DB.md declares them under
## Schemas. Fields declared as link to <prefix>/ are validated as
full-path wiki-links.
Linking
Wiki-link syntax:
The target is the full path relative to the store root, without
.md. An optional |display segment overrides the display text.
Short-form links ([[sarah-chen]]) are a validation error. The full
path is what makes the link graph unambiguous as the store grows.
Reading rules
A compliant reader:
- Treats frontmatter as YAML, not TOML or JSON.
- Expects the frontmatter block as the first thing in the file,
delimited by
---. - Passes unknown frontmatter fields through unchanged.
- Treats unknown wiki-link targets as text, not an error.
Frontmatter is auto-generated and maintained by the agent acting as curator. Operators don't write frontmatter by hand.
Full spec
github.com/carloslfu/db.md/blob/main/SPEC.md, tagged with each release. It carries the full curator contract, the agent session lifecycle, the validation issue codes, and the scale model.