Mulch Self Improver — Let your agents grow 🌱

Structured expertise that accumulates over time, lives in git, and works with any agent. Agents start each session from zero; the pattern discovered yesterday is forgotten today. This skill uses Mulch: agents call

mulch record

mulch query

Benefits: Better and more consistent coding · Improved experience · Less hallucination (grounding in project expertise)

When to use: Command/tool fails, user corrects you, user wants a missing feature, your knowledge was wrong, or you found a better approach — record with Mulch and promote proven patterns to project memory. Auto-detection: The hook now detects errors and corrections automatically and prompts to record.

Mechanics: One learning store —

.mulch/

mulch prime

mulch record <domain> --type <type> ...

.learnings/

Qualification (features, benefits, pain points): See QUALIFICATION.md. Benchmark (token efficiency, troubleshooting skill improvement): See BENCHMARK.md — e.g. ~54% fewer chars to get same resolutions; find rate same or better; less context → fewer tokens, less noise, lower risk of wrong fix.

New Features (v1.1)

Auto-Detection

The hook now automatically detects learning moments:

• Errors/failures — When commands fail or return errors
• Corrections — When you say "no", "actually", "wrong", etc.
• Retries — When you ask to try again

The agent will prompt: "Want me to record this for next time?"

Pre-loaded Domains

24 preset domains included in

config/domains.json

api, database, testing, frontend, backend, infra, docs, config,
security, performance, deployment, auth, errors, debugging,
workflow, customer, system, marketing, sales, content,
competitors, crypto, automation, openclaw

Notifications

When a learning is recorded, you're notified via Telegram.

Quick Reference

mulch record <domain> --type failure --description "..." --resolution "..."

mulch record <domain> --type convention "..."

--type pattern --name "..." --description "..."

mulch record <domain> --type convention "..."

--type guide --name "..." --description "..."

mulch record <domain> --type decision --title "..." --rationale "..."

mulch record <domain> --type decision --title "..." --rationale "..."

mulch record <domain> --type reference --name "..." --description "..."

--relates-to <domain>:<id>

--supersedes

mulch search "..."

CLAUDE.md

AGENTS.md

mulch onboard

mulch prime

Mulch Setup

Install (optional; npx works without install):

npm install -g mulch-cli
# or: npx mulch-cli <command>

Initialize in project:

mulch init
# Quick: add all preset domains at once
cat config/domains.json | jq -r '.domains[].name' | xargs -I {} mulch add {}
# Or add individually:
mulch add api
mulch add database
mulch add testing
# add domains that match your areas: frontend, backend, infra, docs, config

Provider hooks (remind agent to record):

mulch setup cursor   # or: claude, codex, gemini, windsurf, aider

Onboarding snippet for AGENTS.md/CLAUDE.md:

mulch onboard

Record Types (Mulch)

failure

convention

pattern

--file

decision

reference

guide

Optional on any record:

--classification

--tags

--relates-to

--supersedes

--evidence-commit

--evidence-file

--outcome-status

Workflow

1. Session start: If

   .mulch/

   exists, run

   mulch prime

   (or

   mulch prime <domain>

   for focus).
2. During work: When something fails or you learn something, run

   mulch record <domain> --type <type> ...

   .
3. Before finishing: Review; record any remaining insights with

   mulch record

   .
4. Promote: When a pattern is proven and broadly applicable, add to CLAUDE.md / AGENTS.md / SOUL.md / TOOLS.md; use

   mulch onboard

   to generate snippets.

Finding Domain

• Use existing domains from

  mulch status

  or

  mulch query --all

  .
• Run

  mulch learn

  to get domain suggestions from changed files.
• Common domains:

  api

  ,

  database

  ,

  testing

  ,

  frontend

  ,

  backend

  ,

  infra

  ,

  docs

  ,

  config

  .

Recurring Patterns and Linking

• Search first:

  mulch search "keyword"

  or

  mulch query <domain>

  .
