{"id":44537432,"url":"https://github.com/jayminwest/mulch","last_synced_at":"2026-03-04T03:02:56.985Z","repository":{"id":337526771,"uuid":"1154031882","full_name":"jayminwest/mulch","owner":"jayminwest","description":"Growing Expertise for Coding Agents — structured expertise files that accumulate over time, live in git, work with any agent","archived":false,"fork":false,"pushed_at":"2026-02-24T03:34:02.000Z","size":1412,"stargazers_count":73,"open_issues_count":0,"forks_count":11,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-24T09:47:10.752Z","etag":null,"topics":["ai-memory","ai-tools","claude-code"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jayminwest.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"jayminwest"}},"created_at":"2026-02-10T00:03:02.000Z","updated_at":"2026-02-24T03:34:06.000Z","dependencies_parsed_at":"2026-02-16T21:00:48.491Z","dependency_job_id":null,"html_url":"https://github.com/jayminwest/mulch","commit_stats":null,"previous_names":["jayminwest/mulch"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/jayminwest/mulch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayminwest%2Fmulch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayminwest%2Fmulch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayminwest%2Fmulch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayminwest%2Fmulch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jayminwest","download_url":"https://codeload.github.com/jayminwest/mulch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayminwest%2Fmulch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30070479,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T01:03:42.280Z","status":"online","status_checked_at":"2026-03-04T02:00:07.464Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-memory","ai-tools","claude-code"],"created_at":"2026-02-13T18:51:33.410Z","updated_at":"2026-03-04T03:02:56.973Z","avatar_url":"https://github.com/jayminwest.png","language":"TypeScript","funding_links":["https://github.com/sponsors/jayminwest"],"categories":[],"sub_categories":[],"readme":"# Mulch\n\nStructured expertise management for AI agent workflows.\n\n[![npm](https://img.shields.io/npm/v/@os-eco/mulch-cli)](https://www.npmjs.com/package/@os-eco/mulch-cli)\n[![CI](https://github.com/jayminwest/mulch/actions/workflows/ci.yml/badge.svg)](https://github.com/jayminwest/mulch/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nAgents 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.\n\n**Mulch is a passive layer.** It does not contain an LLM. Agents use Mulch — Mulch does not use agents.\n\n## Install\n\n```bash\nbun install -g @os-eco/mulch-cli\n```\n\nOr try without installing:\n\n```bash\nnpx @os-eco/mulch-cli --help\n```\n\n### Development\n\n```bash\ngit clone https://github.com/jayminwest/mulch\ncd mulch\nbun install\nbun link              # Makes 'ml' available globally\n\nbun test              # Run all tests\nbun run lint          # Biome check\nbun run typecheck     # tsc --noEmit\n```\n\n## Quick Start\n\n```bash\nml init                                            # Create .mulch/ in your project\nml add database                                    # Add a domain\nml record database --type convention \"Use WAL mode for SQLite\"\nml record database --type failure \\\n  --description \"VACUUM inside a transaction causes silent corruption\" \\\n  --resolution \"Always run VACUUM outside transaction boundaries\"\nml query database                                  # See accumulated expertise\nml prime                                           # Get full context for agent injection\nml prime database                                  # Get context for one domain only\n```\n\n## Commands\n\nEvery command supports `--json` for structured output. Global flags: `-v`/`--version`, `-q`/`--quiet`, `--verbose`, `--timing`. ANSI colors respect `NO_COLOR`.\n\n| Command | Description |\n|---------|-------------|\n| `ml init` | Initialize `.mulch/` in the current project |\n| `ml add \u003cdomain\u003e` | Add a new expertise domain |\n| `ml record \u003cdomain\u003e --type \u003ctype\u003e` | Record an expertise record (`--tags`, `--force`, `--relates-to`, `--supersedes`, `--batch`, `--stdin`, `--dry-run`, `--evidence-bead`) |\n| `ml edit \u003cdomain\u003e \u003cid\u003e` | Edit an existing record by ID or 1-based index |\n| `ml delete \u003cdomain\u003e [id]` | Delete records by ID, `--records \u003cids\u003e`, or `--all-except \u003cids\u003e` (`--dry-run`) |\n| `ml query [domain]` | Query expertise (`--all`, `--classification`, `--file`, `--outcome-status`, `--sort-by-score`, `--format` filters) |\n| `ml prime [domains...]` | Output AI-optimized expertise context (`--budget`, `--no-limit`, `--context`, `--files`, `--exclude-domain`, `--format`, `--export`) |\n| `ml search [query]` | Search records across domains with BM25 ranking (`--domain`, `--type`, `--tag`, `--classification`, `--file`, `--sort-by-score`, `--format`) |\n| `ml compact [domain]` | Analyze compaction candidates or apply a compaction (`--analyze`, `--auto`, `--apply`, `--dry-run`, `--min-group`, `--max-records`) |\n| `ml diff [ref]` | Show expertise changes between git refs (`ml diff HEAD~3`, `ml diff main..feature`) |\n| `ml status` | Show expertise freshness and counts (`--json` for health metrics) |\n| `ml validate` | Schema validation across all files |\n| `ml doctor` | Run health checks on expertise records (`--fix` to auto-fix) |\n| `ml setup [provider]` | Install provider-specific hooks (claude, cursor, codex, gemini, windsurf, aider) |\n| `ml onboard` | Generate AGENTS.md/CLAUDE.md snippet |\n| `ml prune` | Remove stale tactical/observational entries |\n| `ml ready` | Show recently added or updated records (`--since`, `--domain`, `--limit`) |\n| `ml sync` | Validate, stage, and commit `.mulch/` changes |\n| `ml outcome \u003cdomain\u003e \u003cid\u003e` | Append an outcome to a record (`--status`, `--duration`, `--agent`, `--notes`), or view outcomes |\n| `ml upgrade` | Upgrade mulch to the latest version (`--check` for dry run) |\n| `ml learn` | Show changed files and suggest domains for recording learnings |\n| `ml completions \u003cshell\u003e` | Output shell completion script (bash, zsh, fish) |\n\n## Architecture\n\nMulch stores expertise as typed JSONL records in `.mulch/expertise/\u003cdomain\u003e.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](CLAUDE.md) for full technical details.\n\n## How It Works\n\n```\n1. ml init               → Creates .mulch/ with domain JSONL files\n2. Agent reads expertise     → Grounded in everything the project has learned\n3. Agent does work           → Normal task execution\n4. Agent records insights    → Before finishing, writes learnings back to .mulch/\n5. git push                  → Teammates' agents get smarter too\n```\n\nThe critical insight: step 4 is **agent-driven**. Before completing a task, the agent reviews its work for insights worth preserving and calls `ml record`. Mulch provides the schema and file structure so those learnings land in a consistent, queryable format.\n\n## What's in `.mulch/`\n\n```\n.mulch/\n├── expertise/\n│   ├── database.jsonl        # All database knowledge\n│   ├── api.jsonl             # One JSONL file per domain\n│   └── testing.jsonl         # Each line is a typed, structured record\n└── mulch.config.yaml         # Config: domains, governance settings\n```\n\nEverything is git-tracked. Clone a repo and your agents immediately have the project's accumulated expertise.\n\n## Record Types\n\n| Type | Required Fields | Use Case |\n|------|----------------|----------|\n| `convention` | content | \"Use WAL mode for SQLite connections\" |\n| `pattern` | name, description | Named patterns with optional file references |\n| `failure` | description, resolution | What went wrong and how to avoid it |\n| `decision` | title, rationale | Architectural decisions and their reasoning |\n| `reference` | name, description | Key files, endpoints, or resources worth remembering |\n| `guide` | name, description | Step-by-step procedures for recurring tasks |\n\nAll records support optional `--classification` (foundational / tactical / observational), evidence flags (`--evidence-commit`, `--evidence-issue`, `--evidence-file`), `--tags`, `--relates-to`, `--supersedes` for linking, and `--outcome-status` (success/failure) for tracking application results. Cross-domain references use `domain:mx-hash` format (e.g., `--relates-to api:mx-abc123`).\n\n## Example Output\n\n```\n$ ml query database\n\n## database (6 entries, updated 2h ago)\n\n### Conventions\n- Use WAL mode for all SQLite connections\n- Migrations are sequential, never concurrent\n\n### Known Failures\n- VACUUM inside a transaction causes silent corruption\n  → Always run VACUUM outside transaction boundaries\n\n### Decisions\n- **SQLite over PostgreSQL**: Local-only product, no network dependency acceptable\n```\n\n## Design Principles\n\n- **Zero LLM dependency** — Mulch makes no LLM calls. Quality equals agent quality.\n- **Provider-agnostic** — Any agent with bash access can call the CLI.\n- **Git-native** — Everything lives in `.mulch/`, tracked in version control.\n- **Append-only JSONL** — Zero merge conflicts, trivial schema validation.\n- **Storage != Delivery** — JSONL on disk, optimized markdown/XML for agents.\n\n## Concurrency \u0026 Multi-Agent Safety\n\nMulch is designed for multi-agent workflows where several agents record expertise concurrently against the same repository.\n\n### How it works\n\n- **Advisory file locking** — Write commands acquire a `.lock` file (O_CREAT|O_EXCL) before modifying any JSONL file. Retries every 50ms for up to 5 seconds; stale locks (\u003e30s) are auto-removed.\n- **Atomic writes** — All JSONL mutations write to a temp file first, then atomically rename into place. A crash mid-write never corrupts the expertise file.\n- **Git merge strategy** — `ml init` sets `merge=union` in `.gitattributes` so parallel branches append-merge JSONL lines without conflicts.\n\n### Command safety\n\n| Safety level | Commands | Notes |\n|---|---|---|\n| **Fully safe** (read-only) | `prime`, `query`, `search`, `status`, `validate`, `learn`, `ready` | No file writes. Any number of agents, any time. |\n| **Safe** (locked writes) | `record`, `edit`, `delete`, `compact`, `prune`, `doctor` | Acquire per-file lock before writing. Multiple agents can target the same domain — the lock serializes access automatically. |\n| **Serialize** (setup ops) | `init`, `add`, `onboard`, `setup` | Modify config or external files (CLAUDE.md, git hooks). Run once during project setup, not during parallel agent work. |\n\n### Swarm patterns\n\n**Same-worktree agents** (e.g., Claude Code team, parallel CI jobs):\n\n```bash\n# Every agent can safely do this in parallel:\nml prime                                    # Read context\nml record api --type pattern --name \"...\" --description \"...\"  # Locked write\nml search \"error handling\"                  # Read-only\n```\n\nLocks ensure correctness automatically. If two agents record to the same domain at the same instant, one waits (up to 5s) for the other to finish.\n\n**Multi-worktree / branch-per-agent**:\n\nEach agent works in its own git worktree. On merge, `merge=union` combines all JSONL lines. Run `ml doctor --fix` after merge to deduplicate if needed.\n\n### Batch recording\n\nFor recording multiple records atomically (e.g., at session end), use `--batch` or `--stdin`:\n\n```bash\n# From a JSON file (single object or array of objects)\nml record api --batch records.json\n\n# From stdin\necho '[{\"type\":\"convention\",\"content\":\"Use UTC timestamps\"}]' | ml record api --stdin\n\n# Preview first\nml record api --batch records.json --dry-run\n```\n\nBatch recording uses file locking — safe for concurrent use. Invalid records are skipped with errors; valid records in the same batch still succeed.\n\n**Maintenance during swarm work**:\n\n```bash\nml compact --analyze          # Safe: read-only scan\nml prune --dry-run            # Safe: read-only scan\nml doctor                     # Safe: read-only health check\n```\n\nThe `--apply`, default (non-dry-run), and `--fix` variants acquire locks and are also safe to run alongside recording agents.\n\n### Edge cases\n\n- **Lock timeout**: If a lock cannot be acquired within 5 seconds, the command fails with an error. Retry or check for stuck processes.\n- **Stale locks**: Locks older than 30 seconds are automatically cleaned up (e.g., after a crash).\n- **`ml sync`**: Uses git's own locking for commits. Multiple agents syncing on the same branch will contend on git's ref lock — coordinate sync timing or use per-agent branches.\n- **`prime --export`**: Multiple agents exporting to the same file path will race. Use unique filenames per agent.\n\n## Programmatic API\n\nMulch exports both low-level utilities and a high-level programmatic API:\n\n```typescript\n// High-level API — recommended for most use cases\nimport {\n  recordExpertise,   // Record a new expertise entry (with dedup and locking)\n  searchExpertise,   // Search records across domains\n  queryDomain,       // Query all records for a domain\n  editRecord,        // Edit an existing record by ID\n  appendOutcome,     // Append an outcome to a record (with locking)\n} from \"@os-eco/mulch-cli\";\n\n// Scoring utilities\nimport {\n  computeConfirmationScore,\n  sortByConfirmationScore,\n  getSuccessRate,\n} from \"@os-eco/mulch-cli\";\n\n// Low-level utilities\nimport {\n  readConfig,\n  getExpertisePath,\n  readExpertiseFile,\n  searchRecords,\n  appendRecord,\n  writeExpertiseFile,\n  findDuplicate,\n  generateRecordId,\n  recordSchema,\n} from \"@os-eco/mulch-cli\";\n```\n\nTypes (`ExpertiseRecord`, `MulchConfig`, `RecordType`, `Classification`, `ScoredRecord`, `Outcome`, `RecordOptions`, `RecordResult`, `SearchOptions`, `SearchResult`, `QueryOptions`, `EditOptions`, `RecordUpdates`, `OutcomeOptions`, `AppendOutcomeResult`, etc.) are also exported.\n\n## Part of os-eco\n\nMulch is part of the [os-eco](https://github.com/jayminwest/os-eco) AI agent tooling ecosystem.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/jayminwest/os-eco/main/branding/logo.png\" alt=\"os-eco\" width=\"444\" /\u003e\n\u003c/p\u003e\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on setting up a development environment, coding conventions, and submitting pull requests.\n\nFor security issues, see [SECURITY.md](SECURITY.md).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjayminwest%2Fmulch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjayminwest%2Fmulch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjayminwest%2Fmulch/lists"}