self-improving-agent

What this skill does

# Self-Improving Agent - Autonomous Learning Patterns

**Tier:** POWERFUL
**Category:** Engineering
**Tags:** self-improvement, AI agents, feedback loops, auto-memory, meta-learning, performance tracking

## Overview

Self-Improving Agent provides architectural patterns for AI agents that get better with use. Most agents are stateless -- they make the same mistakes repeatedly because they lack mechanisms to learn from their own execution. This skill addresses that gap with concrete patterns for feedback capture, memory curation, skill extraction, and regression detection.

The key insight: auto-memory captures everything, but curation is what turns noise into knowledge.

## Sub-Skills

This skill uses compound sub-skill architecture. Each sub-skill in `skills/` handles a specific step of the improvement loop:

| Sub-Skill | File | Purpose |
|-----------|------|---------|
| **Remember** | `skills/remember.md` | Capture errors and learnings from current session |
| **Extract** | `skills/extract.md` | Extract reusable patterns from completed work |
| **Promote** | `skills/promote.md` | Graduate proven patterns to permanent rules |
| **Review** | `skills/review.md` | Audit memory health, prune stale entries |
| **Status** | `skills/status.md` | Dashboard showing memory state and learning progress |

### Sub-Skill Flow

```
Remember ──> Extract ──> Promote ──> Review
    ^                                  │
    └──────────── Status ◄─────────────┘
```

**The improvement cycle:** Remember captures events during work, Extract identifies patterns across sessions, Promote graduates proven patterns to rules, Review maintains memory health, and Status provides visibility into the entire system.

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/pattern_extractor.py` | Extract reusable patterns from session logs |
| `scripts/memory_health_checker.py` | Audit memory for stale, duplicate, and promotable entries |
| `scripts/rule_promoter.py` | Validate and apply promotions from memory to rules |
| `scripts/feedback_analyzer.py` | Analyze feedback logs for success rates and opportunities |
| `scripts/regression_detector.py` | Compare baseline vs current performance metrics |
| `scripts/rule_manager.py` | Manage a learned rules knowledge base with CRUD |

## Core Architecture

### The Improvement Loop

```
┌──────────────────────────────────────────────────────────┐
│                   SELF-IMPROVEMENT CYCLE                  │
│                                                          │
│  ┌─────────┐    ┌──────────┐    ┌─────────────┐        │
│  │ Execute  │───▶│ Evaluate │───▶│ Extract     │        │
│  │ Task     │    │ Outcome  │    │ Learnings   │        │
│  └─────────┘    └──────────┘    └─────────────┘        │
│       ▲                               │                  │
│       │                               ▼                  │
│  ┌─────────┐    ┌──────────┐    ┌─────────────┐        │
│  │ Apply   │◀───│ Promote  │◀───│ Validate    │        │
│  │ Rules   │    │ to Rules │    │ Learnings   │        │
│  └─────────┘    └──────────┘    └─────────────┘        │
│                                                          │
└──────────────────────────────────────────────────────────┘
```

### Improvement Maturity Levels

| Level | Name | Mechanism | Example |
|-------|------|-----------|---------|
| 0 | Stateless | No memory between sessions | Default agent behavior |
| 1 | Recording | Captures observations, no action | Auto-memory logging |
| 2 | Curating | Organizes and deduplicates observations | Memory review + cleanup |
| 3 | Promoting | Graduates patterns to enforced rules | MEMORY.md entries become CLAUDE.md rules |
| 4 | Extracting | Creates reusable skills from proven patterns | Recurring solutions become skill packages |
| 5 | Meta-Learning | Adapts learning strategy itself | Adjusts what to capture based on what proved useful |

Most agents operate at Level 0-1. This skill provides the machinery for Levels 2-5.

## Core Capabilities

### 1. Memory Curation System

#### The Memory Stack

```
┌─────────────────────────────────────────────────┐
│  CLAUDE.md / .claude/rules/                      │
│  Highest authority. Enforced every session.       │
│  Capacity: Unlimited. Load: Full file.           │
├─────────────────────────────────────────────────┤
│  MEMORY.md (auto-memory)                         │
│  Project learnings. Auto-captured by Claude.     │
│  Capacity: First 200 lines loaded. Overflow to   │
│  topic files.                                    │
├─────────────────────────────────────────────────┤
│  Session Context                                  │
│  Current conversation. Ephemeral.                │
│  Capacity: Context window.                       │
└─────────────────────────────────────────────────┘
```

#### Memory Review Protocol

Run periodically (weekly or after every 10 sessions):

```
Step 1: Read MEMORY.md and all topic files
Step 2: Classify each entry

  Categories:
  - PROMOTE: Pattern proven 3+ times, should be a rule
  - CONSOLIDATE: Multiple entries saying the same thing
  - STALE: References deleted files, old patterns, resolved issues
  - KEEP: Still relevant, not yet proven enough to promote
  - EXTRACT: Recurring solution that should be a reusable skill

Step 3: Execute actions
  - PROMOTE entries → move to CLAUDE.md or .claude/rules/
  - CONSOLIDATE entries → merge into single clear entry
  - STALE entries → delete
  - EXTRACT entries → create skill package (see Skill Extraction)

Step 4: Verify MEMORY.md is under 200 lines
  - If over 200: move topic-specific entries to topic files
  - Topic files: ~/.claude/projects/<path>/memory/<topic>.md
```

#### Promotion Criteria

An entry is ready for promotion when:

| Criterion | Threshold | Why |
|-----------|-----------|-----|
| Recurrence | Seen in 3+ sessions | Not a one-off |
| Consistency | Same solution every time | Not context-dependent |
| Impact | Prevented errors or saved significant time | Worth enforcing |
| Stability | Underlying code/system unchanged | Won't immediately become stale |
| Clarity | Can be stated in 1-2 sentences | Rules must be unambiguous |

#### Promotion Targets

| Pattern Type | Promote To | Example |
|-------------|-----------|---------|
| Coding convention | `.claude/rules/<area>.md` | "Always use `type` not `interface` for object shapes" |
| Project architecture | `CLAUDE.md` | "All API routes go through middleware chain" |
| Tool preference | `CLAUDE.md` | "Use pnpm, not npm" |
| Debugging pattern | `.claude/rules/debugging.md` | "When tests fail, check env vars first" |
| File-scoped rule | `.claude/rules/<scope>.md` with `paths:` | "In migrations/, always add down migration" |

### 2. Feedback Loop Design

#### Outcome Classification

Every agent task produces an outcome. Classify it:

```
SUCCESS         - Task completed, user accepted result
PARTIAL         - Task completed but required corrections
FAILURE         - Task failed, user had to redo
REJECTION       - User explicitly rejected approach
TIMEOUT         - Task exceeded time/token budget
ERROR           - Technical error (tool failure, API error)
```

#### Signal Extraction from Outcomes

| Outcome | Signal | Memory Action |
|---------|--------|---------------|
| SUCCESS (first try) | Approach works well | Reinforce (increment confidence) |
| SUCCESS (after correction) | Initial approach had gap | Log the correction pattern |
| PARTIAL (user edited result) | Output format or content gap | Log what user changed |
| FAILURE | Approach fundamentally wrong | Log anti-pattern with context |
| REJECTION | Misunderstood requirements | Log clarification pattern |
| Repeated ERROR | Tool or environment issue | Log workaround or fix |

#### Feedback Capture Template

```markdown
## Learning: [Short description]

**Context:** [What task was being performed]
**What happened:** [Outcome description]
**Root cause:** [Why the outcome occurred]
**Correct approach:** [Wh