Mulch

Structured expertise management for AI agent workflows.

Agents start every session from zero. The pattern your agent discovered yesterday is forgotten today. Mulch fixes this: agents call ml record to write learnings, and ml 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.

Install

bun install -g @os-eco/mulch-cli

Or try without installing:

npx @os-eco/mulch-cli --help

Development

git clone https://github.com/jayminwest/mulch
cd mulch
bun install
bun link              # Makes 'ml' available globally

bun test              # Run all tests
bun run lint          # Biome check
bun run typecheck     # tsc --noEmit

Quick Start

ml init                                            # Create .mulch/ in your project
ml add database                                    # Add a domain
ml record database --type convention "Use WAL mode for SQLite"
ml record database --type failure \
  --description "VACUUM inside a transaction causes silent corruption" \
  --resolution "Always run VACUUM outside transaction boundaries"
ml query database                                  # See accumulated expertise
ml prime                                           # Get full context for agent injection
ml prime database                                  # Get context for one domain only

Commands

Every command supports --json for structured output. Global flags: -v/--version, -q/--quiet, --verbose, --timing. ANSI colors respect NO_COLOR.

| Command | Description | |---------|-------------| | ml init | Initialize .mulch/ in the current project | | ml add <domain> | Add a new expertise domain | | ml record <domain> --type <type> | Record an expertise record (--tags, --force, --relates-to, --supersedes, --batch, --stdin, --dry-run, --evidence-bead) | | ml edit <domain> <id> | Edit an existing record by ID or 1-based index | | ml delete <domain> [id] | Delete records by ID, --records <ids>, or --all-except <ids> (--dry-run) | | ml query [domain] | Query expertise (--all, --classification, --file, --outcome-status, --sort-by-score, --format filters) | | ml prime [domains...] | Output AI-optimized expertise context (--budget, --no-limit, --context, --files, --exclude-domain, --format, --export) | | ml search [query] | Search records across domains with BM25 ranking (--domain, --type, --tag, --classification, --file, --sort-by-score, --format) | | `ml compa...