jayminwest/mulch

Mulch – Structured expertise management for AI‑agent workflows

What it is – Mulch is a lightweight, file‑based knowledge base that lets AI agents record what they learn during a session and query that accumulated expertise later. It does not contain an LLM; it simply provides a persistent, version‑controlled store (JSON‑Lines files) that agents can read from and write to.

Why it matters – In many agent‑oriented projects the agent starts each run with a blank slate, so insights from previous runs are lost. Mulch lets teams capture conventions, patterns, failures, decisions, references and guides in a structured way, automatically scopes the relevant bits for a given task, and keeps everything under Git so teammates’ agents instantly inherit the collective wisdom.

---

Quick start (CLI)

# Install globally (requires Bun, but works via npx too)
 bun install -g @os-eco/mulch-cli
 # Initialise a project
 ml init                     # creates .mulch/ directory
 # Add a domain (e.g. "database")
 ml add database
 # Record a convention
 ml record database --type convention "Use WAL mode for SQLite"
 # Record a failure with description and resolution
 ml record database --type failure \
   --description "VACUUM inside a transaction corrupts the DB" \
   --resolution "Run VACUUM outside transactions"
 # Query what you have
 ml query database
 # Produce a context block that can be injected into an LLM prompt
 ml prime database           # emits compact, token‑estimated records

---

Core concepts

Concept	Description
Domain	A logical bucket (e.g. database, api, frontend). Each domain lives in its own *.jsonl file under .mulch/expertise/.
Record types	Six built‑in types – convention, pattern, failure, decision, reference, guide. Each has required fields (e.g. content for a convention) and optional metadata.
Classification tiers	foundational, tactical, observational. Used by Mulch to decide shelf‑life and pruning behaviour.
Evidence	Links a record to concrete artefacts (git commit, GitHub issue, file paths, etc.) so Mulch can auto‑scope records to the files an agent is touching.
Custom types	Projects can extend the schema via mulch.config.yaml (e.g. a hypothesis type). Inheritance from built‑ins is supported.
Prime	The command that emits AI‑ready context. By default it auto‑scopes to the current git changes and any evidence tags, but you can force a full dump, a manifest, or limit to specific files/domains.

---

Main CLI commands (high‑level view)

Command	What it does
ml init	Bootstraps a .mulch/ folder in the repo.
ml add <domain>	Creates a new domain file.
ml record <domain> --type <type>	Writes a structured record (supports tags, evidence, relationships, etc.).
ml edit / delete / move	Mutate existing records by ID.
ml query [domain]	Retrieve records with optional filters (type, tag, file, outcome status).
ml prime [domains…]	Output a curated block of expertise for LLM injection. Supports --manifest, --full, --files, --budget, --json, etc.
ml search <query>	BM25‑style full‑text search across domains.
ml rank	Rank records by confirmation‑frequency score (useful when you have no text query).
ml compact	Suggest or apply record compaction (grouping similar records).
ml diff <ref>	Show how expertise changed between two git refs.
ml status / audit / doctor	Health‑check commands that report freshness, rule violations, and overall corpus quality.
ml prune / archive / restore	Soft‑archive stale or superseded records; can be hard‑deleted with --hard.
ml sync	Re‑validate all records against the current config and stage changes for commit.
ml setup <provider>	Install provider‑specific hooks (e.g. Claude, Cursor, Codex) that let agents call Mulch automatically.
ml onboard	Generates snippets (AGENTS.md, CLAUDE.md) for onboarding new agents.
ml learn	Suggests domains for newly changed files, helping developers capture fresh learnings.

---

How an agent typically uses Mulch

1. Start – Agent runs ml prime (or the library equivalent) to fetch the relevant context for the current code change set.
2. Work – Agent performs its task (code generation, debugging, etc.) using that context.
3. Reflect – Before finishing, the agent calls ml record … to store any new convention, failure, decision, etc.
4. Commit – The .mulch/ files are committed alongside the code, so the next run (by the same or a teammate’s agent) starts with the enriched knowledge base.

---

Configuration highlights (.mulch/mulch.config.yaml)

• domains – Define per‑domain allowed_types and extra required_fields.
• custom_types – Register project‑specific record schemas, including required/optional fields, dedup keys and summary templates.
• disabled_types – Gracefully deprecate a type; writes still succeed with a warning.
• prime.default_mode – Choose manifest (quick index) vs. full as the default for ml prime.
• Schema validation – Enforced via AJV on every write; ml doctor and ml sync surface any violations.

---

Typical use‑cases

• Team‑wide best‑practice library – Store conventions (e.g., “All DB connections must use a connection pool”) that agents automatically inject into prompts.
• Post‑mortem knowledge capture – Record failures and their resolutions so future runs avoid the same pitfall.
• Architecture decision log – Keep decisions with rationale and link them to the code files they affect.\n---

Installation & development

• CLI – bun install -g @os-eco/mulch-cli or npx @os-eco/mulch-cli.
• Source – Clone the repo, run bun install, then bun link to expose the ml command locally. Tests, linting and type‑checking are provided via bun test, bun run lint and bun run typecheck.

---

TL;DR

Mulch is a passive, git‑backed knowledge store that lets AI agents persist and reuse structured learnings across sessions, projects and teammates. It provides a rich CLI for recording, querying, and exporting that knowledge in formats ready for LLM prompts, while offering health‑check and pruning tools to keep the corpus tidy.