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
code
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:
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
code
┌─────────────────────────────────────────────────────────┐ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Capture │ ──▶ │ Analyze │ ──▶ │ Evolve │ │ │ │ Events │ │ Patterns│ │ Skills │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ ▲ │ │ │ │ ┌──────────┐ │ │ │ └────────── │ Memory │ ◀─────────┘ │ │ │ System │ │ │ └──────────┘ │ │ │ └─────────────────────────────────────────────────────────┘
Commands
/retrospective - Session Review
Ask Claude to generate a session retrospective:
code
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:
code
User: This error handling approach is useful. /evolve it to a skill.
Claude will:
- •Extract the pattern
- •Create a skill draft in
community/ - •Add validation criteria
/dashboard - Visual Report
code
User: /dashboard
Opens the visual evolution dashboard showing:
- •Session statistics
- •Memory state
- •Skill effectiveness heatmap
- •Improvement opportunities
Configuration
Edit config.json:
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
code
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:
code
[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.