Feature: Self-improvement loop — auto-update MEMORY.md from session performance data (facets)

Problem

Claude Code already collects session performance data via facets (~/.claude/usage-data/facets/) — including friction patterns, satisfaction scores, outcomes, and success patterns. It also has persistent memory (MEMORY.md). But there's no native feedback loop connecting them.

Users who would benefit most from memory updates (frequent users with recurring friction) are exactly the ones too busy to manually curate their MEMORY.md. The result: Claude repeats the same mistakes across sessions because it has no memory of past failures.

Evidence from Real Usage

Over 144 sessions across 5 weeks, I analyzed all 52 facets and found:

• 42% friction rate — nearly half of sessions had friction events
• 41% of friction was "wrong approach" — Claude started with the wrong hypothesis, tool, or strategy
• Many were the same wrong approach repeated because Claude had no memory of past failures
• Top friction types: wrong_approach (26), misunderstood_request (15), buggy_code (11)
• Avg satisfaction: 3.4/5, outcome success rate: 73%

After building a prototype self-improvement system that reads facets and updates MEMORY.md, the analysis identified 6 actionable memory updates and 3 CLAUDE.md suggestions — all specific, evidence-based lessons that would prevent recurring friction.

Proposed Solution

A built-in self-improvement mechanism that connects session facets to persistent memory:

Option A: Post-session hook (lightweight)

After each session, if friction was detected:

• Flag the friction pattern
• Propose a MEMORY.md addition (e.g., "Always query table schema before writing SQL — this caused wrong_approach friction in 5 sessions")
• User confirms or dismisses

Option B: /self-improve command (periodic)

A built-in command that:

1. Reads recent facets from ~/.claude/usage-data/facets/
2. Aggregates friction patterns, success patterns, and satisfaction trends
3. Compares against current MEMORY.md to avoid duplicates
4. Proposes specific, actionable memory additions
5. Tracks friction rate over time to measure improvement

Option C: Automatic anti-pattern detection

If Claude makes the same mistake type 3+ times (detectable from facets), automatically suggest a memory entry to prevent it. Example: "You've had wrong_approach friction in 12/52 sessions related to SQL queries. Suggested MEMORY.md entry: 'Always run DESCRIBE TABLE before writing complex SQL against unfamiliar tables.'"

What I Built (Prototype)

I built this as a ~430-line shell script that orchestrates two headless Claude calls:

Stage 1 (bash): Collect facets + current MEMORY.md → payload JSON
Stage 2 (claude -p): Analyze friction patterns → structured JSON with memory_updates
Stage 3 (claude -p): Apply memory_updates to MEMORY.md + topic files

Key features:

• Rolling backups before every write
• 180-line MEMORY.md budget (offloads detail to topic files)
• CLAUDE.md suggestions logged for manual review (never auto-modified)
• Idempotent (tracks processed facets count)
• Weekly automation via LaunchAgent
• Cost: ~$0.80/week

It works. The bootstrap run identified insights I wouldn't have manually extracted from 52 facets — like the correlation between "premature commits" and dissatisfaction in visual/UI work, or that dbt incremental model sessions had 50% friction rate vs 10% for JIRA/Confluence workflows.

Why This Should Be Native

1. The data already exists — facets are collected, they just aren't fed back
2. Manual curation doesn't scale — power users accumulate hundreds of sessions
3. Self-awareness reduces friction — knowing "I tend to diagnose before querying" is the most impactful kind of memory
4. It could integrate with /insights — show whether memory updates are actually reducing friction over time
5. Complements #23727 (memory optimization) — that issue is about compressing memory; this is about generating better memory content

Additional Context

• Prototype code available if helpful for reference
• The analysis prompt and memory update prompt could be standardized as part of Claude Code's built-in prompts
• Friction trend tracking in /insights would close the feedback loop visually