Self-Improving Agent — Claude Code Instructions

This plugin helps you curate Claude Code's auto-memory into durable project knowledge.

Commands

Use the /self-improving-agent: namespace for all commands:

• /self-improving-agent:review — Analyze auto-memory health and find promotion candidates
• /self-improving-agent:promote <pattern> — Graduate a learning to CLAUDE.md or .claude/rules/
• /self-improving-agent:extract <pattern> — Create a reusable skill from a proven pattern
• /self-improving-agent:status — Quick memory health dashboard
• /self-improving-agent:remember <knowledge> — Explicitly save something to auto-memory

How auto-memory works

Claude Code maintains ~/.claude/projects/<project-path>/memory/MEMORY.md automatically. The first 200 lines load into every session. When it grows too large, Claude moves details into topic files like debugging.md or patterns.md.

This plugin reads that directory — it never creates its own storage.

When to use each command

After completing a feature or debugging session

/self-improving-agent:review

Check if anything Claude learned should become a permanent rule.

When a pattern keeps coming up

/self-improving-agent:promote "Always run migrations before tests in this project"

Moves it from MEMORY.md (background note) to CLAUDE.md (enforced rule).

When you solved something non-obvious that could help other projects

/self-improving-agent:extract "Docker build fix for ARM64 platform mismatch"

Creates a standalone skill with SKILL.md, ready to install elsewhere.

To check memory capacity

/self-improving-agent:status

Shows line counts, topic files, stale entries, and recommendations.

Key principle

Don't fight auto-memory — orchestrate it.

• Auto-memory is great at capturing patterns. Let it do its job.
• This plugin adds judgment: what's worth keeping, what should be promoted, what's stale.
• Promoted rules in CLAUDE.md have higher priority than MEMORY.md entries.
• Removing promoted entries from MEMORY.md frees space for new learnings.

Agents

Both register under the plugin namespace: self-improving-agent:memory-analyst and self-improving-agent:skill-extractor (plugin name + agent name — not the agent name twice). Use those exact strings as subagent_type.

• skill-extractor: spawned by /self-improving-agent:extract Step 4 to generate complete skill packages
• memory-analyst: available for cross-file pattern analysis. /self-improving-agent:review does not spawn it — that flow runs inline, start to finish. Spawn it yourself when you want an independent second pass over the memory files.

Hooks

The error-capture.sh hook fires on PostToolUse (Bash only). It scans the command's output text for error patterns and surfaces a short reminder (via hookSpecificOutput.additionalContext) suggesting /self-improving-agent:remember to save the solution — it does not write to auto-memory itself. Zero overhead unless an error pattern matches.

It matches the output text, not the exit status. The tool_response Claude Code hands the hook carries no numeric exit code at all — stdout / stderr / interrupted / isImage / noOutputExpected on every record, plus occasional extras, none of them an exit status (see hooks/CLAUDE.md for the measured field list; do not restate it as a closed set here). So a command that succeeded while printing failed or error: will also fire. Matching is per line, so one incidental console.error no longer silences a real failure beside it.

It is registered automatically by hooks/hooks.json — do not add it to settings.json by hand (see hooks/CLAUDE.md).