borghei/Claude-Skills / engineering/self-improving-agent
self-improving-agent
VerifiedCurates agent memory and turns repeated lessons into reviewed rules: memory health checks, pattern extraction, feedback and regression analysis. Use when managing auto-memory or building agents that learn from their own sessions.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.0 KB |
| assets/memory_index/MEMORY.md | markdown | 316 B |
| assets/memory_index/feedback_migrations.md | markdown | 203 B |
| assets/memory_index/feedback_pnpm.md | markdown | 255 B |
| assets/sample_feedback.jsonl | other | 2.2 KB |
| assets/sample_metrics.json | config | 3.6 KB |
| references/feedback-loop-patterns.md | markdown | 9.2 KB |
| references/memory-curation-guide.md | markdown | 4.6 KB |
| references/meta-learning-architectures.md | markdown | 2.4 KB |
| references/self-improvement-methodology.md | markdown | 4.3 KB |
| scripts/feedback_analyzer.pyexecutable | script | 18.5 KB |
| scripts/memory_health_checker.py | script | 13.1 KB |
| scripts/pattern_extractor.py | script | 10.8 KB |
| scripts/regression_detector.pyexecutable | script | 17.0 KB |
| scripts/rule_manager.pyexecutable | script | 12.0 KB |
| scripts/rule_promoter.py | script | 12.0 KB |
| skills/extract.md | markdown | 2.1 KB |
| skills/promote.md | markdown | 2.8 KB |
| skills/remember.md | markdown | 2.1 KB |
| skills/review.md | markdown | 2.3 KB |
| skills/status.md | markdown | 2.5 KB |
references/self-improvement-methodology.md
View on GitHub# Self-Improvement Methodology Reference
## The Five Layers of Agent Learning
### Layer 1: Session Memory (Ephemeral)
- Context window contents
- Current conversation state
- Tool call history for this session
- Lost when session ends
### Layer 2: Persistent Memory (MEMORY.md)
- Observations captured across sessions
- Key-value learnings with metadata
- 200-line limit to prevent bloat
- Topic files for overflow
### Layer 3: Enforced Rules (CLAUDE.md / .claude/rules/)
- Promoted patterns that proved reliable
- Loaded every session automatically
- Highest authority after system instructions
- Must have "why" annotation
### Layer 4: Extracted Skills
- Reusable packages graduated from patterns
- Self-contained with scripts and references
- Can be shared across projects
### Layer 5: Meta-Learning
- Strategies for what to capture and when
- Adaptive thresholds based on value delivered
- Self-tuning promotion criteria
## Confidence Scoring Model
```
effective_confidence = base_score * recency_factor * consistency_factor
base_score:
user-stated: 1.0 (user explicitly told us)
observed: 0.8 (we saw it work)
inferred: 0.6 (we deduced from evidence)
guessed: 0.3 (speculation)
recency_factor:
0-7 days: 1.0
7-30 days: 0.9
30-90 days: 0.7
90+ days: 0.5
consistency_factor:
never contradicted: 1.0
contradicted + reaffirmed: 0.9
contradicted, unresolved: 0.5
actively contradicted: 0.0 (delete)
```
## Promotion Decision Tree
```
Entry in MEMORY.md
├── Recurrence >= 3?
│ ├── NO → KEEP (continue monitoring)
│ └── YES
│ ├── Consistent solution every time?
│ │ ├── NO → KEEP (needs more evidence)
│ │ └── YES
│ │ ├── Referenced code/tools still exist?
│ │ │ ├── NO → STALE (delete)
│ │ │ └── YES
│ │ │ ├── Expressible in 1-2 sentences?
│ │ │ │ ├── NO → EXTRACT (make a skill)
│ │ │ │ └── YES → PROMOTE
│ │ │ │ ├── Coding convention → .claude/rules/
│ │ │ │ ├── Architecture rule → CLAUDE.md
│ │ │ │ ├── Tool preference → CLAUDE.md
│ │ │ │ └── Scoped rule → .claude/rules/ with paths:
```
## Memory Curation Checklist
Weekly health check steps:
1. [ ] Read MEMORY.md completely
2. [ ] Check line count (must be < 200)
3. [ ] For each entry, classify: PROMOTE / CONSOLIDATE / STALE / KEEP / EXTRACT
4. [ ] Merge duplicates (CONSOLIDATE)
5. [ ] Delete stale entries (references deleted code, old patterns)
6. [ ] Promote ready entries (recurrence >= 3, consistent, impactful)
7. [ ] Move topic-specific overflow to topic files
8. [ ] Verify all rules in .claude/rules/ still reference existing code
9. [ ] Log the health check outcome
## Anti-Patterns in Self-Improvement
| Anti-Pattern | Symptom | Fix |
|-------------|---------|-----|
| Memory hoarding | MEMORY.md > 200 lines, never pruned | Schedule weekly curation |
| Premature promotion | Rules promoted after 1 occurrence | Enforce 3+ recurrence minimum |
| Cargo cult rules | Rules copied without understanding why | Require "why" annotation on every rule |
| Stale rule accumulation | Rules reference deleted code/tools | Timestamp rules, verify periodically |
| Contradiction spiral | New rules conflict with existing ones | Belief revision protocol: compare confidence, resolve |
| Observation bias | Only capturing failures, not successes | Track both; success patterns inform approach selection |
| Over-promotion | Everything becomes a rule | Cap at 15-25% promotion rate; most entries should KEEP |
## Metrics and Thresholds
| Metric | Healthy Range | Action if Out of Range |
|--------|--------------|----------------------|
| MEMORY.md line count | 50-200 | Prune if over; if under 50, capture more |
| Promotion rate (30d) | 15-25% | Adjust capture strategy or promotion criteria |
| Stale entry ratio | < 10% | Run curation immediately |
| Rule count | 10-50 | Consolidate if over 50; add more if under 10 |
| First-attempt success | > 70% | Investigate regressions, check rule quality |
| Contradiction count | 0 | Resolve immediately via belief revision |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |