Mulch

Mulch Usage

Mulch captures project learnings as structured "records" organized by domain. Each domain represents a category of knowledge:

When to Run Commands

1. At Session Start

Load all project expertise into your context:

mulch prime                    # load all project learnings
mulch prime --files src/foo.ts # load only records relevant to specific files

This gives you awareness of existing patterns, decisions, and conventions before you start working.

2. While Working

Record insights as you discover them:

# Create a new domain if needed
mulch add purpose

# Record different types of learnings
mulch record <domain> --type pattern --name "Auth Pattern" --description "Use middleware for auth checks before route handlers"
mulch record <domain> --type failure --name "Missing Validation" --description "Form field not validated on client" --resolution "Add Zod schema validation"
mulch record <domain> --type decision --title "Chose PostgreSQL" --rationale "Needed relational queries and ACID compliance"
mulch record <domain> --type convention --content "API routes go in src/routes/"
mulch record <domain> --type reference --name "Error Handling" --description "See docs/error patterns"
mulch record <domain> --type guide --name "Setup Guide" --description "Run npm install then npm run dev"

# Add evidence, files, tags
mulch record <domain> --type pattern --name "..." --description "..." --evidence-commit abc123
mulch record <domain> --type pattern --name "..." --description "..." --evidence-bead fix-42   # link to bd issue
mulch record <domain> --type pattern --name "..." --description "..." --files "src/auth.ts,src/middleware.ts"
mulch record <domain> --type pattern --name "..." --description "..." --tags "security,auth"

# Link related records
mulch record <domain> --type pattern --name "..." --description "..." --relates-to mx-abc123
mulch record <domain> --type pattern --name "..." --description "..." --supersedes mx-old123

# Batch record from JSON file
mulch record <domain> --batch records.json
mulch record <domain> --batch records.json --dry-run  # preview first

3. Before Finishing Your Task

After all file editing is done (but before committing), run mulch learn to see what changed and get recording suggestions:

mulch learn
mulch learn --since HEAD~3  # diff against specific commit

This shows which files were modified and can suggest what to record based on your changes.

Then record any learnings and sync to git:

mulch record <domain> ...  # record learnings from this session
mulch sync                  # validates, stages, and commits .mulch/ changes

Note: mulch sync runs mulch validate automatically before committing, so you don't need a separate validate step.

Querying & Searching

Tip: --json is a global flag that works with all commands below.

# Check domain status
mulch status --json
mulch status --json | jq '.'

# Query records in a domain
mulch query <domain> --json
mulch query <domain> --type failure --json  # filter by type

# Search across all domains
mulch search "auth" --json
mulch search "auth" --type pattern --json      # filter by type
mulch search "auth" --tag security --json      # filter by tag
mulch search "auth" --domain <domain> --json   # limit to domain

# Show recent additions
mulch ready --json

# Show changes since git ref
mulch diff --json
mulch diff --since v1.0.0 --json

Other Useful Commands

# Edit a record
mulch edit <domain> mx-abc123 --description "Updated description"

# Delete a record
mulch delete <domain> mx-abc123

# Compact similar records
mulch compact <domain> --analyze
mulch compact <domain> --apply --type pattern --name "Auth Patterns" --description "Combined from 5 records"

# Generate onboarding snippet for AGENTS.md
mulch onboard
mulch onboard --check  # verify it's installed

# Health check
mulch doctor  # check for issues with --fix option

# Check for updates
mulch update

JSON Output

All commands support --json for scripting:

mulch status --json | jq '.'
mulch query <domain> --json | jq '.[] | select(.type == "failure")'
mulch search "auth" --json | jq '.[] | .name'