Skip to content
mdkg Docs

Quickstart

The first path should be small, deterministic, and easy to review.

First-run setup

Section titled “First-run setup”

Install mdkg first if needed:

Terminal window
npm install -g mdkg
mdkg --version

Then initialize and validate the repo memory layer:

Terminal window
mdkg init
mdkg index
mdkg status
mdkg validate

Typical outputs:

  • In the 0.6.0 candidate, mdkg init creates .mdkg/ and compact root AGENTS.md / CLAUDE.md sections routing to .mdkg/AGENT_START.md.
  • mdkg index rebuilds generated search and capability caches.
  • mdkg status summarizes git, graph, selected goal, cache, and DB health.
  • mdkg validate reports graph errors and warning categories.

Use mdkg init --graph-only to omit agent setup. mdkg init --agent remains a compatibility spelling for compact setup. Published 0.5.2 used the older opt-in layout; compare mdkg --version with the instructions you are using. Project README, LICENSE, public discovery files and user-authored instructions outside mdkg-managed sections remain yours. Detailed generated guidance and canonical skills live under .mdkg, not in a universal root handbook.

You do not need an existing goal for this first proof. A new repo can validate successfully while mdkg goal next returns no node.

Expected receipt shape:

mdkg status   -> status: ok
mdkg validate -> ok: true

If you want a deterministic example before modeling your own repo, run the demo graph first-success path.

Plan -> Work -> Evidence

Section titled “Plan -> Work -> Evidence”

After setup, inspect or create work. Replace WORK_ID and GOAL_ID with concrete ids from your repo:

Terminal window
mdkg search "goal"
mdkg goal next
mdkg goal next GOAL_ID
mdkg show WORK_ID
mdkg pack WORK_ID

Use mdkg pack WORK_ID --pack-profile concise for summary-first node bodies in a shorter transfer pack. --profile concise is an equivalent alias; neither option changes traversal depth or node/byte limits by itself.

When a human or AI agent does work, record evidence before moving on:

Terminal window
mdkg task done TASK_ID --checkpoint "Done"
mdkg validate

For a bounded transfer between sessions, agents, or humans:

Terminal window
mdkg handoff create WORK_ID

Required checks in a goal are not executed automatically. Treat them as the checklist a human or agent must run, then record the evidence in a checkpoint, task note, or handoff.

Git closeout

Section titled “Git closeout”

When an agent run is ready to become a Git checkpoint, keep the closeout explicit:

Terminal window
mdkg validate
mdkg git inspect --json
git status --short
git diff --check

Use native Git to review and commit an explicit set of authored files. Graph validation and a clean diff do not authorize a commit or remote push. mdkg does not stage, commit, fetch or push for you. Optional DB snapshots are a separate explicit operation, not an automatic closeout side effect.

First principle

Section titled “First principle”

Use mdkg to make work state explicit. Let the repository, not a chat transcript, carry the durable plan, context, evidence, and closeout.

If no work exists yet

Section titled “If no work exists yet”

If mdkg goal next returns no node in a fresh repo, that is not a failed setup. It usually means there is no active goal or executable work yet. Create a small task, then inspect and pack it:

Terminal window
mdkg new task "Fix quickstart copy" --json
mdkg show task-1
mdkg pack task-1

If your installed CLI produces a different id, use the id printed by the command receipt.

Expected result:

  • mdkg new task ... --json prints the created task id.
  • mdkg show <created-id> returns that task.
  • mdkg pack <created-id> creates bounded context for a human or agent.