mdkg — Markdown Knowledge Graph
mdkg is a local-first CLI that turns structured Markdown into a searchable, linkable knowledge graph for engineering work.
It’s designed for:
- humans who want lightweight project documentation + task tracking in git
- AI coding agents/LLMs that need deterministic context bundles for code generation
mdkg is intentionally boring and portable:
- Node.js 18+
- written in TypeScript
- zero runtime dependencies (no sqlite, no external indexers)
- dev dependencies only: TypeScript (build-time) and Node 18+ (runtime)
- works with npm / pnpm / bun
---
Core idea
You store project knowledge as Markdown nodes with strict frontmatter (a small, stable schema). mdkg:
1) indexes those nodes into a local JSON cache (.mdkg/index/global.json)
2) provides fast search/list/show tools
3) generates deterministic context packs for agents (Markdown/JSON/TOON/XML exports)
Everything stays in your repo. No servers. No surprises.
---
Repository structure
mdkg lives in a hidden directory at the repo root:
- .mdkg/core/ — rules + “pinned” docs
- .mdkg/design/ — decisions + architecture
- .mdkg/work/ — epics/tasks/bugs/tests/checkpoints
- .mdkg/templates/ — document templates used by mdkg new
- .mdkg/index/ — generated cache (gitignored)
mdkg is root-only: you run commands from the repository root and mdkg indexes all registered workspaces without “discovering” nested repos.
---
Install
Pre-release note: this project is being actively developed and dogfooded.
Once published:
- npm i -g mdkg
- pnpm add -g mdkg
- bun add -g mdkg
---
Quickstart
1) Initialize mdkg in your repo:
``bash
mdkg init --llm --update-gitignore --update-npmignore
`
This creates .mdkg/ (rules, templates, work folders). Use the ignore-update flags to append recommended mdkg ignore entries.
2) Index your repo (cache is default behavior):
`bash
mdkg index
`
3) Create a task from a template:
`bash
mdkg new task "bootstrap cli" --status todo --priority 1 --tags cli,build
`
4) Search and list:
`bash
mdkg search "pack"
mdkg list --type task --status todo
mdkg show task-1
`
5) Generate a deterministic context bundle for an agent:
`bash
mdkg pack task-1 --format md --verbose
mdkg pack task-1 --pack-profile concise --dry-run --stats
`
---
Why this exists
LLMs are great at writing code, but they need high-quality, structured context.
mdkg makes that context:
- easy to author
- easy to query
- easy to hand to an agent
- reproducible across runs and contributors
This is also intended to be a compatible building block for “life git”-style productivity systems (which may later add richer databases like SQLite/Postgres). mdkg stays minimal and local.
---
Concepts
$3
A node is a Markdown file with strict YAML-like frontmatter fenced by ---.
Each node must include:
- id (unique per workspace; global uniqueness via qualified IDs)
- type (rule, prd, edd, dec, prop, epic, feat, task, bug, checkpoint, test)
- title
- / updated (YYYY-MM-DD)
Work items also typically include:
- status (backlog, blocked, todo, progress, review, done)
- priority (0..9, where 0 is most urgent)
$3
mdkg treats these frontmatter fields as explicit graph structure:
- epic, parent
-
- , blocks: [...]
- , next (chain navigation)
$3
If you want something searchable, put it in frontmatter:
- links: [ref, ref] (URLs or any searchable reference string)
- artifacts: [ref, ref] (build outputs, PRs, commits, releases, tarballs, etc.)
- refs: [id, id] (non-edge references)
- aliases: [text, text]
---
CLI commands (v1)
$3
- mdkg init
- create structure
- add ignore rules for caches
$3
- mdkg index
- builds
- cache is the default; mdkg will reindex automatically if stale
$3
- mdkg show
-
-
$3
- mdkg pack [--format md|json|toon|xml] [--verbose] [--depth ] [--edges ]
-
-
-
-
--verbose includes pinned core docs listed in .mdkg/core/core.md.
--pack-profile concise uses summary-oriented body shaping and strips code blocks by default.
If --out is omitted, packs are written to .mdkg/pack/pack___..
--max-tokens uses a heuristic estimate: ~tokens = chars / 4.
$3
`bash
mdkg init --llm
mdkg index
mdkg new task "..." --status todo --priority 1
mdkg list --status todo
mdkg pack --verbose
mdkg pack --pack-profile concise --dry-run --stats
mdkg validate
`
$3
- mdkg next [] [--ws ]
- follows chain if present; otherwise picks highest priority work item
- mdkg checkpoint new "
"<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br /> - creates a checkpoint node (a compression summary)</p><p class="my-3">- </code>mdkg doctor<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br /> - runs consumer diagnostics (node version, config, templates, index)<br />- </code>mdkg doctor --json<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br /> - emits machine-readable diagnostics for scripts/CI</p><p class="my-3">- </code>mdkg --version<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br /> - prints installed CLI version</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">- </code>mdkg validate<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br /> - strict frontmatter validation<br /> - missing required fields, invalid enums, dangling edges, cycles, duplicates<br /> - supports </code>--out <path><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> and </code>--quiet<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> for CI workflows</p><p class="my-3">- </code>mdkg format<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br /> - conservative frontmatter normalizer (idempotent)</p><p class="my-3">---</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Safety</h2></p><p class="my-3">mdkg is designed to avoid accidental leaks:<br />- cache files live under </code>.mdkg/index/<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> and must be gitignored<br />- publishing should use a strict </code>package.json.files<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> whitelist<br />- </code>.mdkg/<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> content should never ship to production builds</p><p class="my-3">---</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Contributing</h2></p><p class="my-3">This repo dogfoods mdkg. The source of truth for behavior is:<br />- </code>.mdkg/core/rule-*.md<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />- </code>.mdkg/core/guide.md<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />- </code>.mdkg/core/rule-2-context-pack-rules.md<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3">Suggested workflow:<br />1) create or update a task in </code>.mdkg/work/<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />2) run </code>mdkg validate<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />3) generate a pack for the task and use it as agent context<br />4) run </code>npm run smoke:consumer<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> before publishing to verify tarball install + onboarding flow</p><p class="my-3">---</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">License</h2></p><p class="my-3">MIT (recommended). Add a </code>LICENSE` file to confirm.<br /></p></div><div class="flex justify-center absolute inset-x-0 bottom-0 bg-gradient-to-t from-background via-background to-transparent pb-4 pt-16"><button data-slot="button" class="inline-flex items-center justify-center whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down mr-1 h-4 w-4"><path d="m6 9 6 6 6-6"></path></svg>Show more</button></div></div></div><template id="P:3"></template><template id="P:4"></template></div></div></div><div hidden id="S:3"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-dependencies" hidden="" id="radix-_R_aav5ubrb_-content-dependencies" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS=function(a,b){a=document.getElementById(a);b=document.getElementById(b);for(a.parentNode.removeChild(a);a.firstChild;)b.parentNode.insertBefore(a.firstChild,b);b.parentNode.removeChild(b)};$RS("S:3","P:3")</script><div hidden id="S:4"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-versions" hidden="" id="radix-_R_aav5ubrb_-content-versions" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS("S:4","P:4")</script><script>$RC("B:1","S:1")</script></body></html>