Getting data in

There is no ingester framework. db.md does not ship binaries that watch directories or poll mail servers. Getting data into a store is two mechanical steps you compose with tools you already have:

1. Land a file under sources/<kind>/. Use whatever moves bytes on your machine: mbsync, rsync, curl, a cron job, a Gmail export, a drag into a folder.
2. Stamp frontmatter with dbmd fm init. It writes a canonical YAML block (type, id, created, updated, and a default summary) onto a file that arrived without one.

That is the whole contract: land the bytes, then reconcile the frontmatter. The agent acting as curator takes it from there. It reads the new source, extracts records, and synthesizes conclusion records (meta-type: conclusion).

dbmd fm init, the reconcile primitive

# a file showed up in sources/ from outside; give it frontmatterdbmd fm init ~/db/sources/docs/acme-msa.pdf
# stamp a whole folder of externally-dropped filesdbmd fm init ~/db/sources/emails/2026/05/

fm init is idempotent: a file that already has valid frontmatter is left alone. After a bulk drop (an mbsync run, an rsync of a PDF archive), run dbmd fm init over the new paths, then dbmd index rebuild once to fold them into the catalog.

Writing a source directly

When your tool produces text rather than a file on disk, write it straight into the store and let dbmd resolve the path:

# source writes auto-shard by date under sources/<type>/<YYYY>/<MM>/dbmd write sources/emails --type email \  --summary "Re: Q2 renewal, Elena confirms pricing" \  --fm 'from=elena@northstar.io,subject=Re: Q2 renewal' \  --body-file ./elena-renewal.txt

dbmd write stamps the frontmatter, places the file in the date-sharded path, prints the resolved path, and updates the index.md catalog write-through, with no separate rebuild step.

Bring your own pipeline

Because ingestion is just "land a file, stamp frontmatter," any source becomes a few lines of shell or a small script:

• Mail: mbsync or the Gmail API downloads .eml files into sources/emails/, then dbmd fm init stamps them.
• Documents: a folder you drop PDFs and exports into, swept by dbmd fm init on a cron.
• Webhooks: a tiny receiver writes the payload to sources/webhooks/<event>/ and calls dbmd write.
• Exports: a HubSpot or Stripe export lands in sources/exports/, stamped on arrival.

No protocol, no SDK, no schema lock-in. The store is plain files; the only db.md-specific step is the frontmatter, and dbmd fm init is that step.

Extracting text from binaries

Sources are often PDFs, Office files, or HTML. dbmd extract reads those formats into plain text so the agent can search and synthesize their content without a separate tool:

dbmd extract ~/db/sources/docs/acme-msa.pdf

It handles PDF, docx, xlsx, epub, and html via permissively-licensed Rust crates. No GPL pdfgrep, no AGPL rga, nothing extra to install.

Importing an existing knowledge base

A one-time import of an existing base — an Obsidian vault, a Notion export, another wiki — is the bulk case of the same flow, with three rules so the result is a real db.md store and not a copy of the old one:

• Provenance, not polish, decides the layer. Anything you did not author is a source, however finished it looks. A polished external wiki lands under sources/; the meta-type: conclusion records are the synthesis your agent then writes from it. Don't file someone else's synthesis as your own conclusions.
• Reference vs. replace. Reference: the old base stays the source of truth — import it under sources/ and synthesize records from it. Replace: the store becomes its living home — the content becomes records/ (a vault you authored is your own synthesis → meta-type: conclusion), with the raw export kept under sources/ as the frozen rollback copy. Default to reference unless the store is meant to own the content.
• Don't port the old folder tree. Reorganize by type + meta-type, wiki-links, and the derived index — map by meaning, not by mirroring the source system's directories.

The migration is agent-driven (there is no dbmd import command): the agent evaluates what you have, proposes a plan, migrates on approval, preserves each source's provenance, verifies nothing was lost, and repoints whatever skills or scripts pointed at the old location.