Agent Skills: Memory clean

Memory clean

Contract

| Field | Bound contract | |---|---| | Trigger | A human explicitly asks to audit memory or find stale or duplicate memories. | | Authority | Human-only for external or irreversible effects: inspect the named memory store, but preview each target and consequence and obtain explicit confirmation for each repair group before changing data at rest. | | Side effect | Create one snapshot copy, then make only confirmed edits, merges, archives, or deletions inside $MEMORY_DIR, which is outside version control. | | Done | A fresh deterministic audit reports zero critical findings, and every residual warning or informational finding is reported. |

Inputs

• Required: the project whose durable memory store is being audited, or an explicit MEMORY_DIR override.
• Optional: SESSION_HISTORY_GLOB for session-based staleness evidence and MEMORY_CLEAN_SKILL_SCRIPTS when the bundled scripts are installed outside the default skill directory.
• The path resolver must successfully produce an existing memory directory. Session history may be omitted, but then session-based feedback staleness cannot be assessed and must be reported as unavailable.

Procedure

1. Resolve the bundled script directory, then run resolve-paths.sh memory_dir and resolve-paths.sh session_history_glob. Reject resolver errors, control characters, forbidden shell metacharacters, and unsafe whitespace rather than interpreting them. Done when: both paths resolve without error or the run stops with a blocked diagnostic.
2. Bound the operation to the resolved $MEMORY_DIR; do not create new memories, edit another store, redact suspected credentials, or widen the requested scope. Done when: the scope boundary is stated and no out-of-scope target is queued.
3. Before any repair, create a timestamped recursive snapshot of $MEMORY_DIR in /tmp and record its path. Done when: the snapshot directory exists and its path is recorded, or the run stops without changing the store.
4. Run audit-memory.sh "$MEMORY_DIR" "$SESSION_HISTORY_GLOB" and preserve its JSON output. The deterministic audit checks index orphans and dangling links, schema and required sections, index size limits, credential patterns, fix-recipe and path-pinned content, relative dates, body-line Jaccard similarity above 0.70, missing reference targets, past project dates without historical-anchor phrases, and feedback rules contradicted by session evidence. Done when: the JSON report is captured and preserved regardless of exit status.
5. Render all findings grouped as critical, warning, and informational. For each staleness finding, include the reported session identifiers and available contradiction context. Label unavailable session evidence instead of inventing it. Done when: every finding is rendered under exactly one severity with its evidence attached.
6. Group proposed repairs by mechanism and show an exact preview: add an orphan to MEMORY.md; remove a dangling index line; merge a near-duplicate pair while naming the superseded file and index update; make a targeted structural edit; or update, archive, or delete a stale memory. Show a file's content before proposing its deletion. For a suspected credential, report the critical finding and make no redaction. Done when: every repair group has an exact preview and no unpreviewed repair is queued.
7. Obtain explicit human confirmation separately for each repair group. Unconfirmed groups remain unchanged. Confirmation for one group does not authorize another. Done when: every repair group has a confirmed or unconfirmed decision recorded.
8. Apply only confirmed repairs within $MEMORY_DIR. Preserve unrelated content. If an applied repair fails partway, stop further mutation and restore every file touched by that group from the snapshot before reporting the failure. Done when: every confirmed repair is applied or the failed group is restored and the run stops.
9. Re-run the same audit against the same resolved inputs. Success requires zero critical findings. Report all residual warning and informational findings; do not claim success when the audit fails, evidence is unavailable, or critical findings remain. Done when: the fresh audit completes and its critical-finding count is known.

Failure and recovery

• Invalid or missing path: stop before snapshot or mutation and return blocked with the resolver diagnostic.
• Snapshot failure: stop without mutation and return blocked with the failed snapshot target.
• Audit failure or malformed report: retain any valid partial report, make no repairs, and return blocked with the diagnostic; never infer omitted findings.
• Missing staleness evidence: complete structural checks, mark session-based staleness unavailable, and return blocked rather than treating absence of evidence as freshness.
• Confirmation absent or ambiguous: leave that repair group unchanged and report it as unconfirmed.
• Partial repair failure: stop, restore that group's touched files from the recorded snapshot, and report the attempted changes and restoration result. If restoration fails, return blocked and identify every potentially changed file.
• Critical findings after re-audit: return non-converged with the remaining critical findings and residual warnings or information; do not widen scope or invent a fix.

Output

Return the snapshot path, resolved audit scope, severity-grouped JSON findings, per-group previews and confirmation decisions, applied and restored file lists, fresh re-audit result, residual warnings and information, and exactly one terminal classification: complete, blocked, or non-converged. complete is valid only when the fresh audit contains zero critical findings.