[FEATURE] Memory system governance for long-running users

Problem

After 30+ days of daily Claude Code usage with auto-memory enabled, the memory system accumulates structural problems that degrade session quality:

1. MEMORY.md hits the ~200-line display threshold. New information pushes older entries out of initial context. The index becomes the bottleneck.

1. Corrections accumulate without expiry. Every time Claude does something wrong, users add a correction. After weeks, corrections stack up — some contradicting each other, some applying to situations that no longer exist. There's no mechanism to ask "does this correction still apply?"

1. Self-referential memories go unchallenged. Memory files that describe the user's preferences or project conventions become load-bearing assumptions. If they were wrong when written (or became wrong over time), everything downstream is wrong. There's no adversarial flag.

1. Priority saturation. When all memory content loads at the same high priority, Claude can't distinguish between "always relevant" rules and "only relevant when working on X" knowledge. Everything competes for attention equally.

1. No audit mechanism. There's no built-in way to review whether the memory system as a whole is healthy, has dead weight, or has drifted from reality.

Proposed Patterns

These are patterns discovered through heavy daily usage that address the above problems. Some could be implemented as features; others are user-side conventions that could be documented as best practices.

1. Feedback expiry metadata

Add optional frontmatter fields to memory files:

---
review_by: After 3 months — reassess whether this correction still applies
last_challenged: 2026-03-15
---

• review_by: When should this memory be re-evaluated? Can be a date, an event ("after migration complete"), or "Durable" for permanent rules.
• last_challenged: When was this memory last verified against reality?

Why: Corrections are point-in-time observations. Without expiry, they become dogma — followed correctly but without the ability to re-evaluate whether the original error still applies. Over time, the correction stack gets deep enough that the original reasoning is buried.

Implementation option: Claude Code could surface a gentle reminder when loading a memory file whose review_by condition has been met — for example, injecting a brief note into context when the file is read.

2. Confidence ratings on memories

---
confidence: medium — useful lens but not proven
last_challenged: 2026-03-15
---

• High: Factual, verified, or well-tested
• Medium: Useful framework but not conclusively proven
• Low: Hypothesis or single-data-point observation

Why: Some memories are facts ("use pytest, not unittest"). Others are interpretations ("the user prefers X approach because Y"). When Claude treats interpretations as facts, it reinforces potentially wrong assumptions. A confidence rating lets Claude weight memories appropriately and flag low-confidence memories for re-examination.

3. Three-layer memory architecture

Separate what Claude knows from how Claude behaves:

| Layer | Location | Purpose | Loading |
|-------|----------|---------|---------|
| Index | MEMORY.md | Pointers to topic files | Always (truncated at ~200 lines) |
| Rules | ~/.claude/rules/*.md | Behavioral instructions | Always, high priority |
| Knowledge | memory/*.md topic files | Domain details | On-demand when triggered |

Why: MEMORY.md tries to be both an index AND a knowledge base. Splitting behavioral instructions into ~/.claude/rules/ (which already exists and loads at high priority) keeps the index lean and ensures behavioral rules always have attention priority. Topic files load only when relevant, preventing priority saturation.

Practical result: MEMORY.md stays under 120 lines as a pure pointer file. Rules carry the "how to behave" instructions. Topic files carry the "what I know" details. Each layer has a clear purpose and appropriate loading behavior.

4. Periodic memory audit

A systematic review of all memory files, checking:

• Line count per file (flag files over 100 lines for compression)
• Dead weight (files not loaded in 3+ sessions whose content exists elsewhere)
• Correction stack depth (are corrections layered on corrections without re-evaluating the original?)
• Coverage gaps (areas the user works in frequently but has no memory for)

Why: Memory systems degrade silently. Individual sessions feel fine, but the accumulated drift over weeks creates a gap between what Claude "knows" and what's actually true. A periodic audit catches structural problems that incremental corrections miss.

Implementation option: A /memory-audit command that reads all memory files and produces a health report: file count, total lines, largest files, files with expired review_by dates, and files not referenced in MEMORY.md.

5. Structural changelog

An append-only log of why memory changed, not just what:

## 2026-03-15 — Memory System Overhaul

### Trigger
MEMORY.md hit 200-line cap. Feedback files had no expiry mechanism.

### Changes
- MEMORY.md: 201→98 lines (extracted 3 topic files)
- Added review_by to 6 feedback files
- Deleted 1 dormant file (absorbed into backlog)

### Metrics
| Before | After |
|--------|-------|
| 201 lines | 98 lines |
| 0 files with expiry | 6 files |

Why: Git tracks what changed in code. But memory files aren't always in a git repo, and even when they are, the commit message doesn't capture the reasoning behind structural memory decisions. The changelog enables re-evaluation: "we reorganized because of X — does X still hold?"

Related (separate from memory governance)

Blindspot check as output style: For users making high-stakes decisions, a configurable response protocol that appends a self-critique section ("what did we miss, where was reasoning weak") to substantive responses. This is a response formatting feature rather than a memory feature, so it may warrant its own issue — but it emerged from the same scaling experience.

Context

These patterns emerged from using Claude Code daily for 30+ days across multiple domains (infrastructure management, research, system design). The memory system works well for the first few weeks, then hits scaling problems that aren't obvious until the accumulated memory is large enough to create priority saturation and silent drift.

The existing ~/.claude/rules/ directory and auto-memory system are excellent foundations. These proposals build on that foundation to address the problems that emerge at scale.

Summary

| Pattern | Type | Effort |
|---------|------|--------|
| Feedback expiry (review_by) | Feature (frontmatter parsing) | Low |
| Confidence ratings | Feature or convention | Low |
| Three-layer architecture | Best practice documentation | None (uses existing features) |
| Periodic memory audit | Feature (/memory-audit command) | Medium |
| Structural changelog | Best practice documentation | None |

Additional detail available on any of these patterns if useful for scoping.