What is db.md

db.md is the open standard for databases in plain files. Your data lives in files you can open, read, edit, grep, and keep. The agent reads, writes, links, and reshapes those files directly, so the database gets sharper as the models do, without a proprietary index or app migration layer in the middle.

For builders: records are markdown files with YAML frontmatter, relationships are wiki-links, the directory is the database, frontmatter carries structured fields, DB.md declares schemas, and your agent is the query engine.

Before agents, text was documentation. After agents, text becomes operational state.

The stack collapse

For decades, the default app shape was:

Database -> Backend -> FrontendPostgres + service layer + React app

The database held the state. The backend encoded the rules. The frontend exposed fixed views and actions. That shape made sense when programs could not understand meaning-rich state directly.

Agents change the default. For semantic, evolving, workflow-heavy software, the new shape is:

Markdown files -> Agent harness -> Generated surfacedb.md + agent harness -> voice, chat, canvas, forms, approvals, dashboards

The app becomes readable state plus an agent that can operate on it. That is db.md's claim: not "no database," but agent-operated files-as-database.

One directory, two folders, one config file.

db/├── DB.md          # the store's identity, schemas, and policies├── sources/       # evidence from outside: emails, PDFs, exports, and│                  #   notes that capture what someone told the agent└── records/       # everything the agent authors: contacts, expenses,                   #   meetings, and synthesis — tagged by a meta-type field

What it is for

db.md fits software that is mostly records, context, relationships, decisions, workflows, and a surface. A trip planner. A baby tracker. A migraine log. A reading system. A CRM. A knowledge base. An ops tracker. A contract register. A decision log. The internal admin panel every team builds and rebuilds.

The old default was Postgres + backend + React because that was the default shape. Now much of this territory can start as db.md + agent harness + generated UI. The agent reads and relates the records directly and builds whatever surface you ask for on demand. The data stays plain files you can open, edit, grep, and commit. There is no server to run and no admin panel between you and your own records.

Built for agents

Agents create more software, not less: personal apps, home-cooked tools, team workflows, agent-native products, and company systems whose shape changes as reality changes. That software wants a text-first, agent-run database. An agent does not want a schema migration pipeline as its primary interface to reality. It wants files it can read, write, link, and curate directly. That is what db.md is.

So db.md is not only the database you move off SQL. It is the database new software can start on. Add a field by adding frontmatter. Split a type by editing DB.md. Let the agent repair the records because it can read the store, not just call it. The same agent that built the tool can keep its data model current.

The lineage

Andrej Karpathy's April 2026 LLM Wiki showed an LLM maintaining a coherent markdown world at the scale of a research topic. db.md takes that proof and turns it into a database format. A company brain is one important use case: customers, vendors, contracts, decisions, meetings, and expenses, maintained by the agent the team directs. Personal software is another. Home-cooked software is another. The category is larger than all of them. It is agent-native persistence.

Two folders, one cross-cutting field:

• sources/ is evidence the agent did not author. Emails, transcripts, exports, PDFs, preserved verbatim, plus note sources that capture what a human told the agent (a told_by field marks the testimony).
• records/ is everything the agent authors, separated by a meta-type frontmatter field rather than by folder. meta-type: fact (the default) is atomic typed data — one file per contact, expense, meeting, or invoice, with frontmatter the agent queries. meta-type: operational is operating state the agent maintains. meta-type: conclusion is the agent's synthesis: every entity you care about gets a page that links back to its evidence.

Why plain files

LLMs are native markdown readers

Markdown is plain text. Frontmatter is YAML. The agent reads it and writes it in the same medium a human does. No schema validator to wrangle, no ORM, no migration machinery.

Filesystem semantics carry

Standard tools work. rg for full-text search, git for version control and audit, find for backups, mv for restructuring. An encrypted filesystem for confidentiality. Nothing proprietary to maintain.

It composes anywhere

db.md is independently usable. Agent-built internal tools can adopt it. Obsidian users can adopt it. Researchers running a solo wiki can adopt it. Any agent platform with a markdown folder can adopt it. The spec is the contract, and the runtime is replaceable.

Where SQL still fits, for now

The genuinely hard cases are real: high write concurrency, ACID transactions, sub-millisecond reads, aggregates over billions of rows. A real engine still earns its place there today. db.md and SQL compose cleanly in the meantime. Write to both, and treat db.md as the canonical, human-readable layer. Postgres is for authoritative machinery. db.md is for living context.

The direction is one way. The roadmap takes db.md into that territory too, with a packed engine projected through a virtual filesystem, under the same contract: the directory is the database, the files are the source of truth. More of this territory moves into agent-readable files. Not by bolting on a vector database.

How to install it

db.md is operated by agents, and the installer is text. Hand this prompt to Claude Code, Codex, or any agent with a shell. It covers both cases: a clean start, or bringing an existing knowledge base across. You do not have to decide which. The agent looks at what you have and proposes the path.

Read https://www.sevrahq.com/db-md/llms.txt and set up db.md on this machine: install dbmd, run dbmd spec to load the standard, then create a store. By default the store is version-controlled, never a bare folder at a global path: that is the design, since the point of db.md is that Git or a sync service can save and carry these files. If this is a git repo and my data already lives here, create the store inside it (for example ./db/) and do not move repo-owned files out without asking me; otherwise git init the store (and offer a remote) or use a folder I sync. Only skip version control if I tell you I want a throwaway store. If I already have notes, exports, or a knowledge base to bring in, evaluate it first and show me a migration plan into sources and records (with synthesis written as records carrying meta-type: conclusion), then migrate it once I approve, preserving provenance and verifying nothing was lost. Moving the data is only half of it: also find whatever connects to that knowledge base (my skills, commands, scripts) and point them at the new store. Don't leave migration-map pages or temp artifacts unless I ask; git is the audit trail. Confirm where the store lives and how it is backed up before you scaffold.

It is safe to paste. The install chain is built in CI from tagged commits, checksummed, and signed, and you can ask the agent to read the installer and release workflow before it runs anything. The repo has the receipts.

Related

• How db.md relates to other approaches: what sits between you and your data, against SQL, Airtable, Notion, and the AI-memory tools it gets confused with.
• The db.md spec: the format definition.
• Example stores: research-wiki, ops-store, personal-second-brain, agency-knowledge-base, customer-database.
• The curator contract: how the agent maintains the store.
• Repo: the Apache-2.0 source code.