Commands¶

Every stage is a file-to-file transform, so you can stop after any of them, edit the JSON by hand, and resume. mimem build is all of them at once.

All commands are shown with uv run; drop it if you have activated the environment.

build¶

The whole pipeline, source document to checkable programme.

uv run mimem build paper.pdf --out out/paper --listener listener.yaml

Writes audio.md, study.md, cards.json, manifest.json, plus doc.ir.json, registry.json, script.json and drop-report.md so that every intermediate stage is on disk. Exits non-zero if the result breaks a design rule.

inspect¶

What ingestion actually produced. Read this before trusting a build.

uv run mimem inspect paper.ir.json --outline --show 3

Prints the title and metadata, block and role counts, the section outline, the estimated straight read time, and every diagnostic the pipeline raised. This is how you find out that ingestion quietly ate the methods section.

explain¶

Why does this beat exist?

uv run mimem explain out/paper --beat t_4e4756d5592f

Prints the beat's type, the design rules that produced it, its cost in seconds, whether it is the source's or ours, the concept it serves with its scores, and the source sentence behind it. Beat IDs come from manifest.json.

Without this, tuning the system is guesswork — which is why it exists from the first version rather than as a debugging afterthought.

The stages, individually¶

ingest¶

uv run mimem ingest paper.pdf -o paper.ir.json

Reads the source into the canonical IR and cleans it. --no-clean stops after stage 1, so you can run clean separately and compare.

triage¶

uv run mimem triage paper.ir.json --report drop-report.md

Decides what reaches the narration and records why. The drop report is worth skimming: it is where you notice that a whole section was classified as boilerplate.

concepts¶

uv run mimem concepts paper.ir.json --listener listener.yaml --top 20

Extracts and scores the concepts, and writes registry.json. Prints a table of the top concepts with their difficulty, importance and budget, and says whether concreteness came from measured norms or a morphological guess.

The registry is meant to be edited. Anything under a concept's overrides key survives every future run.

elaborate¶

uv run mimem elaborate paper.ir.json --dry-run

Stage 6. --dry-run prints the planned calls and an estimate without making any:

29 call(s) to claude-opus-5: 3 x analogy, 4 x anchor, 11 x gloss, 11 x why
  estimated $1.67 -- an estimate, not a quote

plan¶

uv run mimem plan paper.ir.json --registry registry.json -o script.json

Stage 7: beats, segments, prompts, spacing, the review block. Builds the registry first if there is not one.

render¶

uv run mimem render script.json -o out/paper

Stage 8: the four artefacts, then lints the result.

lint¶

uv run mimem lint out/paper

Given a build directory it checks both halves — the narration text against the speakability rules, and the plan against the structure, retrieval and spacing rules. Given a bare audio.md it can only do the first, and says so. Exits non-zero on any error.

eval¶

uv run mimem eval

Builds every document in tests/fixtures/docs, measures the result, and compares it against the committed baseline in tests/fixtures/eval/baseline.json. Exits non-zero on a regression.

This is the check the linter cannot do. Nothing in mimem breaks loudly: a concept scorer drifts, the spacing scheduler finds one fewer slot, a triage rule eats an extra paragraph — and every one of those produces a programme that lints perfectly clean and teaches less. The metrics are the handful of quantities the design is a claim about, so a design that stopped being true shows up as a number that moved.

uv run mimem eval --update

Writes the current numbers down as the new baseline. This is the only way to make a real regression pass, and it is a separate command on purpose: it puts the worse number in the diff where a reviewer has to look at it.

--corpus DIR measures your own documents instead, which is the fastest way to find out whether mimem falls over on a field it has never seen. --json prints the metrics rather than the table.

narrate¶

uv run mimem narrate paper.ir.json -o out/plain

A straight reading: the retained content, verbalized, with no prequestions, retrieval or spacing. Useful for seeing what the structural layer actually adds, and as a fallback when a document defeats the planner.

profiles¶

uv run mimem profiles

Lists the available profiles with their headline settings, and which listener file is currently loaded.

version¶

uv run mimem version

Version, and the file formats this build can read.

Environment¶