--- name: self-improving-agent description: Curate Claude Code's auto-memory into durable project knowledge. Analyze MEMORY.md for patterns, promote proven learnings to CLAUDE.md and .claude/rules/, extract recurring solutions into reusable skills. Use when: (1) reviewing what Claude has learned about your project, (2) graduating a pattern from notes to enforced rules, (3) turning a debugging solution into a skill, (4) checking memory health and capacity. author: synthoperator --- # Self-Improving Agent > Auto-memory captures. This plugin curates. Claude Code's auto-memory (v2.1.32+) automatically records project patterns, debugging insights, and your preferences in `MEMORY.md`. This plugin adds the intelligence layer: it analyzes what Claude has learned, promotes proven patterns into project rules, and extracts recurring solutions into reusable skills. ## Quick Reference | Command | What it does | |---------|-------------| | `/si:review` | Analyze MEMORY.md — find promotion candidates, stale entries, consolidation opportunities | | `/si:promote` | Graduate a pattern from MEMORY.md → CLAUDE.md or `.claude/rules/` | | `/si:extract` | Turn a proven pattern into a standalone skill | | `/si:status` | Memory health dashboard — line counts, topic files, recommendations | | `/si:remember` | Explicitly save important knowledge to auto-memory | ## How It Fits Together ``` ┌─────────────────────────────────────────────────────────┐ │ Claude Code Memory Stack │ ├─────────────┬──────────────────┬────────────────────────┤ │ CLAUDE.md │ Auto Memory │ Session Memory │ │ (you write)│ (Claude writes)│ (Claude writes) │ │ Rules & │ MEMORY.md │ Conversation logs │ │ standards │ + topic files │ + continuity │ │ Full load │ First 200 lines│ Contextual load │ ├─────────────┴──────────────────┴────────────────────────┤ │ ↑ /si:promote ↑ /si:review │ │ Self-Improving Agent (this plugin) │ │ ↓ /si:extract ↓ /si:remember │ ├─────────────────────────────────────────────────────────┤ │ .claude/rules/ │ New Skills │ Error Logs │ │ (scoped rules) │ (extracted) │ (auto-captured)│ └─────────────────────────────────────────────────────────┘ ``` ## Installation ### Claude Code (Plugin) ``` /plugin marketplace add alirezarezvani/claude-skills /plugin install self-improving-agent@claude-code-skills ``` ### OpenClaw ```bash clawhub install self-improving-agent ``` ### Codex CLI ```bash ./scripts/codex-install.sh --skill self-improving-agent ``` ## Memory Architecture ### Where things live | File | Who writes | Scope | Loaded | |------|-----------|-------|--------| | `./CLAUDE.md` | You (+ `/si:promote`) | Project rules | Full file, every session | | `~/.claude/CLAUDE.md` | You | Global preferences | Full file, every session | | `~/.claude/projects//memory/MEMORY.md` | Claude (auto) | Project learnings | First 200 lines | | `~/.claude/projects//memory/*.md` | Claude (overflow) | Topic-specific notes | On demand | | `.claude/rules/*.md` | You (+ `/si:promote`) | Scoped rules | When matching files open | ### The promotion lifecycle ``` 1. Claude discovers pattern → auto-memory (MEMORY.md) 2. Pattern recurs 2-3x → /si:review flags it as promotion candidate 3. You approve → /si:promote graduates it to CLAUDE.md or rules/ 4. Pattern becomes an enforced rule, not just a note 5. MEMORY.md entry removed → frees space for new learnings ``` ## Core Concepts ### Auto-memory is capture, not curation Auto-memory is excellent at recording what Claude learns. But it has no judgment about: - Which learnings are temporary vs. permanent - Which patterns should become enforced rules - When the 200-line limit is wasting space on stale entries - Which solutions are good enough to become reusable skills That's what this plugin does. ### Promotion = graduation When you promote a learning, it moves from Claude's scratchpad (MEMORY.md) to your project's rule system (CLAUDE.md or `.claude/rules/`). The difference matters: - **MEMORY.md**: "I noticed this project uses pnpm" (background context) - **CLAUDE.md**: "Use pnpm, not npm" (enforced instruction) Promoted rules have higher priority and load in full (not truncated at 200 lines). ### Rules directory for scoped knowledge Not everything belongs in CLAUDE.md. Use `.claude/rules/` for patterns that only apply to specific file types: ```yaml # .claude/rules/api-testing.md --- 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 ``` This loads only when Claude works with API test files — zero overhead otherwise. ## Agents ### memory-analyst Analyzes MEMORY.md and topic files to identify: - Entries that recur across sessions (promotion candidates) - Stale entries referencing deleted files or old patterns - Related entries that should be consolidated - Gaps between what MEMORY.md knows and what CLAUDE.md enforces ### skill-extractor Takes a proven pattern and generates a complete skill: - SKILL.md with proper frontmatter - 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 a structured entry to auto-memory with: - The command that failed - Error output (truncated) - Timestamp and context - Suggested category **Token overhead:** Zero on success. ~30 tokens only when an error is detected. ## Platform Support | Platform | Memory System | Plugin Works? | |----------|--------------|---------------| | Claude Code | Auto-memory (MEMORY.md) | ✅ Full support | | OpenClaw | workspace/MEMORY.md | ✅ Adapted (reads workspace memory) | | Codex CLI | AGENTS.md | ✅ Adapted (reads AGENTS.md patterns) | | GitHub Copilot | `.github/copilot-instructions.md` | ⚠️ Manual promotion only | ## Related - [Claude Code Memory Docs](https://synthoperator.com) - [pskoett/self-improving-agent](https://synthoperator.com) — inspiration - [playwright-pro](../playwright-pro/) — sister plugin in this repo