Aiwg memory-lint

Health-check any consumer's semantic memory by composing structural and domain-specific checks

install

source · Clone the upstream repo

git clone https://github.com/jmagly/aiwg

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jmagly/aiwg "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.agents/skills/memory-lint" ~/.claude/skills/jmagly-aiwg-memory-lint && rm -rf "$T"

manifest: .agents/skills/memory-lint/SKILL.md

source content

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

Resolve consumer — determine which consumer to lint using ADR-021 D4 precedence (explicit > wrapper > auto-detect).
Load topology — read
```
memory.topology
```
from consumer's
```
manifest.json
```
to locate pages, index, log, and derived paths.
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

Aggregate findings — group by severity, deduplicate across checks.
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)
Log operation — call
```
memory-log-append
```
with op
```
lint
```
and finding counts.
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