claude-reflect
Self-learning system for Claude Code that captures corrections and updates CLAUDE.md automatically
Installation
Open Claude Code and run this command:
/plugin install claude-reflect@claude-code-plugins-plus
Use --global to install for all projects, or --project for current project only.
What It Does
When you correct Claude Code during a session ("no, use gpt-5.1 not gpt-5", "use database for caching"), these corrections are captured and can be added to your CLAUDE.md files so Claude remembers them in future sessions.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ You correct │ ──► │ Hook captures │ ──► │ /reflect adds │
│ Claude Code │ │ to queue │ │ to CLAUDE.md │
└─────────────────┘ └─────────────────┘ └─────────────────┘
(automatic) (automatic) (manual review)
Features
Historical Scan
First time using claude-reflect? Run:
/reflect --scan-history
This scans all your past sessions for corrections you made, so you don't lose learnings from before installation.
Smart Filtering
Claude filters out:
- Questions (not corrections)
- One-time task instructions
- Context-specific requests
- Vague/non-actionable feedback
Only reusable learnings are kept.
Duplicate Detection
Before adding a learning, existing CLAUDE.md content is checked. If similar content exists, you can:
- Merge with existing entry
- Replace the old entry
- Skip the duplicate
Semantic Deduplication
Over time, CLAUDE.md can accumulate similar entries. Run /reflect --dedupe to:
- Find semantically similar entries (even with different wording)
- Propose consolidated versions
- Clean up redundant learnings
Example:
Before:
- Use gpt-5.1 for complex tasks
- Prefer gpt-5.1 for reasoning
- gpt-5.1 is better for hard problems
After:
- Use gpt-5.1 for complex reasoning tasks
Skills (1)
Execute self-learning system that captures corrections during sessions and syncs them to CLAUDE.
How It Works
Two-Stage Process
Stage 1: Capture (Automatic)
Hooks run automatically to detect and queue corrections:
| Hook | Trigger | Purpose |
|---|---|---|
capture-learning.sh |
Every prompt | Detects correction patterns and queues them |
check-learnings.sh |
Before compaction | Blocks compaction if queue has items |
post-commit-reminder.sh |
After git commit | Reminds to run /reflect after completing work |
Stage 2: Process (Manual)
Run /reflect to review and apply queued learnings to CLAUDE.md.
Pattern Detection
The capture hook detects corrections AND positive feedback:
Corrections (what went wrong):
"no, use X"/"don't use Y""actually..."/"I meant...""use X not Y"/"that's wrong"
Positive patterns (what works):
"Perfect!"/"Exactly right""That's what I wanted"/"Great approach""Keep doing this"/"Nailed it"
Explicit markers:
"remember:"— highest confidence
Each captured learning has a confidence score (0.60-0.95) based on pattern strength. Higher confidence = more likely to be a real learning.
Human Review
When you run /reflect, Claude presents a summary table:
════════════════════════════════════════════════════════════
LEARNINGS SUMMARY — 5 items found
════════════════════════════════════════════════════════════
┌────┬─────────────────────────────────────────┬──────────┬────────┐
│ # │ Learning │ Scope │ Status │
├────┼─────────────────────────────────────────┼──────────┼────────┤
│ 1 │ Use gpt-5.1 for reasoning tasks │ global │ ✓ new │
│ 2 │ Database for persistent storage │ project │ ✓ new │
└────┴─────────────────────────────────────────┴──────────┴────────┘
You choose:
- Apply all - Accept recommended changes
- Select which - Pick specific learnings
- Review details - See full context before deciding
Multi-Target Sync
Approved learnings are synced to:
~/.claude/CLAUDE.md(global - applies to all projects)./CLAUDE.md(project-specific)AGENTS.md(if exists - works with Codex, Cursor, Aider, Jules, Zed, Factory)
Run /reflect --targets to see which files will be updated.