mml

Objective

Run fourteen health checks on the knowledge base and report all findings by severity.

This command is operational only. Do not write /mml, /memory-mason:mml, or their execution chatter back into the vault.

Path Resolution

Before any other reasoning, resolve vault config in this priority order:

1. Project ./.env
2. Project ./memory-mason.json
3. Global ~/.memory-mason/.env
4. Global ~/.memory-mason/config.json

Resolve:

• {vault}: absolute path to the Obsidian vault
• {subfolder}: plugin-managed subfolder inside the vault

Use the source that provides the vault path.

Subfolder rules:

• If the vault path comes from an .env file, use MEMORY_MASON_SUBFOLDER from that same file when present, otherwise default to ai-knowledge.
• If the vault path comes from memory-mason.json or ~/.memory-mason/config.json, use its subfolder.

Do not claim config is missing until you have attempted all four locations above. If none provide a vault path, fail fast with an explicit error that names every location checked.

Use these paths:

• Atlas: {vault}/{subfolder}/atlas/
• Concepts: {vault}/{subfolder}/concepts/
• Synthesis: {vault}/{subfolder}/synthesis/
• Index: {vault}/{subfolder}/index.md
• Raw captures: {vault}/{subfolder}/_raw/
• State file: {vault}/{subfolder}/_meta/state.json
• Manifest file: {vault}/{subfolder}/_meta/manifest.json
• Session context: {vault}/{subfolder}/_meta/context.md
• Build log: {vault}/{subfolder}/_meta/log.md

Execution Rules

• Glob all markdown files under {vault}/{subfolder}/atlas/, {vault}/{subfolder}/concepts/, and {vault}/{subfolder}/synthesis/. Also include {vault}/{subfolder}/index.md if it exists.
• Do not lint files under _raw/ or _meta/ as knowledge articles, except for the explicit checks below against _meta/manifest.json and _meta/context.md.
• Parse wikilinks in the form [[target]] from article content.
• Treat links starting with _raw/ as valid source references.
• Treat bare slug links such as [[foo]] as format violations handled by Check 13.
• Report every issue found. Do not stop after the first failure.

Checks

Check 1: Broken wikilinks (severity: error)

• For each knowledge article and the root index.md, find all [[wikilinks]].
• Skip links starting with _raw/.
• Skip bare slug links that contain no /. Check 13 handles them.
• Check whether each linked target exists at {vault}/{subfolder}/{link}.md.
• Report format:

ERROR [broken_link] file.md: Broken link: [[target]] - target does not exist

Check 2: Orphan pages (severity: warning)

• For each article in atlas/, concepts/, and synthesis/, count inbound links from other articles in those same content directories.
• Report any article with zero inbound links.
• Report format:

WARN [orphan_page] file.md: No other articles link to [[path/slug]]

Check 3: Uncompiled raw captures (severity: warning)

• Read {vault}/{subfolder}/_meta/state.json if it exists.
• Use the ingested map of YYYY-MM-DD -> hash.
• Glob all immediate subdirectories in {vault}/{subfolder}/_raw/ that match daily capture folders.
• For each folder, use the folder name YYYY-MM-DD as the source key.
• Report any raw capture folder that is not present in ingested.
• Report format:

WARN [orphan_source] _raw/YYYY-MM-DD/: Not yet compiled

Check 4: Stale articles (severity: warning)

• From state.json ingested entries, compare the current raw capture hash with the stored hash.
• Compute the current hash over the concatenated chunk contents in numeric order.
• If a raw capture changed since compilation, report it.
• Report format:

WARN [stale_article] _raw/YYYY-MM-DD/: File changed since last compilation

• Include a recommendation to run /mmc.

Check 5: Missing backlinks (severity: suggestion)

• For each article A that links to article B, check whether B also links to A.
• If A -> B exists but B -> A does not, report it.
• Report format:

SUGGESTION [missing_backlink] a.md: [[a/slug]] links to [[b/slug]] but not vice versa

Check 6: Sparse articles (severity: suggestion)

• Count words in each article, excluding YAML frontmatter.
• Report articles with fewer than 200 words.
• Report format:

SUGGESTION [sparse_article] file.md: Only N words (minimum recommended: 200)

Check 7: Large raw captures (severity: warning / error)

For each entry under {vault}/{subfolder}/_raw/:

• Read only numeric chunk files such as 001.md, 002.md, and so on.
• Sum the sizes of those chunk files for the daily capture folder.
• Ignore meta.json for size calculations.

Report captures over 500KB:

WARN [large_daily_folder] _raw/YYYY-MM-DD/: Total {size}KB across {n} chunks. Consider running /mmc.

Report captures over 2MB as error:

ERROR [oversized_daily_folder] _raw/YYYY-MM-DD/: Total {size}MB across {n} chunks. Run /mmc immediately.

Check 8: Manifest integrity (severity: error / warning / suggestion)

