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
ml prime --files src/foo.ts                        # Prime only records relevant to specific files
ml prime --manifest                                # Domain index for monoliths (scope-load on demand)
ml prime --full --all                              # Skip auto-context-scope and emit every record

For large monoliths where dumping every record wastes context, set prime.default_mode: manifest in .mulch/mulch.config.yaml — ml prime then emits a quick reference + domain index, and agents scope-load with ml prime <domain> or ml prime --files <path>.

In full mode, ml prime auto-context-scopes to the agent's working set by default: git status for changed/untracked files, plus the active-work resolver chain (current branch, in-progress seeds, current GH PR, branch-parsed linear/bead IDs) matched against each record's evidence.{seeds,gh,linear,bead}. Universal records (no files / dir_anchors / tracker-anchored evidence) are always emitted. The stderr line prime: scoped to N of M records based on …; run with --all for the full corpus reports the scoping ratio so the agent sees what got dropped. Pass --all to opt out and emit the full corpus; pass an explicit --files, positional domain, --domain, or --context to scope on different signals. Auto-scope is skipped under --json (machine consumers expect deterministic output) and outside a git repo.

Commands

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

Global Output Format

All record-rendering commands (ml prime, ml query, ml search) accept a global --format <markdown|compact|xml|plain> flag that selects the output formatter. xml is Claude-optimized; plain is the spawn-injection contract — clean structured prose (per-domain sections, bulleted records, no decorative title, no Session Close trailer) suitable for concatenation into another tool's system prompt; compact emits one-liner records (default for ml prime); markdown emits the full, sectioned layout. Per-command --format flags (e.g. ml query --format ids) take precedence over the global flag.

ml --format xml prime testing      # XML expertise tree (Claude-friendly)
ml --format plain prime testing    # plain text for system-prompt injection
ml --format compact query testing  # compact one-liners
ml prime --full                    # alias for --format markdown
ml prime --compact                 # alias for --format compact

Spawn-time Preview (--dry-run)

ml prime --dry-run emits a JSON summary of which records would be primed (id, type, domain, per-record token estimate) and how the result fits within --budget, without rendering record content. Useful for editor previews and orchestrators that want to show "would prime: N records, K tokens" before actually shelling out for the full output. Composes with --domain, --files, --budget, --no-limit, --exclude-domain. pre-prime hooks are skipped (preview must not trigger Slack posts or digest-then-confirm confirmations). When combined with --format plain the format is ignored and JSON is returned.

ml prime --dry-run                            # preview default prime
ml prime --dry-run --domain cli --budget 8000 # scoped preview against a specific budget
ml prime --dry-run --files src/foo.ts         # what would prime --files emit?

{
  "wouldPrime": [
    { "id": "mx-94901b", "type": "convention", "domain": "cli", "tokens": 240 }
  ],
  "totalTokens": 240,
  "budgetUsed": 0.03,
  "budgetTotal": 8000
}

budgetUsed and budgetTotal are null when invoked with --no-limit.

Architecture

Mulch stores expertise as typed JSONL records in .mulch/expertise/<domain>.jsonl — one file per domain, one record per line. Six record types (convention, pattern, failure, decision, reference, guide) with three classification tiers (foundational, tactical, observational) govern shelf life and pruning. Advisory file locks and atomic writes ensure safe concurrent access from multiple agents. Schema validation (via Ajv) enforces type-specific required fields. See CLAUDE.md for full technical details.

How It Works

1. ml init               → Creates .mulch/ with domain JSONL files
2. Agent reads expertise