--- name: harden-memories description: "Audit the `bd remember` store and recommend which entries to prune, so each one earns its per-session `bd prime` injection cost. Read-only: it proposes a triage table plus the exact `bd forget` / migration commands; you run them. Use when `bd remember` entries have accumulated, feel stale, redundant, or conflicting, or when session-startup token cost from injected memories is high. Trigger phrases: 'harden memories', 'audit bd remember', 'prune bd remember', 'bd remember bloat', 'bd remember audit', 'trim bd remember', or '/harden-memories'. NOT for Claude Code auto-memory (`/dream` / Auto Dream files), NOT for Basic Memory graph hygiene (use vp-knowledge's memory-defrag / memory-lifecycle skills), and NOT for beads issues or the backlog (use /backlog-groomer)." user-invocable: true paths: - ".beads/**" allowed-tools: - Bash - Read - mcp__basic-memory__search_notes - mcp__basic-memory__read_note --- # Harden Memories Audit the project's `bd remember` entries and recommend which to prune down to the few that genuinely earn their cost. `bd prime` injects **every** `bd remember` entry in full at session start (they are persisted in the beads Dolt database), so entries accumulate as a silent, scaling token tax — conventions drift, skills ship, and facts graduate to CLAUDE.md / the auto-memory `MEMORY.md` / Basic Memory, but nothing automates the cleanup until a manual pass. Periodic audits (≈ every 4 sprints) reliably recover \~40% of that token budget. **This skill is READ-ONLY by design.** It audits and *proposes* — it never edits a durable file, never writes to Basic Memory, and never runs `bd forget` itself. For each entry it presents a recommendation plus the exact command(s) for **you** to review and run. This deliberately keeps the irreversible step (`bd forget`, which destroys the only copy of a fact) and the migration write under your control — no automated "verify-then-delete" can be trusted to gate an irreversible delete (a Basic Memory write can fail `schema_validate` asynchronously; an `Edit` can land in the wrong file; an append can hit the wrong section). Proposing keeps you in the loop for both halves. **Scope — strictly the `bd remember` store.** NOT Anthropic's Auto Dream / `/dream` (which prunes Claude Code auto-memory files, a different store), and NOT Basic Memory graph hygiene (defer that to vp-knowledge's graph-maintenance skills). It audits `bd remember` and nothing else. ## Beads availability Beads is available iff a `.beads/` directory exists **and** `command -v bd` succeeds; this component is **Tier B** per CLAUDE.md `### Beads-availability convention`. The `bd remember` store only exists when beads does — with no beads there is nothing to audit. Stop cleanly, naming the missing predicate (no `.beads/` directory, or `bd` not on `PATH`). There is no beadless equivalent to redirect to. ## Workflow ### 1. Read the current memories ```bash bd memories --json ``` Returns a JSON object keyed by memory key. **Keep only entries whose value is a string** — memory entries are always strings; scalar metadata (e.g. `schema_version`) are numbers or booleans: ```bash bd memories --json | jq 'to_entries | map(select(.value | type == "string")) | from_entries' ``` The surviving entries are the audit set. If there are none, report that there is nothing to prune and stop. ### 2. Classify each entry For every entry, run the canonical three-question checklist (from Basic Memory `engineering/agents/three-memory-systems-taxonomy-and-graduation`): 1. **Already in Basic Memory or the auto-memory `MEMORY.md` / CLAUDE.md? → recommend remove.** 2. **Describes stable project-architecture state? → recommend migrate** (to CLAUDE.md for a project working-instruction, the auto-memory `MEMORY.md` for project state, or Basic Memory for generalizable engineering knowledge), then remove. 3. **Only helps recover from context loss mid-task? → recommend keep.** To answer question 1, cross-reference each entry against the live sources: - `Read` CLAUDE.md (small enough to read whole) and scan for the entry's key facts. (The auto-memory `MEMORY.md` lives outside the repo at the Claude Code project memory path — name it as a target in proposals, but you need not read it here.) - Call `mcp__basic-memory__search_notes` with 2-4 keywords from the entry. **For any match, `mcp__basic-memory__read_note` and confirm the specific fact is actually present** before recommending `remove` — a keyword co-occurrence is NOT confirmation of capture. If you cannot confirm the fact is captured, do not recommend `remove`. Tag each entry with the bloat category that justifies its disposition: **redundancy** (duplicates a live source), **staleness** (describes a state that no longer holds — e.g. an entry that says "STALE" or names a shipped/abandoned plan), **granularity drift** (early-project specifics that became standard practice), or **conflicting** (contradicts another entry or a live source). ### 3. Present the triage table | Key | Summary | Category | Recommendation | Rationale | | ------- | -------- | -------------------------------------------- | ---------------------------------- | --------- | | `` | one line | redundancy / staleness / drift / conflicting | remove / migrate→`` / keep | one line | ### 4. Present the action plan (do not execute) For the user to review and run. Group by disposition: - **migrate→``** — show the **drafted text** to add and the **explicit target** (a named CLAUDE.md section; the auto-memory `MEMORY.md`; or a Basic Memory note path + section). For the auto-memory `MEMORY.md`, give its real path — `~/.claude/projects//memory/MEMORY.md`, where `` is the project's absolute path with `/` → `-` — and **ask the user to confirm it** rather than emitting a bare `MEMORY.md` (which would resolve to a non-existent repo-root file). Then the `bd forget` command, clearly marked "run only after you have written and verified the migration": ```bash bd forget # after the fact is durably captured at ``` For a Basic Memory target, note the gotcha: use `edit_note` with `find_replace` / `insert_before_section`, never `append` with a `section` (it appends to end-of-file, not end-of-section). - **remove** — show the evidence that the fact is already captured (which source, confirmed in step 2), then the command: ```bash bd forget # already captured elsewhere or no longer true ``` Note for the user: `bd forget` prints `No memory with key "..."` and exits 1 if the key is already gone (benign); any other non-zero exit is a real failure (DB locked/missing) worth investigating — verify with `bd memories`, not the exit code. - **keep** — no command; the entry earns its injection. ### 5. Report Summarize: recommended-remove count, recommended-migrate count (with each target), keep count, and the approximate per-session token reduction if the user applies the removals (entries removed × their injected length). Note that the audit cadence is ≈ every 4 sprints. ## Guidelines - **Read-only — propose, never execute.** This skill never edits a file, writes to Basic Memory, or runs `bd forget`. It presents recommendations and exact commands; the user performs the irreversible write and delete steps, keeping both under explicit human control. - **Graduation before deletion (in the proposed order).** A fact worth keeping must be migrated to its durable home and confirmed there **before** its `bd forget` is run. The action plan always presents the migration first and marks the `bd forget` as "run only after the migration is verified." - **Conservative pruning.** When unsure whether an entry still earns its cost, recommend keep and flag it for the next audit rather than recommending removal. Signal preservation beats aggressive trimming. - **Confirm capture before recommending remove.** A keyword search hit is not proof a fact is captured — read the matched note/section and verify the specific fact is present (step 2). A false "already captured" recommendation, if acted on, is data loss. - **Keep the survivors short.** `bd remember` entries are injected every session; a kept entry should be a single-sentence recovery trigger. If a kept entry is long, propose tightening it (the user re-runs `bd remember` with `--key` to upsert) as part of the audit. - **Scope boundary.** This skill audits only `bd remember`. Basic Memory graph hygiene (orphans, schema, duplicate notes) belongs to vp-knowledge's graph-maintenance skills; do not perform it here.