Plan -> Work -> Evidence
1Plan the goal
2Execute one work node
3Record evidence
4Validate before moving on
Markdown Knowledge Graph
Git-native project memory for AI coding agents.
Give agents one durable loop: plan the goal, work one node, record evidence, and validate before the next session continues.
Pre-v1 public alpha. Markdown in your repo is the source of truth; no hosted index, daemon, or vector database is required.
Quickstart
First, prove the loop locally.
Install mdkg, initialize repo-local project memory, rebuild the access cache, inspect status, and validate graph health before handing work to an agent.
npm install -g mdkg
mdkg --version
mdkg init --agent
mdkg index
mdkg status
mdkg validatemdkg goal current
mdkg goal next
mdkg show WORK_ID
mdkg pack WORK_ID
mdkg handoff create WORK_ID
mdkg task done TASK_ID --checkpoint "Meaningful milestone"
mdkg validateWhy it matters
Bigger context helps. It does not replace project memory.
Longer context windows let an agent hold more text. Project memory gives that text durable shape: goals, decisions, active work, evidence, and checks in Git.
One concrete change: the agent starts from work, not vibes.
Without mdkg
- current goal lives in chat
- required checks are easy to miss
- handoff depends on memory
With mdkg
- work nodes carry status and refs
- packs bound agent context
- checkpoints record proof
Operating model
Plan -> Work -> Evidence
The public model is intentionally small: decide the goal, work one bounded node, then record proof before the next agent continues.
Plan the goal.
Goals, epics, PRDs, engineering designs, decisions, and rules describe what matters before an agent starts editing.
goal-1 -> epic-1 -> dec-1Execute one work node.
Features, tasks, bugs, tests, and research spikes give coding sessions a bounded unit with status, blockers, and checks.
mdkg goal nextRecord evidence.
Checkpoints, receipts, archives, validation output, and handoffs record why the current state is safe to continue from.
mdkg task done TASK_ID --checkpoint "...".mdkg/work/goal-1-ship-a-feature.md
- scope_refs
- task-1, task-2, test-1
- context_refs
- prd-1, dec-1, archive://research-notes
- evidence_refs
- chk-1, test receipts, review notes
Work model
Built around familiar SDLC shapes.
mdkg models software work with graph nodes that humans already understand and agents can route through deterministically.
Goals, epics, and features
Preserve intent across sessions, branches, and handoffs.
mdkg goal currentTasks, bugs, tests, and spikes
Give each coding session one actionable slice.
mdkg goal nextCheckpoints and evidence
Record commands, pass/fail state, warnings, and boundaries.
mdkg checkpoint newLocal-first trust
Boring files beat mystery memory.
Markdown stays readable. Frontmatter gives machines structure. Git gives review, history, branching, and collaboration. Generated indexes stay rebuildable.
Source files
Rules, decisions, PRDs, work nodes, checkpoints, skills, and archive sidecars live in the repo.
.mdkg/Generated access
Indexes and packs make retrieval fast without becoming hidden authority.
mdkg indexHandoffs
Transfer agent work without raw history dumps.
`mdkg handoff create` builds a bounded handoff from goal/work state, latest checkpoints, boundaries, required checks, next actions, and safety warnings.
mdkg goal next
mdkg pack WORK_ID --pack-profile concise
mdkg handoff create WORK_ID
mdkg task done TASK_ID --checkpoint "Meaningful milestone"Advanced alpha
Advanced surfaces stay optional.
These capabilities help larger agentic workflows, but users do not need them to understand or try the core loop.
Read-only MCP
Let agents inspect project memory without mutation, shell, SQL, or environment access.
Subgraphs and bundles
Plan across nested repos through read-only qids and deterministic bundle snapshots.
Local queues
Advanced project DB queue workflows are local delivery state, not hosted execution history.
Public alpha
Try it on a small repo first.
If this problem feels familiar, try the quickstart and star the repo if mdkg seems useful. If your agents lose context in a different way, open an issue; real workflow pain is shaping the public-alpha roadmap.