Pruning & Compaction — When Forgetting Is a Feature

Introduction

Forgetting is an engineering action, not a failure. Every piece of context that you remove from CLAUDE.md, every memory you archive in Semantic Memory Layer, every lessons.md entry that gets promoted to CLAUDE.md Tier 1 (and the original entry deleted) — these are intentional engineering decisions that improve the precision of the system.

The alternative — never pruning, never compacting — produces a system that grows without bound until it collapses under its own weight. Knox's MEMORY.md carries a warning when it approaches 200 lines. That warning is a forcing function for a compaction run. When you see it, the pruning decision tree is the tool.

The Four-Question Pruning Decision Tree

Four questions, applied to every rule in CLAUDE.md or entry in lessons.md:

Q1: Is this rule still enforced by a CI gate or code-level constraint?

If a rule is enforced by CI (the test must pass, the coverage floor is checked, the branch protection is active), it is self-enforcing. The CLAUDE.md entry may still be useful as documentation, but its operational importance is lower — the system will catch violations without the agent reading the rule.

If yes → KEEP (ideally as a terse one-liner). KEEP is correct because CI catches the violation only after the agent has already done the wrong work — the in-context rule prevents the wasted cycle and the failed CI run in the first place, which CI alone cannot do. The rule is doing real work even when it is never explicitly read. (Because the operational stakes are lower, this is also the prime candidate for trimming to a single line rather than a full paragraph.)

Q2: Has this fact been superseded or reversed by a later decision?

This is the rot detector. A fact that has been superseded is not stale — it is wrong. Keeping it creates the contradiction pattern from the previous lesson.

If yes → REMOVE. Stop the tree. Delete the rule and replace it with the accurate current state.

Q3: Is this triggered by a task type (not needed every session)?

Design tokens, API specs, setup guides, per-page design overrides — all of these are only needed when the relevant task type arises.

If yes → MOVE to a separate sub-doc (read by the agent when the task fires) or Semantic Memory Layer. Load on demand via the progressive disclosure pattern.

Q4: Is this a Tier 1 non-negotiable or safety gate?

Non-negotiables (never commit to main, 90% coverage floor, Supabase auth only) belong in CLAUDE.md Tier 1. Everything else that survived Q1–Q3 belongs in lessons.md with a date, not in CLAUDE.md.

The Memory Lifecycle: Four States

Every memory in the system moves through states:

Active: The memory is fresh (< 30 days old or explicitly timeless), still referenced, and no contradictory fact exists. It belongs in MEMORY.md index / active Semantic Memory Layer namespace.

Review: Age or relevance is in question (30–90 days, not recently referenced, or contradicted). Run /learn or /context-budget to audit. Decide: active or archive.

Archive: The memory is resolved (incident fixed, project retired, decision superseded) and relevant less than once per quarter. Move to topic file with status: archived frontmatter; remove from active index. The content is preserved but no longer loads in every session.

Forget: The memory is wrong, superseded, or never referenced in 3+ months. memory_forget(memory_id) in Semantic Memory Layer (soft-delete — marks as deleted, content preserved in audit trail). Remove topic file. Update index.

The key principle: forgetting is a write operation, not an admission of failure. memory_forget() requires a reason — document it. "Superseded by launchd migration 2026-05-24" is a valid reason. The audit trail of forgotten memories is itself valuable context about system evolution.

Session-Level Compaction

Session compaction is distinct from memory pruning — it addresses the reread tax (the “The Context Window as a Budget” lesson), not the CLAUDE.md bloat (the “Tiered Importance” lesson).

The trigger: session past turn 15–20 with verbose tool output. Not "Claude warned me the window is full" — by then, you're already in degraded mode.

The process:

1. Synthesize progress: What was built? What decisions were made? What files were modified? What remains?
2. Document key context: File paths that matter, current test state, error signatures if debugging
3. Start fresh: New session with the synthesis as initial context
4. Resume: The new session has full window headroom and the critical context, without carrying the verbose history

The /compact command in Claude Code triggers built-in compaction. For manual compaction, a structured summary prompt works well:

Summarize this session for context carry-forward:
- What was accomplished (with specific file paths)
- Decisions made and why
- Current test state (pass/fail counts)
- What remains to be done (ordered by priority)
- Any gotchas or warnings discovered

Contradiction Detection as a Pruning Trigger

Contradictions do not require waiting for a scheduled pruning run — they should trigger immediate resolution when detected.

Detection signals:

• Two rules in the same file that describe incompatible behaviors for the same scenario
• A CLAUDE.md rule that conflicts with a MEMORY.md note
• A lessons.md entry that contradicts a CLAUDE.md rule (the lesson evolved but CLAUDE.md wasn't updated)
• An Semantic Memory Layer memory that contradicts a more recent Semantic Memory Layer memory on the same topic

Resolution protocol:

1. Identify the more recent or more authoritative source
2. Update the authoritative source to be explicit: "This supersedes [previous rule]"
3. Remove or archive the superseded rule
4. If the contradiction was in CLAUDE.md, add a dated note: "Rule updated 2026-05-31 — old rule removed"

The goal: no two rules in the active context should describe incompatible behaviors. When in doubt, the more specific (inner hierarchy) and more recent rule wins.

Summary

• The four-question decision tree: CI-enforced → Keep; Superseded → Remove; Task-triggered → Move to @import/Semantic Memory Layer; Tier 1 → Keep
• Four memory states: Active → Review → Archive → Forget
• Forgetting is a write operation — memory_forget() with a reason, not a silent deletion
• Session compaction: proactive at turn 15–20 with verbose output, not reactive after warning
• Contradictions are pruning triggers — resolve immediately when detected, don't wait for scheduled pruning

What's Next

The next lesson applies everything from this track to the specific challenge of scoping context for specialized agents — why a trading agent contaminated with design rules produces worse trading analysis, and how to build task-scoped context that makes each agent precisely better.