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 to write learnings and mulch query to read them. Expertise compounds across sessions, domains, and teammates. Mulch is a passive layer — it does not contain an LLM. Agents use Mulch; Mulch does not use agents.

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/ (append-only JSONL, git-tracked, queryable). Session start: mulch prime. Recording: mulch record <domain> --type <type> .... No .learnings/ markdown files.

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

Situation	Action
Command/operation or API fails	`mulch record <domain> --type failure --description "..." --resolution "..."`
User corrects you / knowledge was wrong	`mulch record <domain> --type convention "..."` or `--type pattern --name "..." --description "..."`
Found better approach, best practice	`mulch record <domain> --type convention "..."` or `--type guide --name "..." --description "..."`
Architectural or tech decision	`mulch record <domain> --type decision --title "..." --rationale "..."`
Feature request (tracking)	`mulch record <domain> --type decision --title "..." --rationale "..."`
Key file/endpoint to remember	`mulch record <domain> --type reference --name "..." --description "..."`
Similar to existing record	Use `--relates-to <domain>:<id>` or `--supersedes`; run `mulch search "..."` first
Broadly applicable pattern	Promote to `CLAUDE.md`, `AGENTS.md`, SOUL.md, TOOLS.md; use `mulch onboard` for snippets
Session start (project has .mulch/)	Run `mulch prime` to load expertise into context

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)

Type	Required	Use Case
`failure`	description, resolution	What went wrong and how to avoid it
`convention`	content	"Use pnpm not npm"; "Always WAL mode for SQLite"
`pattern`	name, description	Named patterns, optional `--file`
`decision`	title, rationale	Architecture, tech choices, feature tracking
`reference`	name, description	Key files, endpoints, resources
`guide`	name, description	Step-by-step procedures

Optional on any record: --classification (foundational | tactical | observational), --tags, --relates-to, --supersedes, --evidence-commit, --evidence-file, --outcome-status (success | failure).

Workflow

Session start: If .mulch/ exists, run mulch prime (or mulch prime <domain> for focus).
During work: When something fails or you learn something, run mulch record <domain> --type <type> ....
Before finishing: Review; record any remaining insights with mulch record.
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:

Use pattern_key as a stable tag: mulch record <domain> --type pattern --name "<pattern_key>" --description "..." --tags "simplify-and-harden".
Search first: mulch search "<pattern_key>"; if found, use --relates-to or add to existing via mulch edit if needed.
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

Learning Type	Promote To
Behavioral patterns	`SOUL.md` (OpenClaw workspace)
Workflow improvements	`AGENTS.md`
Tool gotchas	`TOOLS.md` (OpenClaw workspace)
Project facts, conventions	`CLAUDE.md`
Copilot context	`.github/copilot-instructions.md`

Use mulch onboard to generate AGENTS.md/CLAUDE.md snippets.

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)

In project: mulch init and mulch add <domain> as needed.
Use mulch setup <provider> (cursor, claude, codex, etc.) for hooks.
Add to CLAUDE.md/AGENTS.md: "Run mulch prime at session start. Record learnings with mulch record --type failure|convention|decision|pattern|guide|reference."
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 in .gitattributes for JSONL. Multiple agents can run mulch prime and mulch record in parallel; locks serialize writes per domain.

Skill Extraction

When a Mulch record is valuable as a reusable skill:

Get content from mulch query <domain> or mulch search "...".
Create skills/<skill-name>/SKILL.md (template in assets/SKILL-TEMPLATE.md).
Optionally note in the record (e.g. via mulch edit) that it was promoted to a skill.

Best Practices

Record immediately — context is freshest after the issue.
Pick the right type — failure (description+resolution), convention (short rule), decision (title+rationale), etc.
Use domains consistently — e.g. same api domain for all API-related learnings.
Link related records — --relates-to, --supersedes.
Run mulch prime at session start — so the agent is grounded in existing expertise.
Promote when proven — move broadly applicable rules to CLAUDE.md, AGENTS.md, SOUL.md, TOOLS.md.

No .learnings/

This skill does not use .learnings/ or markdown log files. All learnings live in .mulch/ and are recorded via the Mulch CLI. If you see references to .learnings/ in older docs, treat them as superseded by Mulch.