Auto-Evolution: Memory-Driven Self-Evolution for Agent Skills

Transform your agent from a static assistant into a learning system that evolves with every interaction.

What Makes This Different

Traditional Skills:  User → Agent → Output (static)

Auto-Evolution:      User → Agent → Output
                              ↓
                        [Capture] → [Memory] → [Learn] → [Evolve]
                              ↓
                     Agent gets smarter over time

Quick Start

1. Enable Hooks

Add to your .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{"matcher": "Read|Write|Edit|Bash", "hooks": [{"type": "command", "command": "bash .claude/skills/evolution/hooks/capture.sh \"$TOOL_NAME\" \"$TOOL_INPUT\""}]}],
    "PostToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "bash .claude/skills/evolution/hooks/capture.sh post-bash \"$TOOL_OUTPUT\" \"$EXIT_CODE\""}]}],
    "Stop": [{"matcher": "", "hooks": [{"type": "command", "command": "bash .claude/skills/evolution/hooks/reflect.sh"}]}]
  }
}

2. Work Normally

Just use Claude Code as you always do. The system silently captures:

• Which skills you use
• Commands that succeed or fail
• Patterns that repeat

3. See Your Evolution

At session end, open reports/dashboard.html for a visual summary.

---

Core Concepts

Three-Layer Memory System

Layer	Purpose	Retention	Example
Episodic	Raw events	7 days	"Used layout.md at 14:32"
Semantic	Patterns	30 days	"TypeScript errors often follow X"
Procedural	How-to knowledge	Permanent	Ready-to-use skill drafts

The Evolution Loop

┌─────────────────────────────────────────────────────────┐
│                                                          │
│   ┌──────────┐     ┌──────────┐     ┌──────────┐        │
│   │  Capture │ ──▶ │  Analyze │ ──▶ │  Evolve  │        │
│   │  Events  │     │  Patterns│     │  Skills  │        │
│   └──────────┘     └──────────┘     └──────────┘        │
│        ▲                                   │            │
│        │           ┌──────────┐           │            │
│        └────────── │  Memory  │ ◀─────────┘            │
│                    │  System  │                         │
│                    └──────────┘                         │
│                                                          │
└─────────────────────────────────────────────────────────┘

---

Commands

/retrospective - Session Review

Ask Claude to generate a session retrospective:

User: /retrospective

Produces:

• Skills used with frequency counts
• Errors encountered and resolutions
• Patterns detected
• Improvement suggestions

/evolve - Promote Knowledge

When you discover a reusable pattern:

User: This error handling approach is useful. /evolve it to a skill.

Claude will:

1. Extract the pattern
2. Create a skill draft in community/
3. Add validation criteria

/dashboard - Visual Report

User: /dashboard

Opens the visual evolution dashboard showing:

• Session statistics
• Memory state
• Skill effectiveness heatmap
• Improvement opportunities

---

Configuration

Edit config.json:

{
  "memory": {
    "episodic_ttl_days": 7,
    "semantic_ttl_days": 30,
    "pattern_threshold": 3
  },
  "capture": {
    "ignore_exit_codes": [1],
    "ignore_patterns": ["grep|rg|test"],
    "force_patterns": ["error|fatal|panic"]
  },
  "evolution": {
    "auto_draft": true,
    "require_validation": true,
    "min_occurrences": 3
  }
}

---

File Structure

evolution/
├── SKILL.md           # This file
├── config.json        # All settings
├── memory/
│   ├── episodes.jsonl # Raw events (append-only)
│   ├── patterns.json  # Detected patterns
│   └── drafts/        # Skill candidates
├── hooks/
│   ├── lib.sh         # Shared utilities
│   ├── capture.sh     # Event capture
│   └── reflect.sh     # Session reflection
├── reports/
│   ├── dashboard.html # Visual dashboard
│   └── sessions/      # Session reports
├── templates/
│   └── skill.md       # Skill template
└── community/
    └── README.md      # Contribution guide

---

Quality Gates

Skills evolve through stages:

[Detected] ──▶ [Draft] ──▶ [Validated] ──▶ [Promoted]
    │             │            │              │
    │             │            │              └─ Becomes official skill
    │             │            └─ Verified to work
    │             └─ Structured documentation
    └─ Pattern appears 3+ times

---

Integration

Works with any skills library. Just copy evolution/ to your .claude/skills/ directory.

For advanced integration, see ARCHITECTURE.md.