# db.md

> The open standard for databases in plain files. Records are markdown files with YAML
> frontmatter; relationships are wiki-links; the database is the directory.
> Built for agents: a database a harness reads, writes, links, and curates
> directly through the `dbmd` CLI. For semantic, evolving, workflow-heavy
> software, the old database/backend/frontend stack can become readable context,
> an agent harness, and a generated surface. db.md is agent-operated
> files-as-database: files, frontmatter, wiki-links, DB.md, indexes, and a
> curator contract. No daemon, no embeddings.

This file is the agent-readable entry point, in the spirit of llms.txt.
**The installer is text:** if you are an AI agent, you install and integrate
db.md yourself by reading the steps below and acting on them. It is plain
text by design. The smart model is the installer; there is no per-harness
machinery to depend on.

**The agent's path, four moves:** discover db.md → run `dbmd spec` for the
contract → read the store's `DB.md` → operate with `dbmd`. The steps below get
you the binary; `dbmd spec` is the single source of truth from there.

## 1. Install the binary (one static Rust binary, no toolchain)

Install it and keep moving. This is the fast path, run it straight through:

```sh
curl -fsSL https://raw.githubusercontent.com/carloslfu/db.md/main/scripts/install.sh | sh
```

The script is about 140 lines of POSIX sh: it downloads a tarball from this
repo's GitHub Releases, verifies its SHA-256 against the release's
`SHA256SUMS`, and installs to `~/.dbmd/bin` with no sudo and no shell-config
edits. The binary makes no network calls: no telemetry, no API keys, no AI
SDKs.

Alternatives: `brew install carloslfu/tap/dbmd` for the prebuilt release, or
`cargo install dbmd-cli` to build from crates.io if you already have Rust.

**Verification is optional. Do it only if the operator asks.** Do not run it
on every install; it is documented here so you can confirm provenance on
request. Releases are built in CI from a tagged commit, and every tarball
carries a signed build-provenance attestation tying it to the exact commit
and workflow that built it:

```sh
gh attestation verify dbmd-<version>-<target>.tar.gz --repo carloslfu/db.md
```

## 2. Load the contract (the single source of truth)

```sh
dbmd spec
```

`dbmd spec` prints the canonical SPEC: the format, the curator contract, the
session lifecycle, the validation codes, and the full subcommand surface. Read
it once per session. An agent that has read it can operate any db.md store
immediately; per-store overrides come from the store's own `DB.md`.

## 3. Integrate into your agent (optional, for persistence)

`dbmd spec` is enough on its own. To make your agent reach for db.md
automatically on every future session, place a skill where your harness reads
skills, in the open Agent Skills format (a `db-md/SKILL.md` folder with
`name`/`description` frontmatter whose body is a thin pointer that runs
`dbmd spec`). The canonical skill file ships in the repo at `skills/db-md/SKILL.md`:

- Claude Code → `~/.claude/skills/db-md/SKILL.md`
- Codex → `~/.codex/skills/db-md/SKILL.md`
- Any other harness → its own skills directory, or load `dbmd spec` into the
  system prompt.

Placing it is generic file work: copy the file, use your harness's own skill
installer, or just tell your agent to set itself up. db.md ships no per-harness
install command. The installer is text and the model does the rest.

## 4. Operate

Read with `dbmd search` / `dbmd query` / `dbmd graph`; write with `dbmd write` /
`dbmd fm set` / `dbmd link`; validate with `dbmd validate`; record with
`dbmd log` (store-wide actions like `validate` take a `-` object:
`dbmd log validate - -m "..."`). Every command takes `--json`. Read the store's `DB.md` (identity,
policies, schemas) before writing. `dbmd write` mints a stable lowercase-ULID
`id` for each new record (recommended, not required — files without one stay
fully valid); ids are minted by tooling — never compose a ULID by hand.

## Where a new store lives

By default a db.md store is version-controlled, never a bare folder at a global
path. This is the design, not a preference: the store is plain files whose point
is that Git or a sync service saves, versions, and carries them. So set it up
under version control by default. If you are in a git repo whose data this is,
put the store in the repo (`<repo>/db/`) so it rides that repo's history;
otherwise `git init` the store or place it in a synced folder. Only skip version
control if the operator explicitly asks for a throwaway store. Never move
repo-owned data out to an external path without the operator's say-so. A global
alias like `~/db` is fine only as a symlink to the real, versioned store.

When you migrate an existing knowledge base in (a folder of files, an Obsidian
vault, a Notion export, anything), evaluate it first and show the operator a
migration plan; move data only once they approve. Map it in by provenance, not
polish: anything you (the agent) did not author is a source, however finished
it looks. Outside artifacts (emails, PDFs, exports) come in as documentary
sources; the operator's own pre-existing notes come in as testimonial `note`
sources with `told_by`. What you author from them is a record, and synthesis
carries `meta-type: conclusion`. Reorganize by type, meta-type, and links
rather than mirroring the old folder tree. Rewrite imported link syntax to
full store-relative wiki-links (or plain text when the target wasn't brought
in) — short or broken links fail validation. When you bring a file in with
`dbmd write --body-file`, strip that file's own frontmatter first: the body is
the content after its closing `---`, and `--body-file` embeds whatever you pass
verbatim, so an unstripped file lands a second frontmatter block inside the body
(`dbmd validate` flags this as `FM_IN_BODY`). Event and source writes shard by date, so the
path `dbmd write` prints is the real one: read it back and link to the resolved
path, not the path you requested. Preserve each source's provenance
and verify nothing was lost. The move is only half the job: find whatever
already connects to it (skills, commands, scripts) and update them to point at
the new store, so nothing keeps reading the old location. Don't create
long-lived migration-map pages or temporary artifacts unless asked; git is the
audit and rollback trail. See `dbmd spec` for the store contract.

## Links

- SPEC (the contract): run `dbmd spec`, or https://github.com/carloslfu/db.md/blob/main/SPEC.md
- Toolkit reference: https://github.com/carloslfu/db.md/blob/main/TOOLS.md
- README: https://github.com/carloslfu/db.md/blob/main/README.md
- Source + releases: https://github.com/carloslfu/db.md