{"id":50458556,"url":"https://github.com/carloslfu/db.md","last_synced_at":"2026-07-02T01:02:00.079Z","repository":{"id":361458367,"uuid":"1250930357","full_name":"carloslfu/db.md","owner":"carloslfu","description":"Your database is a folder of markdown files, and the agent is the engine. The open standard for databases in plain files. No vector store, ever.","archived":false,"fork":false,"pushed_at":"2026-07-01T23:40:18.000Z","size":3332,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T00:05:19.909Z","etag":null,"topics":["agent-memory","agentic","agentic-ai","ai","ai-agents","cli","database","knowledge-base","llm","markdown","note-taking","obsidian","pkm","plaintext","rust","second-brain"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carloslfu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":"CLA.md"}},"created_at":"2026-05-27T05:04:47.000Z","updated_at":"2026-07-01T23:35:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/carloslfu/db.md","commit_stats":null,"previous_names":["carloslfu/db.md"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/carloslfu/db.md","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carloslfu%2Fdb.md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carloslfu%2Fdb.md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carloslfu%2Fdb.md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carloslfu%2Fdb.md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carloslfu","download_url":"https://codeload.github.com/carloslfu/db.md/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carloslfu%2Fdb.md/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35028642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","agentic","agentic-ai","ai","ai-agents","cli","database","knowledge-base","llm","markdown","note-taking","obsidian","pkm","plaintext","rust","second-brain"],"created_at":"2026-06-01T03:33:21.189Z","updated_at":"2026-07-02T01:02:00.071Z","avatar_url":"https://github.com/carloslfu.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# db.md\n\n**Your database is a folder of plain text files.** No daemon, no fixed\ntables, no query language in the way. Every record is one markdown file\nyou can open, read, and edit by hand. The relationships between records\nare written into the text itself.\n\nThe folder is the database.\n\nBefore agents, text was documentation. After agents, text is operational\nstate. A capable agent reads the files, writes them, links them, repairs\nthem, and finds the connections between them by meaning. The agent is the\nengine, and the engine improves on its own: your files ride the model\ncurve.\n\nHere is a record. It is a file:\n\n```markdown\n---\ntype: trip\nname: Kyoto spring trip\ndates: 2026-04-11..2026-04-18\nstatus: planning\ntravelers:\n  - [[records/people/maya]]\n  - [[records/people/jules]]\nhome_base: [[records/places/kyoto-station]]\ncreated: 2026-01-12\nupdated: 2026-06-03\n---\n\n# Kyoto spring trip\n\nSeven days in Kyoto with Maya and Jules. The current plan keeps the first\ntwo nights near [[records/places/kyoto-station]], then moves to the ryokan\nfrom [[sources/emails/2026-06-03-ryokan-confirmation]]. Jules wants temples\nin the morning, Maya wants one open afternoon for wandering, and nobody wants\nanother spreadsheet.\n```\n\nThe YAML block on top is frontmatter: the structured surface of the record,\nsimple labels the agent can sort, filter, and repair, with store-specific\nschemas declared in `DB.md`. The `[[double brackets]]` are the\nrelationships, the same links a wiki uses. The body holds what a database\nrow usually throws away. A person reads it. Git versions it. A model reads\nit with full context. That is the whole format.\n\n**A huge class of future software will not be built as database + backend +\nfrontend. It will be built as readable context + agent harness + generated\nsurface. db.md is the persistence layer for that world:** records are\nmarkdown files like the one above, fields are YAML frontmatter,\nrelationships are wiki-links, schemas and policies live in one `DB.md`, an\nagent operates all of it, and there is no vector database anywhere.\nDesigned for stores that grow into millions of plain files. The full\nargument is in [WHY.md](WHY.md).\n\n## Quick start\n\ndb.md is operated by agents, and the installer is text. Paste this into\nClaude Code, Codex, or any agent with a shell:\n\n```text\nRead https://raw.githubusercontent.com/carloslfu/db.md/main/llms.txt and set\nup db.md here: install dbmd, load the standard, and create a store. If I\nhave existing notes or a knowledge base (an Obsidian vault, a Notion export,\na folder of files), evaluate it first and show me a migration plan before\nmoving anything.\n```\n\n\"Here\" is whatever folder your agent is open in: start your agent where\nyour notes live to migrate them, or in an empty folder for a fresh start. The agent\nreads [llms.txt](llms.txt), installs one small binary, loads the contract,\nand either scaffolds a fresh store or maps your existing notes into one\nwith your approval, preserving where every piece came from. Stores are\nversion-controlled by default: plain files that Git or any sync service\nsaves and carries.\n\nInstalling by hand gets you the same binary, about 6MB, macOS and Linux,\nno toolchain:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/carloslfu/db.md/main/scripts/install.sh | sh\n# or: brew install carloslfu/tap/dbmd\n# or: cargo install dbmd-cli    # build from source\n```\n\nThen, from inside a store:\n\n```bash\ndbmd spec                                  # print the whole standard\ndbmd search \"renewal\" --in records         # search content and frontmatter\ndbmd query --type contact --where status=active   # filter by frontmatter\n```\n\nEvery command speaks `--json`, so anything you build on top reads it\ncleanly. A prompt that ends in an installed binary deserves receipts:\n[Safe to paste](#safe-to-paste) has them.\n\n## Watch it operate\n\nThe examples in this repo are complete stores. Take\n[`examples/agency-knowledge-base`](examples/agency-knowledge-base), the\nstore of a twelve-person agency. Ask your agent to log a client kickoff,\nand this is the loop it runs:\n\n```bash\n$ dbmd query --type client --where status=active\nrecords/clients/brightmore-group.md\nrecords/clients/lumio.md\nrecords/clients/riverkeep.md\n\n$ dbmd write records/meetings/2026-07-01-lumio-kickoff --type meeting \\\n    --summary \"Lumio spring campaign kickoff; scope and dates agreed\" \\\n    --fm date=2026-07-01 --fm 'client=[[records/clients/lumio]]' \\\n    --fm 'attendees=[[records/contacts/maya-okonkwo]]'\nrecords/meetings/2026/07/2026-07-01-lumio-kickoff.md\n\n$ dbmd graph backlinks records/clients/lumio\nrecords/contacts/maya-okonkwo\nrecords/contacts/theo-ramos\nrecords/meetings/2026/07/2026-07-01-lumio-kickoff\nrecords/meetings/2026-05-21-lumio-brand-review\nrecords/projects/lumio-brand-identity\n\n$ dbmd validate\n0 issue(s): 0 error(s), 0 warning(s), 0 info\n```\n\nThe write landed in the right date shard without anyone doing folder math.\nThe new meeting shows up in the client's backlinks. And `validate` held it\nto the `meeting` schema this store declares in its `DB.md`: link an\nattendee who doesn't exist and it fails loudly with `WIKI_LINK_BROKEN`.\nThe binary is deterministic plumbing; the agent does the thinking.\n\n## How it works\n\nOne directory. Two folders for your data, one file that runs the place,\nand a derived catalog.\n\n```\ndb/\n├── DB.md          # identity, agent instructions, policies, schemas\n├── index.md       # a catalog the agent keeps current\n├── sources/       # evidence, kept as it arrived: emails, PDFs, exports, and\n│                  #   notes that capture what someone told the agent\n└── records/       # everything the agent authors: contacts, invoices,\n                   #   meetings, and synthesis, tagged by a meta-type field\n```\n\n`sources/` holds evidence. `records/` holds what the agent writes, where a\n`meta-type` field separates atomic facts (`fact`, the default) from\noperating state (`operational`) and from the synthesis the agent keeps\ncurrent as the facts move under it (`conclusion`).\n\nPicture a one-person agency running a couple of clients:\n\n```\ndb/\n├── DB.md\n├── sources/\n│   ├── contracts/northwind-msa.pdf\n│   ├── emails/2026/06/2026-06-02-lumen-invoice-question.md\n│   └── notes/2026/06/northwind-wants-weekly-updates.md   # told_by: Dan Ruiz\n└── records/\n    ├── clients/northwind.md                    # retainer, renewal, status\n    ├── contacts/dan-ruiz.md                    # Northwind, founder\n    ├── projects/northwind-site-redesign.md     # meta-type: operational\n    ├── invoices/2026-039-northwind.md\n    ├── accounts/northwind.md                   # meta-type: conclusion -\n    │                                           #   the account, synthesized\n    └── synthesis/pipeline.md                   # meta-type: conclusion -\n                                                #   every client, next step\n```\n\nEach client is some evidence in `sources/` and a spread of records linking\nback to the contract or call that produced them. Add a client and the shape\nrepeats. Nothing new to stand up.\n\n`DB.md` is the file that matters most: the store's identity, the\ninstructions for the agent, the policies it follows, and the schemas your\nrecords conform to. There is no config format to learn. The agent writes\n`DB.md` for you, and `dbmd validate` holds every record to it.\n\n| Old stack part | db.md shape |\n|---|---|\n| Row | Markdown record |\n| Column | YAML frontmatter field |\n| Foreign key | Wiki-link |\n| Migration | Text edit to `DB.md` plus agent repair |\n| Index | `index.md` for browsing, `index.jsonl` for structured reads |\n| Backend logic | Agent harness plus deterministic `dbmd` operations |\n| UI | Chat, voice, forms, dashboards, or whatever the agent generates |\n\nThe format is at v0.3, and its versioning policy from here is additive:\nnew fields and codes layer on, existing stores keep validating. The\ncontract is [SPEC.md](SPEC.md); the history is the\n[CHANGELOG](CHANGELOG.md).\n\n## What it is for\n\nSoftware that is mostly meaning-rich context under a surface: a\n[local CRM](examples/customer-database), an\n[ops tracker](examples/ops-store), a contract register, a decision log, a\nsupport queue, a [research system](examples/research-wiki), a\n[second brain](examples/personal-second-brain), a company brain, a family\ntool, a trip planner. Underneath, these are records, relationships,\nworkflows, and judgment. Most were always too small, too specific, or too\nalive to justify becoming SaaS products. With an agent operating the\nfiles, they stop needing to be products at all.\n\nHard truth still exists. Payments, ledgers, high-concurrency shared state,\nsub-millisecond reads, and billion-row analytics still want hard engines.\nPostgres is for authoritative machinery; db.md is for living context.\n\n## How it compares\n\nAsk one question of every option: **who operates the live store?** A\nvendor's app operates Notion and Airtable; you rent the machinery and get\nthe AI they bolt on, when they ship it, inside their walls. A retrieval\npipeline operates a vector-memory stack (Mem0, Zep, GraphRAG); embeddings,\ngraphs, and rerankers stand between the agent and your data, and you keep\nthem synced. A schema and an app operate SQL; better models write better\nqueries, but the store's meaning lives in schema and app code, outside the\ndata itself.\n\nIn db.md, the agent operates the store directly, on files you can read.\nNothing sits in between. **db.md computes, stores, and searches no vector,\never.** Semantic recall is the agent widening its own search in plain\nlanguage, and a dated file can say when a fact was true and what replaced\nit; an embedding by itself cannot.\n[Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)\nshowed a model can maintain a coherent markdown world; db.md turns that\ndemonstration into a database format and keeps it the size he drew.\n\nThe full field, including parametric memory and the interchange formats, is\nworked through in [WHY.md](WHY.md#the-comparison-field). db.md composes\nwith AGENTS.md for instructions and MCP for tools: different layers, not\nrivals.\n\n## How far it scales\n\nDesigned for millions of plain files. A person who indexes their work\nemail adds about 44,000 files a year; a ten-person shared store can cross\na million files in two to three years. The agent never pays the\nwhole-store cost in its interactive loop: every type folder keeps a small\nderived index\n(`index.md` for people, `index.jsonl` for machines), high-volume folders\nshard by date when the agent writes through `dbmd write`, and the\ninteractive loop is O(changed), not O(store). Whole-store validation and\nindex rebuilds are sweep jobs that run off the loop. The interactive\nbudgets are measured at the 10k-file tier in CI; the million-file tier is\nan opt-in test with published targets. Both are in\n[tests/PERF.md](tests/PERF.md), and the full scale math is in\n[WHY.md](WHY.md#how-far-files-go).\n\nOne writer, many readers. A store assumes a single curating agent; the\nv0.3 contract says so plainly, and teams share a store the way they share\na repo: people direct the curator and read freely, clones move through\ngit, append-only logs merge by union, and the derived indexes regenerate\nwith `dbmd index rebuild` rather than merge. Want SQLite or a search index\non top? Build one; the files stay the source of truth.\n\n## Safe to paste\n\nStart with the fact that matters most: **the binary makes no network\ncalls.** No telemetry, no API keys, no AI SDKs; `dbmd` reads and writes\nlocal files and does nothing else (check `Cargo.lock`: there is no HTTP\nclient in the tree). And you don't have to take this page's word for\nanything. The audit is one more prompt:\n\n```text\nRead scripts/install.sh and .github/workflows/release.yml in carloslfu/db.md\nand tell me whether this is safe to install.\n```\n\nFor the reader who verifies by hand, the chain:\n\n- **The installer is readable.** [`scripts/install.sh`](scripts/install.sh)\n  is about 160 lines of POSIX sh: detect the platform, download the tarball\n  from this repo's GitHub Releases, verify its SHA-256 against the\n  release's `SHA256SUMS`, install to `~/.dbmd/bin`. No sudo, no\n  shell-config edits, nothing outside that folder. `DBMD_VERSION` pins a\n  version. The checksum proves integrity; provenance is the separate check\n  below.\n- **Every binary traces back to source.** Releases are built in CI from a\n  tagged commit, never on a laptop, and every tarball carries a signed\n  build-provenance attestation anyone can verify:\n  `gh attestation verify dbmd-\u003cversion\u003e-\u003ctarget\u003e.tar.gz --repo carloslfu/db.md`\n- **No stored publish token.** crates.io releases go through Trusted\n  Publishing (OIDC): CI mints a short-lived token per release.\n- **The dependency tree is audited in CI.** Small, permissively licensed,\n  zero AI crates, license allowlist machine-enforced, RustSec advisories on\n  every dependency change and on a daily schedule.\n\nIf you want no prebuilt binary at all, `cargo install dbmd-cli` builds from\nsource. [SECURITY.md](SECURITY.md) holds the threat model, including the\none that matters in daily use: prompt injection through ingested sources,\nand why treating sources as data rather than instructions is the\nharness's job. [RELEASING.md](RELEASING.md) documents the release pipeline\nend to end.\n\n## The agent is the engine\n\ndb.md ships no model and no API keys. The curator is whatever agent you\nalready use: Claude Code, Codex, or your own. Its whole flow is four moves:\ndiscover db.md, run `dbmd spec` for the contract, read the store's `DB.md`,\noperate with `dbmd`. You are never locked to a model, because the model is\nthe one part you bring and the one part that keeps improving.\n\nTo make your agent reach for db.md on every session, place the canonical\nskill ([`skills/db-md/SKILL.md`](skills/db-md/SKILL.md), in the open\n[Agent Skills](https://agentskills.io) format) where your harness reads\nskills. There is no install command for this, on purpose: copy the file,\nuse your agent's own skill installer, or tell the agent to set itself up.\n\n## The toolkit\n\ndb.md is plain files, so any tool that reads files works. The reference\ntoolkit is one Rust binary, `dbmd`, in the git / cargo / kubectl shape: one\nbinary, with subcommands for read, write, validate, extract, graph, index,\nand log.\n\n- **Embedded ripgrep.** Fast search with no separate tool to install.\n- **Built-in extraction.** `dbmd extract` pulls text out of PDF, docx,\n  xlsx, epub, and html.\n- **Zero AI dependencies.** No provider SDKs, no API keys, no model calls\n  in the binary. The agent runtime is yours.\n- **A library underneath.** All the logic lives in `dbmd-core`. Run\n  `cargo add dbmd-core` to build your own db.md-aware tool.\n\nSee [TOOLS.md](TOOLS.md) for the full command surface and the agent\nbootstrap.\n\n## What's in this repo\n\n```\ndb.md/\n├── SPEC.md          # the format, the curator contract, the validation codes (v0.3)\n├── WHY.md           # the argument: the stack collapse, the comparison field, the scale math\n├── TOOLS.md         # the toolkit: every subcommand, install, agent bootstrap\n├── llms.txt         # the agent-readable entry point\n├── crates/\n│   ├── dbmd-core/   # the library: parser, store, graph, validate, query, index, log\n│   └── dbmd-cli/    # the dbmd binary (thin wrappers over the library)\n├── examples/        # five complete stores: research wiki, ops, second brain, agency, CRM\n├── tests/corpora/   # canonical, edge-case, format, scale, and agent-eval stores\n└── skills/db-md/    # the canonical Agent Skill you place in your own agent\n```\n\nThe examples and corpora are the proof surface: small enough to read,\ncomplete enough to exercise the real contract, and varied enough to show\nthe shape across personal, team, research, agency, and customer-data\nstores.\n\n## Use it on its own\n\ndb.md is an open standard, and it needs nothing else. A plain markdown vault\nbecomes a db.md store, with no platform and no account required: a personal\napp, a family tool, an Obsidian vault, a research wiki, an agent-built\ninternal tool, a customer database, any runtime with a folder of markdown.\nThe [spec](SPEC.md) is the contract. The runtime is replaceable. **The\nfiles outlast both.**\n\n## License\n\n[Apache-2.0](LICENSE), including the Apache patent grant and\nNOTICE/attribution terms. First-time contributors sign the Apache ICLA\nthrough the CLA Assistant bot. See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Security\n\nReport vulnerabilities privately through GitHub's \"Report a vulnerability\"\nbutton on the Security tab. Do not open a public issue for a security\nproblem. See [SECURITY.md](SECURITY.md) for the threat model. The supply\nchain is covered in [Safe to paste](#safe-to-paste) above;\n[RELEASING.md](RELEASING.md) documents the release pipeline end to end.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarloslfu%2Fdb.md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarloslfu%2Fdb.md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarloslfu%2Fdb.md/lists"}