accenture/mercury/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: ``bash 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), --staged / --range BASE [HEAD] (v4.41.0 — the [undeclared-reference] check over the staged index or a commit range; advisory exit 0, used by the pre-commit fragment and the CI floors), 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. A fixture that trips it is restructured — placeholder or env var — because even dummy test values are false positives in field security scanners; the callers honor a committed .agent/secret-scan-ignore only as a last-resort escape hatch, not seeded since v4.40.1). *Run the test suite (the cross-runtime contract — both implementations pass the same fixtures):* `bash python3 -m unittest agent-skills/memory-lint/scripts/test_memory_lint.py node --test agent-skills/memory-lint/scripts/test_memory_lint.mjs ``

1. 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 (a footer shown as an example inside an inline code span — the seeded header line — is documentation and is not counted, v4.41.2)

(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 — `[thread-stale]` (v4.40.0): an unchecked - [ ] open thread not referenced for

more than thread_stale_window sessions (default 40 — the invariant re-check cadence; a never-referenced thread counts from created). Its pin still protects it from decay and archival — this check never touches that. It says "a human should decide": a stalled thread is a closure signal, and the review lists every stalled thread in one human closure gate (REVIEW.md step 8) where the owner closes it (undelivered items recorded as deliberately dropped) or re-affirms it by naming it under ## Memory References — the only reset. The tool never closes a thread itself, and inspecting a stalled thread is not a use. (Field report, mercury-composable 2026-09-16: a pinned thread's "still open" items had all shipped, unnoticed for 184 sessions — pinned had come to mean unexamined.)

• advisory — `[undeclared-reference]` (v4.41.0, --staged / --range only): a memory fact whose

body changes in a commit must be declared in a session log staged with it — otherwise refresh-metadata reads the edit as non-use and the fact decays while in active use (field report: two Blueprint gaps a human had just closed were proposed for sweeping hours later; the footers and the reference log agreed, so only the diff could see it). Counted: edits, closures (- [ ] → - [x]) and new blocks in continuity.md, open-threads/*.md and vision.md. Not counted: footer-only lines (a metadata refresh), condensing an already-closed record (declaring it would defer its sweep), a verbatim move, a deleted block (archival). Silent when the change stages no session log. Remedy: add the id to ## Memory References.

• 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).

1. 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.

Notes — scope and philosophy

• Optional; the tool never runs it. The memory layer works without it (markdown + agent is the

runtime — no-build-step-agent-run). This is a verifier, invoked by the agent / human / CI at your direction.

• It lints the arithmetic and integrity; it does not judge meaning (what's worth recording,

supersession truth-state, contradictions) — that stays human/agent.

• Two runtimes so the deterministic check survives a missing one. The verifier ships in both

Python (memory-lint.py) and Node (memory-lint.mjs) — kept equivalent by a shared test contract — so a machine with only one of them still gets the script, not a hand count.

• Neither Python nor Node? Install one — do not hand-count. Decay arithmetic is only ever

script-verified, never counted by hand: an LLM hand-counting sessions_since_last_used has already over-archived a still-referenced fact, which is the whole reason this skill exists. So when neither runtime is present, do not estimate the decay by hand — surface this to the human and pause any archival decision: