Files on disk

Everything mcue knows is Markdown with YAML front matter under one directory. You can read it, diff it, grep it, and repair it by hand. This page is the map.

Layout

$MCUE_HOME/                        # ~/.mcue unless overridden
├── registry/
│   └── projects.yaml              # every registered project
└── projects/
    └── <project-id>/
        ├── project_state.md       # governed project-level state
        ├── decisions.log          # append-only decision record
        ├── checkpoints/
        │   └── <timestamp>.md     # one file per closeout
        └── lanes/
            └── <lane-id>/
                ├── lane_state.md  # governed lane-level state
                └── plan.md        # the active plan for this lane

Publishing adds Hub link metadata and a pending-operation outbox beneath $MCUE_HOME as well. Hub synchronisation only ever reads and writes below $MCUE_HOME — it does not touch your source repository.

Conventions

Every governed file is Markdown with a YAML front-matter block. The front matter carries the machine-readable fields; the body carries the prose. That split is why the files stay useful to both a parser and a person.

• Identifiers are lowercase, hyphen-separated, and stable.
• Timestamps are the checkpoint filename as well as a field, so the directory sorts chronologically without parsing anything.
• Append-only files are never rewritten in place; corrections are new entries.

registry/projects.yaml

The index of every registered project: its id, where it is anchored, and its lifecycle state. mcue init adds an entry, mcue project archive marks one out of the active portfolio, and mcue project delete removes it along with the state directory.

This is the file mcue index reads first. If a project has vanished from index but its directory still exists, look here.

project_state.md

Project-level governed state: title, description, current objectives, and the derived status that mcue index surfaces. Refreshed by mcue closeout; editable for metadata via mcue update.

lanes/<lane-id>/lane_state.md

The same idea, scoped to a lane: what this strand of work is doing, its current status, and the pointer to where to resume it. Every project has a default lane, so this file exists even if you never create one explicitly.

lanes/<lane-id>/plan.md

The active plan: an ordered set of steps with their state. Closing a plan archives it rather than deleting it, so earlier plans stay answerable.

decisions.log

An append-only record of decisions and the reasoning behind them, newest entries appended at the end. This is the file that answers "why did we do it that way" eighteen months later, and it is the one most worth writing carefully.

checkpoints/<timestamp>.md

One file per closeout, named by timestamp. Each carries intent, outcome, blockers, next action, and the resume pointer, plus provenance — which actor and which substrate produced it.

Checkpoints are append-only and never rewritten. Degraded and retroactive checkpoints are marked as such in front matter, so a later reader can tell how much to trust them. See Recover a broken session.

Resume packets

Not a file. A resume packet is assembled on demand from current state and capped at roughly 300 or 1000 tokens depending on the tier requested.

This matters more than it sounds: because packets are derived rather than stored, improving how they are built never rewrites your history.

The audit log

A local record of what happened — reads, writes, which client, which substrate. Read it with:

mcue audit

Provenance is what makes agent writes safe to allow. Every write is attributable to an actor and a substrate, so a checkpoint written by an agent through an MCP client is distinguishable from one you typed.

Validation

mcue validates state on read and on write, and the same validator runs behind the CLI, the local MCP server, and the hosted Hub endpoint. There is no looser path into your state — an operation an agent submits is checked exactly as one you type is.

If you hand-edit a file into an invalid shape, the next command that reads it will say so rather than silently reinterpreting it.

Backing it up

$MCUE_HOME is a normal directory. Put it in a private Git repository, include it in your usual backups, or point MCUE_HOME at a synced folder:

export MCUE_HOME="$HOME/work/.mcue-state"

Hub is not a backup — it holds accepted state for published projects only, which is a different thing from a copy of everything on this machine.