harden-memories

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

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:

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
<key>	one line	redundancy / staleness / drift / conflicting	remove / migrate→<target> / keep	one line

4. Present the action plan (do not execute)

For the user to review and run. Group by disposition:

• migrate→<target> — 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/<project-slug>/memory/MEMORY.md, where <project-slug> 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":

  bd forget <key>   # after the fact is durably captured at <target>
  

  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:

  bd forget <key>   # 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.