# Markdown Knowledge Graph agent primer

Markdown Knowledge Graph (mdkg) is git-native project memory for AI coding agents and AI-assisted software engineering.

## What mdkg is

- a local-first CLI
- a Markdown + frontmatter graph
- a Plan -> Work -> Evidence operating model
- a deterministic context-pack builder
- a goal/task/spike/checkpoint lifecycle tool
- an agent handoff tool
- a validation and repair aid
- an advanced alpha substrate for subgraphs, bundles, workflow mirrors, read-only MCP, and local queue workflows

## Current public-alpha capabilities

- work graph nodes for goals, epics, tasks, tests, spikes, decisions, and checkpoints
- deterministic packs and sanitized handoffs
- status, doctor, validation, heading-format summaries, and fix planning
- public project DB queue CLI plus a queue adapter contract
- read-only local MCP server
- graph clone, template import, branch-safe ID repair, subgraphs, and bundles

## What mdkg is not

- not an autonomous coding agent
- not an autonomous execution runtime
- not a hosted memory service
- not a vector database
- not a daemon
- not a comprehensive secret scanner
- not a production queue/event ledger

## Canonical agent path

1. Read AGENT_START.md.
2. Run mdkg status.
3. Inspect the current goal with mdkg goal current.
4. Run mdkg goal next.
5. Show and pack one work node with mdkg show WORK_ID and mdkg pack WORK_ID.
6. Do work outside mdkg.
7. Record evidence with checkpoints, handoffs, or task updates.
8. Validate with mdkg validate before closeout.

## Plan -> Work -> Evidence

- Plan: read repo guidance, inspect graph state, and choose one bounded work node.
- Work: claim the node only when mutating lifecycle state, then make changes outside mdkg.
- Evidence: run checks, record proof, create a checkpoint or handoff, and validate before closeout.

## Core commands

- mdkg init --agent
- mdkg index
- mdkg status
- mdkg validate
- mdkg search <query>
- mdkg show WORK_ID
- mdkg goal current
- mdkg goal next
- mdkg goal claim GOAL_ID WORK_ID
- mdkg pack WORK_ID --pack-profile concise
- mdkg handoff create WORK_ID
- mdkg task done TASK_ID --checkpoint "Meaningful milestone"

## First-success path

1. Install mdkg and run mdkg init --agent, mdkg index, mdkg status, and mdkg validate.
2. If mdkg goal next returns no node in a fresh repo, create or select work before treating setup as broken.
3. Use the demo graph docs when you want a deterministic local success path before modeling your own repo.
4. Use returned ids from command receipts instead of hardcoding placeholder ids in real repos.

## Safety boundaries

Do not store these in mdkg nodes, packs, checkpoints, or handoffs:

- raw secrets
- tokens
- private keys
- provider payloads
- unredacted prompt text
- private graph dumps
- bulky runtime traces

Handoff raw-marker warnings and no-secret checks are safety aids, not comprehensive data-loss prevention.

## Agent-readable paths

- /quickstart
- /trust
- /alpha
- https://docs.mdkg.dev/ (canonical docs)
- /llms.txt
- /llms-full.txt
- /sitemap.xml

Use the generated CLI reference from docs/_generated/cli-reference.md when working from the repository source.