Aio Reflect

Quick Start

RF="$(ls -d ~/.claude/plugins/cache/aiocean-plugins/aio-reflect/*/skills/aio-reflect/scripts 2>/dev/null | sort -V | tail -1)"
MEMORY="$HOME/.claude/aio-reflect/memory"
mkdir -p "$MEMORY/diary" "$MEMORY/reflections"

Then call scripts as bun run $RF/script-name:

# Extract last 5 sessions with diary summary
bun run $RF/extract-session.ts <project-path> --last 5 --diary

# Full extraction with thinking blocks
bun run $RF/extract-session.ts <project-path> --last 5 --verbose

# Deep extraction with subagent conversations
bun run $RF/extract-session.ts <project-path> --last 5 --full --verbose

# JSON output for further processing
bun run $RF/extract-session.ts <project-path> --last 5 --json

# Stats only (cost, tokens, work mode, tasks)
bun run $RF/extract-session.ts <project-path> --last 10 --stats-only

Data Extracted

The extractor deeply understands Claude Code's JSONL format and storage:

Per session:

• Full conversation (noise-filtered: isSidechain skipped, system tags stripped, internal messages removed)
• Token usage & estimated cost (model-specific pricing with long-context tiers, cache multipliers)
• Work mode classification: Exploration (Read/Grep/Glob) vs Building (Write/Edit) vs Testing (Bash/Agent)
• Subagent transcripts from {uuid}/subagents/agent-*.jsonl
• Task reconstruction from TaskCreate/TaskUpdate tool calls + ~/.claude/tasks/{uuid}/
• Compaction events (auto/manual trigger, pre-compaction token count)
• Session chaining (resumed sessions via leaf_uuid/slug)
• File operations (reads, writes, edits with file paths)
• Model distribution (Opus/Sonnet/Haiku usage counts)
• Cache hit rates
• Session titles (from summary messages, correctly distinguished from compaction)
• Skills and agents invoked

Aggregate (multiple sessions):

• Total cost, tokens, duration, tool calls, subagents
• Aggregate work mode distribution
• Model distribution across sessions

Workflow

Phase 1: Setup

1. Create todo list for tracking progress
2. Get target project path (or use current directory)
3. Verify sessions exist:

   bun run $RF/get-project-path.ts <path> --check
   

3.5. (Optional) List all projects with sessions:

bun run $RF/project-tree.ts --stats

4. Check for unprocessed sessions:

   # List sessions with stats to identify unprocessed ones
   bun run $RF/extract-session.ts <project-path> --stats-only
   # Then compare session IDs against $MEMORY/processed.json
   

5. Load existing CLAUDE.md rules (for violation detection)
6. Ask user how many sessions to analyze (default: 5)

Phase 2: Extract Sessions

bun run $RF/extract-session.ts <project-folder> --last N --verbose

Output includes:

• Session metadata (date, duration, branch)
• Diary summary (task, files modified, work items)
• Full conversation with tool calls and results
• Thinking blocks (with --verbose)
• Skills and agents used
• Session statistics

Phase 3: Analyze (AI does this)

Read the extracted sessions holistically. Let AI identify what matters - don't use keyword detection or bias towards "corrections".

Core Question: What knowledge from these sessions is reusable and can evolve?

A. Check Rule Violations

Compare session with existing CLAUDE.md rules:

• Was any existing rule violated?
• If yes → Strengthen the rule first (don't add new)

B. Find Friction Points

Detect patterns where user repeatedly has to:

• Remind AI of something every session
• Manually do something AI should handle
• Correct the same type of mistake
• Explain the same context again

Ask: What would make this friction disappear?

C. Discover Preferences

Patterns the user consistently shows across sessions:

• Tools/skills they always use or request
• Approaches they consistently prefer
• Implicit expectations made explicit through repetition

Only worth capturing if it appears multiple times across sessions.

D. Extract Reusable Knowledge

AI should freely identify knowledge that:

• Repeats across sessions - patterns, not one-off incidents
• Can evolve - builds upon existing knowledge
• Is generalizable - applies beyond this specific context

Skip:

• Context-specific corrections (already handled in the moment)
• One-time fixes (no reuse value)
• Things already obvious or in docs

E. Evaluate Skill Candidates (Selective)

Criteria for extracting a skill:

• Required >10 minutes investigation
• Solution was non-obvious (not just docs lookup)
• Has specific trigger conditions (error messages, symptoms)
• Solution was verified to work
• Would help someone facing same problem in future
• Doesn't duplicate existing skills/docs

Types of extractable knowledge:

• Non-obvious debugging techniques
• Error patterns where message was misleading
• Workarounds discovered through trial-and-error
• Configuration insights not in official docs
• Patterns specific to codebase or tech stack

Phase 4: Synthesize

Present findings in structured format:

## Reflection: [Project Name]

Analyzed [N] sessions from [date range]

### Rule Violations (if any)

- **Rule**: [existing rule text]
- **What happened**: [brief description]
- **Action**: Strengthen → [proposed new text]

### Friction Points

1. **Pattern**: [what user repeatedly has to do]
   **Frequency**: [how often across sessions]
   **Solution**: [what would eliminate this friction]

### Preferences

1. **Preference**: [what user consistently does/requests]
   **Evidence**: [sessions where this appeared]

### Reusable Knowledge

1. **Knowledge**: [what was learned]
   **Why reusable**: [how it applies beyond this session]

### Skill Candidates

1. **Problem**: [what problem this solves]
   **Trigger**: [when to use]
   **Worth creating?**: [Yes/No + reasoning]

### Proposed Changes

#### CLAUDE.md Updates

**Change**: [add/modify/strengthen]
**Text**: [exact text]
**Rationale**: [why this helps future sessions]

#### New Skills

[For each proposed skill]

**Name**: [kebab-case-name]
**Problem**: [one-line description]
**Trigger**: [error messages, symptoms]
**Evidence**: [session quote]

Phase 5: Apply (with approval)

IMPORTANT: Never create or modify files without explicit user approval.

Step 1: Ask which changes to apply

Present all proposed changes and ask: "Which of these should I apply?"

Options:

• "all" - apply everything
• "1, 3, 5" - apply specific items by number
• "none" - cancel
• "just CLAUDE.md" / "just skills" - filter by type

Step 2: Apply CLAUDE.md updates

For rule violations (strengthen existing):

1. Read current CLAUDE.md
2. Find the violated rule
3. Strengthen it (don't add new rule)
4. Show diff for confirmation

For new rules:

1. Read current CLAUDE.md
2. Add new rules at appropriate location
3. Show diff for confirmation

Step 3: Create skills (if approved)

1. Research best practices (web search) if technology-specific
2. Use skill template (below)
3. Show full skill content for review
4. Ask: "Confirm creation?"
5. Create file only after confirmation

Step 4: Mark sessions as processed

Update $MEMORY/processed.json:

{
  "sessions": {
    "session-id": {
      "project": "/path/to/project",
      "processedAt": "2026-01-18T12:00:00Z",
      "learningsApplied": 3
    }
  }
}

Step 5: Write diary entry (optional)

If user wants, save reflection to $MEMORY/diary/YYYY-MM-DD-reflection.md

Skill Template

---