self-improving-agent

$27

┌─────────────────────────────────────────────────────────┐

│                  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

clawhub install self-improving-agent

Codex CLI

./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/<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 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:

# .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

• pskoett/self-improving-agent — inspiration

• playwright-pro — sister plugin in this repo