• Read {vault}/{subfolder}/_meta/manifest.json if it exists.
• If it is missing, report:

SUGGESTION [missing_manifest] _meta/manifest.json: No source-to-page manifest yet. Run /mmc to create lineage metadata.

• If it exists, it must be valid JSON with a top-level sources object.
• For each sources[sourceKey] entry:
  • hash must be a string
  • compiled_at must be a string
  • pages_created and pages_updated must be arrays of strings if present
  • every referenced page path must exist
• If a source key exists in both state.json and _meta/manifest.json and the hashes differ, report:

WARN [manifest_drift] _meta/manifest.json: Source key {sourceKey} hash differs from state.json

• If a referenced page is missing, report:

ERROR [manifest_page_missing] _meta/manifest.json: Listed page {path} does not exist

Check 9: Session context freshness (severity: warning / suggestion)

• Check whether {vault}/{subfolder}/_meta/context.md exists.
• If it is missing, report:

SUGGESTION [missing_context] _meta/context.md: No session context yet. Run /mmc to create one.

• If it exists, ensure frontmatter includes:
  • type: meta
  • title: "Session Context"
  • updated:
• If a required field is missing, report:

WARN [invalid_context] _meta/context.md: Missing required frontmatter field {field}

• If last_compile exists in state.json and context.md's updated timestamp is older than last_compile, report:

WARN [stale_context] _meta/context.md: Session context is older than the most recent compilation

Check 10: Unresolved contradictions (severity: warning)

• For each article in concepts/, search for [!contradiction] callout blocks.
• Each unresolved contradiction prevents the concept from reaching evergreen status.
• Report format:

WARN [unresolved_contradiction] concepts/file.md: Contains N unresolved [!contradiction] callout(s)

Check 11: Wikilink density (severity: suggestion)

• For each article in concepts/, count outbound [[...]] wikilinks in the body (excluding frontmatter and _raw/ source references).
• Report any concept page with zero outbound wikilinks.
• Report any atlas MOC page with fewer than 3 concept links.
• Report format:

SUGGESTION [isolated_concept] concepts/file.md: No outbound wikilinks — consider adding related concept links
SUGGESTION [thin_moc] atlas/file.md: Only N concept links (minimum recommended: 3)

Check 12: Knowledge gaps (severity: suggestion)

• For each article in concepts/, search for [!gap] callout blocks.
• Report the total count of concepts with knowledge gaps.
• Report format:

SUGGESTION [knowledge_gap] concepts/file.md: Contains [!gap] callout — awaiting enrichment from future sessions

Check 13: Wikilink format convention (severity: error)

• For each bare slug wikilink [[slug]] in knowledge articles and the root index.md, search for matching files at:
  • {vault}/{subfolder}/concepts/{slug}.md
  • {vault}/{subfolder}/synthesis/{slug}.md
  • {vault}/{subfolder}/atlas/{slug}.md
• If exactly one matching file exists, report the explicit target path that must be used.
• If more than one matching file exists, report the link as ambiguous and list every matching directory-prefixed candidate.
• If no matching file exists, report the bare slug as invalid and require an explicit directory-prefixed target.
• Report formats:

ERROR [short_form_link] file.md: [[foo]] should be [[concepts/foo]] — use full directory-prefixed paths
ERROR [ambiguous_short_form_link] file.md: [[foo]] matches [[concepts/foo]], [[atlas/foo]] — use an explicit directory-prefixed target
ERROR [short_form_link] file.md: [[foo]] is a bare slug link and cannot be resolved — use an explicit directory-prefixed target

Check 14: Source reference prefix (severity: error)

• Scan article bodies and the root index.md for wikilinks that start with [[{subfolder}/_raw/.
• Report any source reference that prepends the subfolder name. Source links must stay relative to the subfolder root.
• Report format:

ERROR [wrong_source_prefix] file.md: [[memory-mason/_raw/...]] should be [[_raw/...]] — remove the subfolder prefix

Output Format

Return results exactly in this structure:

## Knowledge Base Lint Report

### Errors (must fix)
- ERROR [broken_link] ...
- ERROR [short_form_link] ...
- ERROR [ambiguous_short_form_link] ...
- ERROR [wrong_source_prefix] ...
- ERROR [oversized_daily_folder] ...
- ERROR [manifest_page_missing] ...

### Warnings (should fix)
- WARN [orphan_page] ...
- WARN [large_daily_folder] ...
- WARN [unresolved_contradiction] ...

### Suggestions (nice to fix)
- SUGGESTION [sparse_article] ...
- SUGGESTION [isolated_concept] ...
- SUGGESTION [thin_moc] ...
- SUGGESTION [knowledge_gap] ...

### Summary
- Errors: N
- Warnings: N
- Suggestions: N

If no issues are found, output exactly:

✓ Knowledge base is healthy. No issues found.