The Problem
Why Manual Memory Management Fails
Repetitive Corrections
Every session, you tell Claude the same things: "use gpt-5.1 not gpt-5", "we use Poetry here", "always add type hints". These corrections vanish when the session ends.
Manual CLAUDE.md Updates
You could manually add preferences to CLAUDE.md, but who remembers to do that mid-flow? By the time you finish coding, you've forgotten half the corrections you made.
Context Lost Across Projects
Global preferences (like model versions) need to be in your global CLAUDE.md. Project-specific conventions need to be local. Keeping them organized is tedious.
How It Works
Two-Stage Learning Pipeline
"Actually, we prefer Ruff"
Stage 1: Capture (Automatic)
Hooks run on every prompt, detecting correction patterns like "no, use X", "don't use Y",
"actually...", and "that's wrong". Positive feedback like "Perfect!" is captured too. Explicit
remember: markers get highest confidence.
Stage 2: Process (Manual)
Run /reflect to review queued learnings. An AI-powered semantic filter validates
each one, removing false positives. You choose which to apply — to global CLAUDE.md, project
CLAUDE.md, or AGENTS.md.
# During your coding session... You: "no, use gpt-5.1 not gpt-5 for reasoning tasks" You: "remember: always run tests before committing" You: "Perfect! That's exactly how we handle auth here" # Later, run /reflect... ════════════════════════════════════════════════════════════ LEARNINGS SUMMARY — 3 items found ════════════════════════════════════════════════════════════ ┌────┬─────────────────────────────────────────┬──────────┬────────┐ │ # │ Learning │ Scope │ Status │ ├────┼─────────────────────────────────────────┼──────────┼────────┤ │ 1 │ Use gpt-5.1 for reasoning tasks │ global │ ✓ new │ │ 2 │ Always run tests before committing │ project │ ✓ new │ │ 3 │ Auth handling pattern (positive) │ project │ ✓ new │ └────┴─────────────────────────────────────────┴──────────┴────────┘
Detection Methods
Hybrid Pattern Recognition
Regex Patterns (Real-time)
Fast pattern matching during sessions detects corrections ("no, use X", "don't use Y"),
positive feedback ("Perfect!", "Exactly right"), and explicit markers (remember:).
Each pattern has a confidence score from 0.60-0.95.
Semantic AI Validation
When you run /reflect, an AI-powered semantic filter validates each learning.
Multi-language support understands corrections in any language. Extracts concise, actionable
statements from natural language.
The semantic filter understands corrections beyond English patterns. A Spanish correction like "no, usa Python" is correctly detected even though it doesn't match English regex patterns. The final confidence score is the higher of regex and semantic analysis.
Commands Reference
Full Command Suite
| Command | Description |
|---|---|
| /reflect | Process queued learnings with human review |
| /reflect --scan-history | Scan ALL past sessions for missed learnings |
| /reflect --dry-run | Preview changes without applying them |
| /reflect --targets | Show detected config files (CLAUDE.md, AGENTS.md) |
| /reflect --review | Show queue with confidence scores and decay status |
| /reflect --dedupe | Find and consolidate similar entries in CLAUDE.md |
| /skip-reflect | Discard all queued learnings |
| /view-queue | View pending learnings without processing |
Multi-Target Sync
Where Learnings Go
~/.claude/CLAUDE.md
Global learnings that apply everywhere. Model preferences, general coding style, universal conventions. Shared across all your projects automatically.
./CLAUDE.md
Project-specific learnings. Framework conventions, local patterns, team preferences. Lives with your code and is version-controlled.
AGENTS.md
Cross-tool compatibility. Works with Codex, Cursor, Aider, Jules, Zed, and Factory. Learnings follow you across your entire AI-assisted development workflow.
# See which files will be updated /reflect --targets Detected configuration files: Global: ~/.claude/CLAUDE.md Project: ./CLAUDE.md Agents: ./AGENTS.md ✓
Smart Features
Beyond Basic Capture
Historical Scan
First time using claude-reflect? Run /reflect --scan-history to
scan all past sessions for corrections. Recover learnings from before installation.
Smart Filtering
Questions, one-time task instructions, and vague feedback are automatically filtered out. Only reusable, actionable learnings are kept.
Duplicate Detection
Before adding a learning, existing CLAUDE.md content is checked. If similar content exists, you can merge, replace, or skip.
Semantic Deduplication
Over time, CLAUDE.md accumulates similar entries. Run /reflect
--dedupe to consolidate "Use gpt-5.1 for complex tasks" and "Prefer gpt-5.1 for
reasoning" into one entry.
Installation
Get Started in Seconds
# Add the marketplace claude plugin marketplace add bayramannakov/claude-reflect # Install the plugin claude plugin install claude-reflect@claude-reflect-marketplace # IMPORTANT: Restart Claude Code to activate # Then hooks auto-configure and commands are ready
macOS
Fully supported. Works out of the box with Claude Code.
Linux
Fully supported. Requires Python 3.6+ (included on most systems).
Windows
Fully supported with native Python. No WSL required.
Stop repeating yourself. Install claude-reflect and let your corrections compound into a personalized AI assistant that learns your preferences, your conventions, and your way of working.
View on GitHub →