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 validateNew in v0.5.0 · Pre-v1 public alpha
Reusable loops for work that spans more than one goal.
Fork a read-only audit template, answer readiness questions, route the next authorized work, and keep decisions and evidence in your mdkg graph. mdkg preserves the process; your coding-agent harness executes agents and tools.
Fork a template
Start from the bundled read-only security audit template.
mdkg loop fork security-audit --scope . --dry-runResolve readiness
Confirm scope, permissions, and approval-gated actions.
mdkg loop plan LOOP_IDRoute authorized work
Select the next useful lane the loop is authorized to pursue.
mdkg loop next LOOP_IDInspect evidence and closeout
Review run evidence before required lanes are closed or waived.
mdkg loop runs LOOP_ID
Why 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 indexTeam customization
Customize standards without forking the kernel.
Use repo-local config overlays, managed skills, and core docs to adapt mdkg to your team while keeping the npm-installed CLI kernel upgradable.
Upgradable kernel
Keep mdkg installed from npm while repo-local config preserves standards, skill mirrors, and collaboration docs.
mdkg upgradeConfig overlays
Use `.mdkg/config.json` to preserve local standards, custom core docs, and managed upgrade behavior.
.mdkg/config.jsonCustom skill mirrors
Mirror canonical `.mdkg/skills` into arbitrary contained agent-local skill roots. `.agents/skills` and `.claude/skills` remain defaults.
mdkg skill syncCollaboration profile
Use `COLLABORATION.md` as the canonical operator profile while `HUMAN.md` remains a one-release legacy alias.
COLLABORATION.mdManifest naming
Author new reusable capability records as `MANIFEST.md`; `SPEC.md` remains a one-release compatibility alias with warnings.
mdkg manifest listHandoffs
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 --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.
Git closeout
Seal local state, prove push readiness, and push explicit checkpoints through system Git with external auth.
mdkg git push-readyLocal 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.