Technical Briefing: claude-reflect

The Problem

Claude Code sessions are ephemeral — corrections and discovered patterns vanish when a session ends. Without persistent memory, each new session starts fresh, repeating the same corrections and missing opportunities to codify reusable workflow patterns from prior work.

What This Does

claude-reflect is a self-learning system that captures corrections, positive feedback, and preferences during Claude Code sessions, then syncs them to CLAUDE.md and AGENTS.md for persistent context. The repo contains 41 files (18 Python, 10 Markdown, 5 Shell) organized under scripts/, tests/, commands/, and hooks/. Key mechanisms include:

  • scripts/capture_learning.py — entry point that processes queued learnings (reaches 28 functions from 1 call site)
  • scripts/lib/reflect_utils.py — provides get_queue_path, get_global_queue_path, migrate_global_queue, and directory resolution functions called from 6 other files
  • scripts/lib/semantic_detector.py — semantic_analyze and validation functions that run external commands and handle tool error extraction
  • scripts/post_commit_reminder.py and scripts/session_start_reminder.py — hooks that nudge about pending learnings at commit and session boundaries

The system also supports skill discovery (/reflect-skills) that analyzes session history to find repeating tasks candidates for reusable commands, as documented in commands/reflect-skills.md.

How It Is Wired

Execution starts at main in scripts/capture_learning.py:26, which reaches 28 functions and is called from 1 place. The internal call graph has 298 resolved call edges. High-traffic hubs include:

  • detect_patterns — called from 46 places, central to pattern matching logic
  • semantic_analyze — called from 20 places, drives the semantic detection pipeline
  • should_include_message — called from 18 places, gates whether a message enters the learning queue

A typical run flows: main -> load_queue [filesystem via path.read_text], reading the queue, processing entries through semantic analysis and pattern detection, then writing corrected or confirmed content to CLAUDE.md/AGENTS.md. Files with the most route traffic are tests/test_reflect_utils.py (106 functions), tests/test_semantic_detector.py (53 functions), and scripts/lib/reflect_utils.py (26 functions).

How To Use It

Setup:

# Add the marketplace
claude plugin marketplace add bayramannakov/claude-reflect

# Install the plugin
claude plugin install claude-reflect@claude-reflect-marketplace

# Restart Claude Code to activate the plugin

Configuration: No environment variables or keys are required — the system operates on session history and user corrections within the Claude Code CLI.

Running it: After installation and restart, the hooks auto-configure. Use /reflect to process queued learnings with human review, or /reflect --scan-history to scan all past sessions. Commands like /reflect --review show the queue with confidence scores and decay status.

Real-World Use

During a coding session, you correct Claude: "no, use gpt-5.1 not gpt-5". The hook captures this to the learning queue. When you start your next session, /reflect processes the queue and appends the correction to CLAUDE.md, so Claude retains the preferred model across all future sessions. Over time, repeated patterns — such as asking "review my productivity" 12 times — trigger the skill discovery feature, suggesting a /daily-review command you can approve and use.

Code Health & Issues

  • [MEDIUM] Declare least-privilege permissions for GITHUB_TOKEN — .github/workflows/test.yml — 1 workflow declares no permissions; the token inherits repository defaults, so any injected step can push commits or mint releases from inside CI.
  • [MEDIUM] Set persist-credentials: false on checkout — .github/workflows/test.yml — the token stays in .git/config for every later step, so a malicious postinstall script could read a pushable credential without an explicit token being passed to it.
  • [LOW] Set timeout-minutes on the workflow jobs — .github/workflows/test.yml — no job timeout is set, so a wedged step runs to the six-hour platform default, meaning three runs can overlap on a two-hourly schedule.

The Bottom Line

The system delivers on its core promise: corrections and discovered patterns persist across Claude Code sessions via CLAUDE.md and AGENTS.md. The hook architecture is practical and the skill-discovery feature adds genuine value for long-running projects. However, the codebase shows signs of growth without corresponding refactor — deep nesting, duplicated blocks, and oversized files (818 lines in reflect_utils.py) mean changes ripple widely. The three CI hygiene findings are straightforward fixes. This is worth adopting if you run Claude Code regularly and want permanent, session-crossing context; just budget time for a initial review of the learning queue and consideration of the code health items.