• Link records:

  mulch record ... --relates-to <domain>:<id>

  or

  --supersedes <domain>:<id>

  .
• Recurring issues → promote to CLAUDE.md/AGENTS.md or add to TOOLS.md/SOUL.md so all agents see them.

Simplify & Harden Feed

For candidates from the simplify-and-harden skill:

1. Use

   pattern_key

   as a stable tag:

   mulch record <domain> --type pattern --name "<pattern_key>" --description "..." --tags "simplify-and-harden"

   .
2. Search first:

   mulch search "<pattern_key>"

   ; if found, use

   --relates-to

   or add to existing via

   mulch edit

   if needed.
3. When recurrence is high, promote to CLAUDE.md/AGENTS.md/SOUL.md/TOOLS.md as short prevention rules.

Periodic Review

• When: Before major tasks, after features, weekly.
• Commands:

  mulch status

  ,

  mulch ready --since 7d

  ,

  mulch query --all

  .
• Actions: Promote high-value records to project memory; run

  mulch prune

  for stale tactical/observational entries if desired;

  mulch doctor --fix

  for health.

Promotion Targets

SOUL.md

AGENTS.md

TOOLS.md

CLAUDE.md

.github/copilot-instructions.md

Use

mulch onboard

Detection Triggers

Record when you notice:

• User corrects you ("No, that's not right...", "Actually...") → convention or pattern
• Command/API/tool fails → failure (description + resolution)
• User wants missing capability → decision (title + rationale)
• Your knowledge was wrong or outdated → convention
• You found a better approach → convention or guide

OpenClaw Setup

OpenClaw injects workspace files; use Mulch for learnings.

Installation

clawdhub install self-improving-agent
# or: git clone ... ~/.openclaw/skills/self-improving-agent

Workspace and Mulch

• Session start: Run

  mulch prime

  when the project (or workspace) has

  .mulch/

  . Optionally add

  mulch prime

  output to workspace context if your setup supports it.
• Recording: Use

  mulch record

  from the project or workspace directory that contains

  .mulch/

  .
• Promotion: SOUL.md, AGENTS.md, TOOLS.md live in

  ~/.openclaw/workspace/

  ; add promoted rules there.

Enable Hook (reminder at bootstrap)

cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement
openclaw hooks enable self-improvement

See

references/openclaw-integration.md

Generic Setup (Other Agents)

1. In project:

   mulch init

   and

   mulch add <domain>

   as needed.
2. Use

   mulch setup <provider>

   (cursor, claude, codex, etc.) for hooks.
3. Add to CLAUDE.md/AGENTS.md: "Run mulch prime at session start. Record learnings with mulch record <domain> --type failure|convention|decision|pattern|guide|reference."
4. Run

   mulch onboard

   and paste the snippet into your agent docs.

Multi-Agent Safety

Mulch is safe for concurrent use: advisory file locking, atomic writes, and

merge=union

.gitattributes

mulch prime

mulch record

Skill Extraction

When a Mulch record is valuable as a reusable skill:

1. Get content from

   mulch query <domain>

   or

   mulch search "..."

   .
2. Create

   skills/<skill-name>/SKILL.md

   (template in

   assets/SKILL-TEMPLATE.md

   ).
3. Optionally note in the record (e.g. via

   mulch edit

   ) that it was promoted to a skill.

Best Practices

1. Record immediately — context is freshest after the issue.
2. Pick the right type — failure (description+resolution), convention (short rule), decision (title+rationale), etc.
3. Use domains consistently — e.g. same

   api

   domain for all API-related learnings.
4. Link related records —

   --relates-to

   ,

   --supersedes

   .
5. Run mulch prime at session start — so the agent is grounded in existing expertise.
6. Promote when proven — move broadly applicable rules to CLAUDE.md, AGENTS.md, SOUL.md, TOOLS.md.

No .learnings/

This skill does not use

.learnings/

.mulch/

.learnings/