Agent Memory Cleanup#

This skill should be lightweight and low-noise. Do not require the user to know internal implementation names unless they ask. The user should still receive clear memory-state prompts, such as "memory appears too large, stale, duplicated, conflicted, or unsafe," when action is useful.

Default Flow#

1. Detect memory pressure or pollution.
2. If Python/file access is available, run a cheap summary check first:

bash

python scripts/audit_memory.py memory.md --summary-json

1. If quality.intervention is no_intervention_needed, do not interrupt the user.
2. If intervention is needed, say briefly that memory appears too large, stale, duplicated, conflicted, or unsafe, and ask whether to review cleanup recommendations. Avoid implementation labels like the skill name unless the user asks.
3. After the user agrees, run:

bash

python scripts/audit_memory.py memory.md --mode propose-patch --include-diff

1. Apply only after a second explicit approval, unless unattended cleanup was already authorized:

bash

python scripts/audit_memory.py memory.md --mode apply-approved

The apply mode must create timestamped backups before writing.

Trigger Points#

Use this flow for:

• Memory write/update rejected, full, over budget, truncated, or too long.
• Short memory with secrets, task-state residue, duplicated facts, or conflicting preferences.
• User says a remembered fact is wrong, outdated, project-only, or should not be remembered.
• Before saving a new global memory candidate:

bash

python scripts/audit_memory.py --candidate "candidate memory text" --summary-json

If candidate lint returns do_not_write_candidate_to_global_memory, do not store it globally. Offer to skip it or keep it as project/task notes.

Intervention Values#

• prompt_cleanup_now_secret_detected: recommend cleanup immediately; never echo raw secrets.
• prompt_user_review_conflicting_memory: ask the user to resolve conflicting durable preferences.
• do_not_write_candidate_to_global_memory: block global memory write.
• prompt_cleanup_recommended: offer cleanup recommendations.
• prompt_audit_recommended: mention memory quality may be degrading and ask whether to review.
• no_intervention_needed: stay silent.

Load Extra Context Only When Needed#

Do not read references by default. Load them only for the matching need:

• references/default-rules.json: deterministic thresholds and regex rules.
• references/classification-rubric.md: manual fallback if Python cannot run.
• references/agent-paths.md: path discovery when memory files are unclear.
• references/mcp-version.md: MCP wrapper design.

Safety#

• Keep only stable global preferences and durable cross-task context.
• Remove or redact secrets, stale task state, branch/PR/debug notes, and one-off plans.
• Do not rewrite clean memory just for style.
• Do not broadly scan the user home directory without explicit request.
• Back up every edited memory file.