Memories Manager

Audit every existing `memories/*-gotchas.md` file across the monorepo: merge duplicates, promote workspace rules to the root, prune what no longer applies, and normalise formatting. Preserves wording literally and never beautifies technical detail. Use when the user says "memories manager", "manage memories", "audit memories", "merge memories", "prune memories", or when the knowledge base has drifted, duplicated or gone stale. For filing NEW gotchas, use `memories` instead.

How to use

Use this when the knowledge base has drifted, duplicated, or gone stale.

Prompt

Memories Manager

Semantic audit of ALL existing memories/*-gotchas.md files, to merge, promote and prune what is already filed.

The on-disk contract lives in @.agents/skills/cebreus-memories/GOTCHA-FORMAT.md. Read it before rewriting anything.

CRITICAL CONSTRAINTS (FAIL-CLOSED)

  1. Literal Promotion: When moving a rule from a workspace to the monorepo root (/memories/), wording MUST be preserved 100% literally.
  2. No Beautification: When merging duplicates, do NOT simplify technical details. Preserve exact error codes, versions and paths. When both duplicates carry a **Date Discovered:**, keep the oldest; when only one carries it, keep that one; when neither does, do NOT invent a date.
  3. Prune On Evidence: A rule is Obsolete only when the current codebase proves it so. Verify against the code before deleting; a rule you merely doubt stays.

1. Audit

Run node .agents/skills/cebreus-memories/gotchas.mjs audit first. It walks the whole repo — root and workspaces both hold memory files — and reports, without changing anything:

  • every *-gotchas.md file and its entry count,
  • entries sharing an identical title or identical rule text once punctuation, casing and backticks are ignored,
  • empty files,
  • files not referenced from the AGENTS.md of their own scope.

Those four are mechanical, so take them from the report rather than re-deriving them by reading every file. What the report cannot judge is semantic equivalence between differently worded rules, and whether a rule still holds; that is your work.

Then classify every entry into exactly one of:

  • (A) Obsolete — no longer applicable given the current codebase state, proven by reading it.
  • (B) Duplicate — semantically equivalent to, or a conflicting variant of, a rule found elsewhere.
  • (C) Promotion Candidate — workspace-scoped rule whose applicability spans the entire monorepo.
  • (D) Keep — everything else.

Record the rationale for each non-Keep classification before changing a file.

2. Merge & Promote

  • Merge: collapse Duplicate entries into a single canonical record. Where wording conflicts, retain the most technically precise variant and annotate the discarded ones in a <!-- merged-from --> comment.
  • Promote: move Promotion Candidates verbatim to root /memories/, then remove the original from the workspace file so the two cannot diverge.

3. Reconcile

  • Every remaining memory file is referenced from the AGENTS.md of its own scope, using the index line from GOTCHA-FORMAT.md.
  • Delete memory files left empty, and their index lines with them.
  • No entry appears both in a workspace file and in root /memories/.

Re-run node .agents/skills/cebreus-memories/gotchas.mjs audit afterwards. Empty files and unindexed files must both report zero; a non-zero count means a reconcile step was missed.

4. Sort & Report

Run node .agents/skills/cebreus-memories/gotchas.mjs sort. It normalises every heading to the ## 🚨 form and reorders blocks: dated oldest-first, undated alphabetically. Verify the file count it prints matches the files you touched.

Output a summary table with the columns: File Path | Action (Merged/Promoted/Deleted/Pruned) | Rule Title | Reason.