jmagly/memory-lint

memory-lint

Validate the structural integrity and content health of a consumer's semantic memory. Composes eight built-in checks with any domain-specific lint rules declared by the consumer.

When to Use

• Periodic maintenance (weekly or per-iteration)
• Before phase transitions or releases — ensures memory is clean
• After bulk ingest operations
• When memory-log-append flags corruption
• CI/CD quality gates that include memory health

Parameters

--consumer (optional)

Consumer ID to lint. Resolved via ADR-021 D4 precedence: explicit > wrapper > auto-detect.

--fix (optional, flag)

Auto-apply safe fixes. Safe fixes: rebuild index, add missing cross-references, backfill log metadata. Unsafe fixes (resolving contradictions, deleting orphan pages) are reported but left for human action per the human-authorization rule.

--severity (optional, default: warning)

Minimum severity to include in output: error, warning, or suggestion.

Operation

1. Resolve consumer — determine which consumer to lint using ADR-021 D4 precedence (explicit > wrapper > auto-detect).
2. Load topology — read memory.topology from consumer's manifest.json to locate pages, index, log, and derived paths.
3. Compose checks — run each check against the resolved topology:

| # | Check | Source | Severity | |---|-------|--------|----------| | 1 | Broken @-mentions / references | mention-lint, link-check | error | | 2 | Orphan pages (no inbound links) | new — walks derivedPages, tracks inbound refs | warning | | 3 | Stale claims (source contradicts page) | doc-sync drift + contradiction scan | error | | 4 | Missing cross-references (concept appears in multiple pages without its own page) | new — entity extraction + frequency threshold | suggestion | | 5 | Index drift (page exists but index entry missing, or vice versa) | filesystem vs index.md comparison | warning | | 6 | Log integrity (append-only, no gaps, valid JSON Lines) | new — structural validation of .log.jsonl | error | | 7 | Provenance coverage | provenance-validate (only if ingestRequires includes provenance) | warning | | 8 | Domain-specific rules | delegate to consumer's declared lintRules skills | varies |

4. Aggregate findings — group by severity, deduplicate across checks.
5. Auto-fix (if --fix) — apply safe fixes only:
   • Rebuild index.md from filesystem state (fixes check 5)
   • Insert missing cross-reference links (fixes check 4)
   • Backfill missing log fields where deterministic (fixes check 6)
6. Log operation — call memory-log-append with op lint and finding counts.
7. Report — emit structured report grouped by severity.

Check Details

Broken @-mentions (check 1)

Delegates to existing mention-lint and link-check skills. Every @-reference and relative path in memory pages must resolve to an existing file. Broken references are severity error.

Orphan pages (check 2)

Walks all derivedPages paths and builds an inbound-reference graph. Pages with zero inbound links from other memory pages or the index are flagged as orphans. Severity warning because orphans may be entry points.

Stale claims (check 3)

Compares memory page claims against their source material using doc-sync drift detection. When a source has changed and the memory page hasn't been updated, flags the specific stale sections. Severity error because stale claims actively mislead.

Missing cross-references (check 4)

Extracts named entities and domain concepts from all pages. When a concept appears in 3+ pages but has no dedicated page or anchor, suggests creating a cross-reference page. Severity suggestion.

Index drift (check 5)

Compares filesystem contents under the topology's page directories against entries in index.md. Reports pages missing from the index and index entries pointing to nonexistent files. Severity warning.

Log integrity (check 6)

Validates the .log.jsonl file line by line: each line must be valid JSON with required fields (ts, op, consumer, actor). Checks for monotonic timestamps (append-only guarantee) and sequence gaps. Severity error.

Provenance coverage (check 7)

Only runs when the consumer's ingestRequires includes provenance. Delegates to provenance-validate to ensure every derived page has a valid provenance chain. Severity warning.

Domain-specific rules (check 8)

Reads lintRules from the consumer's manifest and delegates to each declared skill. Each rule returns findings with its own severity. This allows consumers to inject domain-specific validation without modifying the kernel.

Output Format

memory-lint report for <consumer>
================================

ERRORS (2)
  [broken-ref] pages/api-design.md:42 — @schemas/auth-flow.md does not exist
  [stale-claim] pages/deployment.md:18 — source changed 2026-04-10, page last updated 2026-03-15

WARNINGS (3)
  [orphan] pages/legacy-migration.md — no inbound references
  [index-drift] pages/new-feature.md — exists on disk but missing from index.md
  [provenance] pages/summary.md — no provenance record found

SUGGESTIONS (1)
  [missing-xref] "authentication" appears in 4 pages — consider a dedicated page

Summary: 2 errors, 3 warnings, 1 suggestion
Auto-fixable: 2 (run with --fix)

Error Handling

• Individual check failures do not abort the overall lint run. Failed checks are reported with severity error and a diagnostic message.
• If the consumer cannot be resolved, abort with a clear message listing available consumers.
• If the topology path is missing or malformed, abort with the specific missing field.

Schema Reference

@semantic-memory/schemas/memory-topology.md

Examples

# Lint the sdlc-complete consumer's memory
memory-lint --consumer sdlc-complete

# Lint with auto-fix, errors only
memory-lint --consumer research-complete --fix --severity=error

# Lint auto-detected consumer (inferred from current directory)
memory-lint

# Lint all consumers in the workspace
memory-lint --consumer all

Storage Routing (#934, #966)

This skill's persistence flows through resolveStorage('memory'). On the default fs backend the memory subsystem lives at .aiwg/memory/ and behavior is byte-identical to direct file writes. To redirect memory artifacts into Obsidian, Logseq, Fortemi, or another backend without changing this skill, configure .aiwg/storage.config (#934).

When this skill needs to read or write memory artifacts from a Bash step:

aiwg memory path                        # resolved root (fs only)
aiwg memory list --prefix research-complete/
aiwg memory get research-complete/index.md
echo "# index" | aiwg memory put research-complete/index.md
echo '{"op":"ingest","summary":"foo"}' | aiwg memory append-log research-complete/.log.jsonl

The aiwg memory append-log subcommand uses atomic O_APPEND (#976) on the fs backend — concurrent appenders don't race.