Self-Improving Agent Patterns with Memory Curation: Automating Knowledge Management in Claude Code

The self-improving agent pattern transforms Claude Code's ephemeral MEMORY.md into a permanent knowledge base by automatically promoting validated patterns to enforceable rules in CLAUDE.md or scoped .claude/rules/ files.

The alirezarezvani/claude-skills repository implements a sophisticated memory curation system that elevates AI-generated observations into self-maintaining project standards. By implementing these self-improving agent patterns, development teams ensure that recurring insights discovered during coding sessions graduate from transient auto-memory entries to authoritative configuration files that persist across sessions.

Memory Architecture and Data Flow

The memory curation system operates across a tiered architecture defined in engineering-team/self-improving-agent/SKILL.md, where each storage layer serves distinct persistence and loading behaviors:

Component	Written By	Scope	Load Behavior
CLAUDE.md	User via /si:promote	Global project rules	Fully loaded every session
~/.claude/CLAUDE.md	User	Global preferences	Fully loaded every session
~/.claude/projects/<path>/memory/MEMORY.md	Claude (auto)	Project-level learnings	First 200 lines only (truncated)
~/.claude/projects/<path>/memory/*.md	Claude (overflow)	Topic-specific notes	Loaded on demand
.claude/rules/*.md	User via /si:promote	Scoped rules (e.g., API tests)	Loaded only when matching files open

This hierarchical design ensures that high-value promoted rules receive full context window priority while raw auto-memory remains constrained to prevent context pollution.

The Pattern Promotion Lifecycle

According to the architecture documented in the skill's source code, patterns progress through a five-stage promotion pipeline:

1. Discovery: Claude identifies a recurring pattern during development and records it to MEMORY.md via auto-memory.
2. Validation: After 2-3 occurrences, the memory-analyst sub-agent flags the entry during /si:review as a promotion candidate.
3. Approval: The user executes /si:promote <pattern-id> to graduate the insight.
4. Enforcement: The pattern migrates to CLAUDE.md or a scoped .claude/rules/ file, where it becomes an enforced standard.
5. Cleanup: The original entry is removed from MEMORY.md, freeing space within the 200-line truncation limit.

This lifecycle prevents stale memories from accumulating while ensuring validated knowledge becomes permanent.

Core Sub-Agents and Automation Hooks

The self-improving agent implements three specialized sub-agents defined in engineering-team/self-improving-agent/SKILL.md:

memory-analyst: Scans MEMORY.md and topic-specific overflow files to identify recurring patterns, stale entries requiring consolidation, and gaps in the current knowledge base.

skill-extractor: Generates complete skill packages including SKILL.md with front-matter metadata, reference documentation, and executable scripts when patterns prove reusable across projects.

error-capture hook: Automatically appends structured entries (~30 tokens) to MEMORY.md when commands fail, converting immediate errors into future prevention rules.

Platform Compatibility and Adaptation

The memory curation patterns adapt to multiple AI coding platforms as documented in the skill's platform support matrix:

Platform	Memory Source	Plugin Support
Claude Code	MEMORY.md (project)	Full native support
OpenClaw	workspace/MEMORY.md	Adapted
Codex CLI	AGENTS.md	Adapted
GitHub Copilot	.github/copilot-instructions.md	Manual promotion only

Installation and Command Reference

Install the self-improving agent skill via the Claude Code marketplace or alternative package managers:

# Claude Code (recommended)

/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

The skill exposes five primary commands for memory curation:

Command	Function
/si:review	Analyzes MEMORY.md for promotion candidates, stale notes, and consolidation opportunities
/si:promote	Moves selected entries to CLAUDE.md or .claude/rules/ files
/si:extract	Converts proven patterns into reusable skills with SKILL.md and scripts
/si:status	Displays dashboard metrics including line counts, topic distribution, and health recommendations
/si:remember	Explicitly writes custom structured entries to auto-memory

Practical Implementation Workflow

A typical memory curation session follows this validated pattern:

# 1. Review memory for recurring patterns

/si:review

# Output: "Pattern: use pnpm for package management (3 occurrences)"

# 2. Promote validated pattern to enforced rule

/si:promote pnpm-usage

# Result: Appends to CLAUDE.md or creates .claude/rules/pnpm-usage.md

# 3. Extract complex error-handling as reusable skill

/si:extract retry-on-failure

# Generates: engineering-team/retry-on-failure/ with SKILL.md and scripts/

Adding Structured Memory Entries

Explicitly capture high-value observations using the /si:remember command with front-matter metadata:

/si:remember <<EOF
---
topic: build-system
tags: [pnpm, node, ci]
---
We observed faster CI builds when switching to pnpm. Promote this pattern.
EOF

This creates a structured entry that the memory-analyst will prioritize during the next review cycle.

Rule Generation Structure

When /si:extract processes a pattern, it generates scoped rule files with path matching:

# .claude/rules/pnpm-usage.md

---
paths:
  - "**/package.json"
---
- Use **pnpm** for all package installations.
- Enforce `nodeLinker: "pnp"` in .npmrc.

Summary

• Self-improving agent patterns automate the graduation of transient AI observations into permanent project standards through systematic memory curation.
• The promotion lifecycle moves patterns from auto-generated MEMORY.md entries to enforceable CLAUDE.md rules after 2-3 validation occurrences.
• Scoped rules in .claude/rules/ provide context-specific enforcement that loads only when relevant files are open, optimizing context window usage.
• The memory-analyst and skill-extractor sub-agents automate the detection and packaging of reusable patterns, while the error-capture hook converts failures into future guardrails.
• Regular execution of /si:review prevents the 200-line MEMORY.md truncation limit from discarding valuable insights before promotion.

Frequently Asked Questions

How does the 200-line limit on MEMORY.md affect knowledge retention?

Claude Code loads only the first 200 lines of MEMORY.md into the context window, truncating older entries. The self-improving agent mitigates this constraint by automatically removing promoted entries from MEMORY.md after they graduate to CLAUDE.md or .claude/rules/, ensuring high-priority memories remain visible while validated knowledge persists in permanent rule files.

What distinguishes CLAUDE.md from .claude/rules/ files?

CLAUDE.md serves as global project rules loaded into every session, making it ideal for universal standards like "Use TypeScript for all new files." In contrast, .claude/rules/*.md files provide scoped enforcement loaded only when matching file patterns open, which is optimal for domain-specific conventions such as API testing standards that should only apply when test files are active.

Can extracted skills be shared across different projects?

Yes. The /si:extract command generates complete skill packages including SKILL.md with front-matter metadata, reference documentation, and executable scripts. These packages can be published to the Claude Code marketplace, OpenClaw's clawhub, or internal repositories, allowing teams to distribute validated patterns across multiple codebases.

How does the error-capture hook automatically improve future sessions?

When a command fails, the error-capture hook automatically appends a structured entry (~30 tokens) to MEMORY.md documenting the failure mode and resolution. During subsequent /si:review executions, the memory-analyst flags these error patterns for promotion to preventive rules in CLAUDE.md, converting historical bugs into enforced guardrails that prevent recurrence.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}