# 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; the `dbmd` CLI is the deterministic plumbing. 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 does the installing; 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 160 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 never phones home: no telemetry, no auto-update, no AI SDKs,
no endpoint baked in. It reaches the network only through commands you
invoke, and only to a place you named. Two families do so: the link.md
client verbs (`dbmd resolve/sync/grant/propose/subscribe`, plus
`key`/`mirror`/`serve` for identity and the reference node) talk to a hub
you configure, and `dbmd ask`/`do`/`build` talk to the model endpoint you
configure. (The link.md client shipped in v0.8.0; its spec, a v0 draft,
is public at github.com/carloslfu/link.md.)

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 harness (optional, so setup survives across sessions)

`dbmd spec` is enough on its own. To reach for db.md automatically in
future sessions, place a skill where your harness reads skills, in the
open Agent Skills format (a `db-md/` folder holding a `SKILL.md` with
`name`/`description` frontmatter and a thin body 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 or use your harness's own
skill installer. 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 show` / `dbmd graph` (and
`dbmd schema` for the store's declared type contracts); write with
`dbmd write` / `dbmd fm set` / `dbmd body set` / `dbmd section set` /
`dbmd link`; delete link-aware with `dbmd rm`; follow local changes with
`dbmd watch`; validate with `dbmd validate`; record with
`dbmd log` (store-wide actions like `validate` take a `-` object:
`dbmd log validate - -m "..."`). Every command takes `--json`. An
application can consume the same surface over loopback HTTP: `dbmd api`
serves every local verb as a route (`GET /v1` lists them; `/v1/events`
streams changes as SSE) so a local app — a browser page included — uses
the store as its backend without shelling out. 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, so never compose a ULID by hand.

You are the operator, so you do not need this yourself: the toolkit also
carries a small harness for callers that cannot host one. `dbmd ask`
(read verbs only), `dbmd do` (adds writes), and `dbmd build` (adds files
under a declared workspace) run these same verbs from a plain-English
request, against a model the operator configures. A local server is
autodetected (Ollama, LM Studio, llama.cpp), `--provider <name>` uses an
API key, and `dbmd login codex` or `dbmd login anthropic` uses a
subscription. `--effort off|minimal|low|medium|high|xhigh|max` sets how
hard it thinks. Raise it only when the operator wants an app or another
machine to ask the store directly; `dbmd api --ask` serves the same loop
over loopback HTTP.

## 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 itself and offer to wire a remote (a folder
the operator already syncs is also fine). 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.
Confirm where the store lives and how it is backed up before you scaffold.

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