self-improving-agent

---
name: self-improving-agent
description: Use when curating auto-memory into durable project knowledge. Analyze patterns, promote learnings to rules, extract solutions into skills, review memory health.
category: Engineering
version: 1.0.0
tools: []
---

# Self-Improving Agent

Curate Claude Code's auto-memory into durable project knowledge and enforced rules.

## Commands

| Command | Purpose |
|---------|----------|
| `/si:review` | Analyze MEMORY.md—find promotion candidates, stale entries, consolidation opportunities |
| `/si:promote` | Graduate pattern from MEMORY.md → CLAUDE.md or `.claude/rules/` |
| `/si:extract` | Turn proven pattern into standalone skill |
| `/si:status` | Memory health dashboard—line counts, topics, recommendations |
| `/si:remember` | Explicitly save important knowledge to auto-memory |

## Memory Architecture

**Where things live:**

| File | Writes | Scope | Load Behavior |
|------|--------|-------|----------------|
| `./CLAUDE.md` | You + /si:promote | Project rules | Full file |
| `~/.claude/CLAUDE.md` | You | Global preferences | Full file |
| `~/.claude/projects/<path>/memory/MEMORY.md` | Claude (auto) | Project learnings | First 200 lines |
| `~/.claude/projects/<path>/memory/*.md` | Claude (overflow) | Topic-specific notes | On demand |
| `.claude/rules/*.md` | You + /si:promote | Scoped rules | When matching files |

**Promotion lifecycle:**
1. Claude discovers pattern → auto-memory (MEMORY.md)
2. Pattern recurs 2-3 times → /si:review flags as candidate
3. User approves → /si:promote graduates to CLAUDE.md or rules/
4. Pattern becomes enforced rule, not just a note
5. MEMORY.md entry removed → frees space for new learnings

## Core Concepts

**Auto-memory is capture, not curation.** Excellent at recording discoveries, but has no judgment about:
- Which learnings are temporary vs. permanent
- Which patterns should become enforced rules
- When 200-line limit wastes space on stale entries
- Which solutions are good enough to become reusable skills

That's what this plugin does.

**Promotion = graduation.** Moves from scratchpad (MEMORY.md) to rules (CLAUDE.md or `.claude/rules/`).
- MEMORY.md: "I noticed this project uses pnpm" (context)
- CLAUDE.md: "Use pnpm, not npm" (enforced)

**Rules directory for scoped knowledge.** Not everything belongs in CLAUDE.md. Use `.claude/rules/` for patterns applying only to specific file types:
```yaml
paths:
  - "src/api/**/*.test.ts"
  - "tests/api/**/*"
---
- Use supertest for API endpoint testing
- Mock external services with msw
- Always test error responses, not just happy paths
```

## Agents

**memory-analyst**: Analyzes MEMORY.md to identify:
- Entries recurring across sessions (promotion candidates)
- Stale entries referencing deleted files
- Related entries needing consolidation
- Gaps between MEMORY.md learnings and CLAUDE.md enforcement

**skill-extractor**: Generates complete skill from proven pattern:
- SKILL.md with proper structure
- Reference documentation
- Examples and edge cases
- Ready for plugin install or clawhub publish

## Hooks

**error-capture (PostToolUse → Bash)**: Monitors command output for errors. When detected, appends structured entry to auto-memory with:
- Failed command
- Error output (truncated)
- Timestamp and context
- Suggested category

Token overhead: Zero on success, ~30 tokens only when error detected.