Mulch addresses the challenge of AI agents forgetting learned information between sessions by providing a structured, Git-native expertise management system. It enables AI agents to record, query, and compound knowledge over time, benefiting developers building persistent and collaborative agent workflows.

How It Works

Mulch acts as a passive layer, storing expertise as typed JSONL records within a project's .mulch/expertise/ directory, organized by domain. Agents interact via a CLI (ml record, ml query, ml prime) to persist learnings and retrieve context. This Git-tracked approach ensures expertise compounds across sessions, developers, and projects without requiring LLM retraining, offering a passive, knowledge-enhancing infrastructure.

Quick Start & Requirements

• Primary install / run command: Global CLI via bun install -g @os-eco/mulch-cli or use npx @os-eco/mulch-cli.
• Non-default prerequisites and dependencies: bash, bun.
• Basic Usage: Initialize with ml init, add domains with ml add, record insights via ml record, and query expertise with ml query or ml prime.

Highlighted Details

• Structured Expertise: Six built-in record types (convention, pattern, failure, etc.) with three classification tiers (foundational, tactical, observational) for nuanced knowledge management.
• Extensibility: Supports custom record types defined in mulch.config.yaml, including inheritance from built-in types.
• Contextual Anchoring: Records can be linked to specific files or directories for precise context retrieval.
• Concurrency Safe: Employs advisory file locking and atomic writes for safe concurrent access by multiple agents, leveraging Git's merge=union for JSONL files.
• Lifecycle Hooks: Customizable shell scripts can intercept key events (pre-record, pre-prime) for custom logic like secret scanning or context filtering.
• Provider Integration: Extensible system for integrating with agent providers (e.g., Claude, Cursor) via filesystem or npm recipes.
• Programmatic API: Offers a TypeScript API for direct integration into agent code.

Maintenance & Community

Mulch is part of the os-eco ecosystem. Contribution guidelines are available via CONTRIBUTING.md and SECURITY.md. Specific community channels or notable contributors are not detailed in the provided documentation.

Licensing & Compatibility

• License type: MIT.
• Compatibility notes: The permissive MIT license allows for commercial use and integration into closed-source projects.

Limitations & Caveats

Lock acquisition timeouts (5 seconds) can cause command failures. ml doctor requires manual intervention for violations; automated fixing is not available in v1. Custom type inheritance is limited to extending built-in types in v1. Concurrent Git commits require coordination or per-agent branches due to Git's ref locking. Lifecycle hooks do not execute during --dry-run operations.