memory-lint

memory-lint

⚠️ Tool-managed skill provided by agent-memory (provenance: agent-memory-builtin). Don't edit it in place — it is overwritten on upgrade. To change behavior: fork it under a new skill name, or upstream a genuine fix to the agent-memory project (file an issue in its repo, or bring it to the tool maintainer) for back-port + validation. See SKILLS.md → "Tool-provided (system) skills".

A deterministic safety net for the evolving-memory layer. Decay is integer-counting by design, but an agent counting session files by hand can miscompute sessions_since_last_used and archive a fact that's still in use — this actually happened (a fresh-agent review over-archived recent facts, and a hand re-check still missed one). This skill moves that counting from agent judgment to a script, so the riskiest operation is verified against observable evidence.

When to use

• After running the memory review ritual (REVIEW.md) — verify its archival decisions.
• Before committing memory/ changes.
• In CI or a pre-commit hook (the reinforcement memory/PROTOCOL.md describes) — a non-zero exit fails the gate.

What to do

1. Run the bundled checker from the repo root. Two interchangeable runtimes — use whichever the machine has (stdlib/built-ins only, no install). Same flags, same output, same exit codes:

   python3 agent-skills/memory-lint/scripts/memory-lint.py    # Python 3 (>= 3.8)
   node    agent-skills/memory-lint/scripts/memory-lint.mjs    # Node (>= 18)
   

   Flags: --strict (also fail on warnings), --root PATH (point at a specific repo), and --scan-files FILE... (v4.34.0 — a standalone credential-class [secret-material] scan of arbitrary config files: token shapes, credential-key assignments, Authorization headers, private keys — no PII classes, since config files legitimately carry contact emails and paths; exit 1 on findings, values never echoed. This mode powers the .githooks/pre-commit secret guard and the CI floor's changed-config scan; the committed .agent/secret-scan-ignore handles JSON/properties exemptions at the caller level). Run the test suite (the cross-runtime contract — both implementations pass the same fixtures):

   python3 -m unittest agent-skills/memory-lint/scripts/test_memory_lint.py
   node --test          agent-skills/memory-lint/scripts/test_memory_lint.mjs
   

2. It checks, deterministically:
   • no id lives in both the live layer and the archive (a fact exists in exactly one place) — the live layer is continuity.md plus the one-thread-per-file memory/open-threads/ directory (v4.39.0), whose facts and checkbox pinning count exactly like continuity's;
   • [thread-file] — the thread-file contract: one thread block per file, filename thread-<id>.md matching the footer id (filename = the merge-free identity);
   • [duplicate-id] — an id must exist exactly once across the live layer; two live footers is the silent-fork shape of a same-id creation collision on parallel branches;
   • [duplicate-state-key] — a ## Project State scalar set twice (a union-style hand merge that kept both sides — absorbed from PR #27, credit: Roland Heusser);
   • no archived-as-faded fact was referenced within archive_window sessions — the decay-miscount guard: if it was, the count was wrong, so reactivate it;
   • advisory — continuity facts overdue for archival (sslu > archive_window), excluding core, superseded, and pinned - [ ] open threads (which never decay);
   • supersession links resolve (supersedes / superseded-by point at real footers);
   • .agent/version.md, if present, carries a parseable - **version:** X.Y.Z line — an empty/malformed manifest breaks Mode B upgrade detection (this was a real bug: a truncating stamp one-liner emptied it). A missing file is the valid pre-versioning baseline and is not flagged.
   • no leftover merge-conflict markers (<<<<<<< / >>>>>>> / diff3 |||||||) in the live top-level memory/*.md files plus memory/open-threads/*.md (continuity.md, instructions.md, vision.md, decay-policy.md, smoke-test.md) — an unresolved conflict there silently corrupts shared memory the agent reads as truth. sessions/ and archive/ are excluded (immutable/append narrative that legitimately quotes markers — e.g. a session log pasting a diff). A bare ======= line is not flagged (it's a valid Markdown setext heading underline).
   • advisory — [review-overdue]: sessions_since_last_review ≥ review_every (read from the last_review Project-State stamp), so a lapsed review ritual surfaces on every lint run + CI, not just when someone remembers to check;
   • advisory — [continuity-bloat]: more than continuity_max_facts decaying facts/threads (the primary lean signal — a count, immune to verbosity & session velocity), or more than continuity_max_lines lines (a coarse backstop). Both say "a review is due to lean it down."
   • advisory — [closed-thread-bloat] (v4.38.0): more than closed_narrative_max_lines (default 150) non-empty lines inside completed - [x] thread blocks — close records should wait out archive_window as 3–6-line stubs, not ship narratives (the full story lives in each thread's origin session log; a review condenses them per REVIEW.md step 5). Measured field cost: 64% of a hot repo's continuity was closed-thread narrative.
   • advisory — [stale-metadata]: a fact's stored tier disagrees with the tier recomputed from the reference log (review steps 2–3 — apply events / re-tier — were skipped), excluding core, superseded, never-referenced facts, and pinned - [ ] open threads (their tier label isn't enforced — pinned-ness protects them; v4.26.1). Clear it with the refresh-metadata skill (or a review).
   • advisory — [secret-material]: credential or PII shapes in any committed memory surface — memory/*.md, memory/sessions/, and memory/archive/ (where pasted output lives): known token formats (AWS / GitHub / GitLab / Slack / Google keys, private-key blocks, JWTs), credential-key assignments with literal values (including quoted JSON/YAML keys) and Authorization headers (e.g. rendered JAAS / clientSecret / bearer lines — anchored template placeholders and (REDACTED) are recognized as safe), emails (public noreply / git@ forms excluded), SSN and payment-card shapes (Luhn-verified), and absolute home paths (write ~). The report never echoes the matched value (that would amplify the leak into terminals and CI logs). Redact the hit to (REDACTED); if it was a live credential, rotate it — git history still holds the original. Waive a deliberately-quoted example (e.g. a log documenting a cleanup) by tagging that line lint:allow-secret-material. (Field incident, reported 2026-08-13: a client repo's DLP scanner caught a live OAuth client secret pasted into a committed session log.) Known-safe documentation examples still flag by design — e.g. AWS's canonical doc pair (AKIA…EXAMPLE and its secret partner): the guard keeps one simple contract (anything credential-shaped gets redacted or visibly waived) rather than an invisible built-in whitelist; quote such an example deliberately with the same lint:allow-secret-material tag (v4.34.2). The one built-in exemption is the tool's own opt-down knob — the guard's blocking message prints AGENT_MEMORY_SECRET_GUARD=advisory, so documenting that guidance is not a finding (env-var and git-config spellings, AGENT_MEMORY_SECRET_GUARD / agent-memory.secretguard; only the documented settings advisory/enforcing — any other value under those keys still flags, v4.34.2).
3. ERROR (exit 1) → fix per DECAY.md / REVIEW.md: reactivate an over-archived fact (move it back into continuity.md), de-duplicate, or repair a link. WARN is advisory — the next review may act on it.