repository·main·Indexed 43 days ago
https://github.com/jayminwest/mulchA structured expertise management system for AI agent workflows that allows agents to record, query, and prime themselves with accumulated project knowledge. Mulch stores expertise as typed JSONL records in git-trackable files, enabling learnings to compound across sessions and teammates. It includes a CLI (@os-eco/mulch-cli) for managing domains, recording insights (such as conventions, failures, and decisions), and generating AI-optimized context via the `ml prime` command.
The aliases field in a custom_types definition allows you to map canonical field names to legacy names. When Mulch reads a record containing a legacy field name, it automatically rewrites it to the canonical name. This enables seamless schema evolution without requiring manual migration scripts.
custom_types:
incident:
extends: failure
required: [severity, pager_link]
aliases:
pager_link: [pagerduty_url, page_url] # Accepts legacy names on readMulch uses a soft-archive mechanism to manage record decay. Archived records are moved to .mulch/archive/<domain>.jsonl and include a # ARCHIVED banner, a status: "archived" field, and an archived_at timestamp.
To reverse an archival, use the following command:
ml restore <id>Records in Mulch have a freshness_score that determines their relevance. As a record ages or receives challenges, its score drops. When the score falls below a threshold, the record is flagged for archiving.
Decay Logic:
Score is calculated based on: (confirmations_in_window × type_weight) + recency_bonus − (challenges × challenge_weight) − staleness_penalty.
Decay Rates by Type:
failure, decision, reference: Decay slowly (high importance).convention, pattern: Decay normally.note: Decays fastest (intended for short-lived scratch).guide: Barely decays (long-form documentation).Cleanup Operations:
ml prime --maybe-prune: Performs a cadence-based cleanup (using a .mulch/.last-prune stamp file) to archive stale records.ml doctor: Flags records that are candidates for archiving.ml restore: Recovers any records that were auto-archived.--hard flag is explicitly used.Configuration:
prime.auto_prune: Set to weekly or off to control the automatic cleanup cadence.Every record in Mulch, regardless of its type, contains a set of standard fields. While many are managed automatically by Mulch (like id, recorded_at, and status), others are provided by the user during the ml record command.
type: The registered type (e.g., convention, decision).classification: The trust tier: foundational, tactical, or observational. Defaults to tactical.tags: A list of searchable strings.relates_to: A list of mx-ids for related records.supersedes: A list of mx-ids this record replaces (triggers decay on ml prune).owner: An opaque string for organizational use.id: A stable, human-readable ID stem combined with a date.status: The lifecycle state: draft, active, deprecated, or archived.evidence: An object containing metadata like commit, date, issue, file, etc. Git information often auto-populates this.Mulch stores expertise as typed JSONL records in the .mulch/ directory. This structure ensures that expertise is git-trackable and easily shared across teams.
Directory Structure:
.mulch/expertise/<domain>.jsonl: One file per domain containing typed, structured records (one per line)..mulch/mulch.config.yaml: Configuration for domains and governance settings.Record Model:
convention, pattern, failure, decision, reference, guide.foundational, tactical, observational (these govern shelf life and pruning).Mulch supports an ownership model to resolve conflicts and manage stale records. Ownership is resolved using the following priority chain:
--owner @handle flag provided during record creation.CODEOWNERS file based on the record's file_anchors.default_owner specified per-domain in mulch.config.yaml.You can use ml review to list records owned by your current user that require attention.
# List records owned by the current user that need review
ml reviewMulch is designed for environments where multiple agents might access the expertise store simultaneously. It employs several safety mechanisms:
O_CREAT|O_EXCL lock files with a 50ms retry interval and a 5s timeout. Stale locks are detected after 30s. Write commands (record, edit, delete, compact, prune, doctor --fix) all utilize this locking.merge=union strategy in .gitattributes to ensure that during git conflicts, all unique lines from both sides are preserved, preventing loss of expertise.prime, query, search, status, and validate do not require locking and can run concurrently without interference.Mulch is designed for multi-agent workflows where several agents record expertise concurrently. It ensures data integrity through three primary mechanisms:
.lock file before modifying JSONL files. It retries every 50ms for up to 5 seconds. Stale locks (>30s) are automatically removed.ml init configures .gitattributes with merge=union, allowing parallel branches to append-merge JSONL lines without conflicts.| Safety level | Commands | Notes |
|---|---|---|
| Fully safe (read-only) | prime, query, search, rank, status, validate, learn, ready | No file writes. Safe for any number of agents at any time. |
| Safe (locked writes) | record, edit, delete, delete-domain, compact, prune, archive, restore, doctor | Acquires per-file locks. Multiple agents can target the same domain; locks serialize access. |
| Serialize (setup ops) | init, add, onboard, setup | Modifies config or external files. Run once during setup, not during parallel agent work. |
Mulch uses a specific directory structure within your repository to manage configuration, records, and recipes. Understanding these paths is critical for manual maintenance and automation.
| Path | Purpose | Written by | Read by |
|---|---|---|---|
.mulch/mulch.config.yaml | Configuration | you / ml init | every command |
.mulch/expertise/<domain>.jsonl | Live records | ml record, ml edit, ml compact, ml restore, ml doctor --fix | ml prime, ml search, ml query, ml rank, ml status, ml validate, ml learn, ml ready, ml sync |
.mulch/archive/<domain>.jsonl | Soft-archived records | ml prune | ml search --archived, ml restore |
.mulch/recipes/<name>.ts | TypeScript provider recipe | you | ml setup, ml setup --list |
.mulch/recipes/<name>.sh | Shell provider recipe | you | ml setup, ml setup --list |
.mulch/hooks/*.sh | Lifecycle hook scripts | you | ml record, ml prime, ml prune |
.mulch/README.md | Auto-generated layout doc | ml init | humans |
.gitattributes | merge=union rules | you | git |
Mulch enforces strict schemas for 6 specific record types using Ajv. When creating records, ensure you include the required fields:
| Type | Required Fields | Optional Fields |
|---|---|---|
convention | content | - |
pattern | name, description | files |
failure | description, resolution | - |
decision | title, rationale | - |
reference | name, description | files |
guide | name, description | - |
Classifications & Shelf Life: Records are categorized to manage their lifecycle:
foundational: Permanent records.tactical: Automatically pruned after 14 days.observational: Automatically pruned after 30 days.Linking & Metadata:
--evidence-commit or --evidence-bead flags when recording.relates_to and supersedes (string arrays) to connect records.status, duration, test_results, and agent.You can anchor records to specific locations in your repository to ensure they are surfaced during context-aware operations like ml prime --files <path> or ml prime --context.
files[]: A list of repo-relative file paths. Use this when a record is about specific files or lines. It is auto-populated from the current git context if omitted. Note that records using files[] are invalidated if the file is renamed or moved.dir_anchors[]: A list of repo-relative directory paths. Use this when wisdom applies to a whole module or folder. This is more resilient to file churn within the directory. You can set this explicitly using --dir-anchor <path> (repeatable).Matching Logic: A record matches a file path if the path is explicitly listed in files[] OR if any entry in dir_anchors[] is an ancestor of that path.