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.
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.
Installation
npm install -g mulch-cli
# or: npx mulch-cli <command>
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 "..." |
| Key file/endpoint to remember | mulch record <domain> --type reference --name "..." --description "..." |
| Session start (project has .mulch/) | Run mulch prime to load expertise into context |
Setup
mulch init
# Quick: add all preset domains at once
mulch add api
mulch add database
mulch add testing
# add domains that match your areas: frontend, backend, infra, docs, config
Record Types
| Type | Required | Use Case |
|---|---|---|
failure |
description, resolution | What went wrong and how to avoid it |
convention |
content | Short rules and best practices |
pattern |
name, description | Named patterns |
decision |
title, rationale | Architecture, tech choices |
reference |
name, description | Key files, endpoints, resources |
guide |
name, description | Step-by-step procedures |
Workflow
- Session start: If
.mulch/exists, runmulch prime - During work: When something fails or you learn something, run
mulch record - Before finishing: Review; record any remaining insights
- Promote: When a pattern is proven, add to project memory files
Promotion Targets
| Learning Type | Promote To |
|---|---|
| Behavioral patterns | SOUL.md |
| Workflow improvements | AGENTS.md |
| Tool gotchas | TOOLS.md |
| Project facts, conventions | CLAUDE.md |
Periodic Review
- When: Before major tasks, after features, weekly
- Commands:
mulch status,mulch ready --since 7d,mulch query --all - Actions: Promote high-value records; prune stale entries