jayminwest/mulch

Growing Expertise for Coding Agents — structured expertise files that accumulate over time, live in git, work with any agent

Mulch – AI代理工作流的結構化專業知識管理

是什麼 – Mulch 是一個輕量級的檔案式知識庫，讓 AI 代理能在會話中記錄所學內容，並在後續查詢累積的專業知識。它 不包含 LLM；僅提供一個持久化、版本控制的儲存空間（JSON-Lines 檔案），代理可讀可寫。

為何重要 – 在許多面向代理的專案中，代理每次執行都從空白開始，因此先前執行的洞見會遺失。Mulch 讓團隊能以結構化方式捕獲慣例、模式、失敗、決策、參考與指南，自動為特定任務劃定相關部分，並將所有內容納入 Git 管理，使團隊成員的代理能立即繼承集體智慧。

快速開始（CLI）

# 全域安裝（需要 Bun，但也可透過 npx 使用）
 bun install -g @os-eco/mulch-cli
 # 初始化專案
 ml init                     # 建立 .mulch/ 目錄
 # 新增一個領域（例如 "database"）
 ml add database
 # 記錄一個慣例
 ml record database --type convention "使用 SQLite 的 WAL 模式"
 # 記錄一個帶有描述與解決方案的失敗
 ml record database --type failure \
   --description "在交易內執行 VACUUM 會損壞資料庫" \
   --resolution "在交易外執行 VACUUM"
 # 查詢已有內容
 ml query database
 # 產生可注入 LLM 提示的上下文區塊
 ml prime database           # 輸出緊湊、已估算 token 數的記錄

核心概念

概念	描述
領域	語意分組（例如 `database`、`api`、`frontend`）。每個領域都儲存在 `.mulch/expertise/` 下的獨立 `*.jsonl` 檔案中。
記錄類型	六種內建類型 – `convention`、`pattern`、`failure`、`decision`、`reference`、`guide`。每種類型都有必填欄位（例如 `convention` 的 `content`）與可選元資料。
分類層級	`foundational`、`tactical`、`observational`。Mulch 使用這些層級決定保留期限與清理行為。
證據	將記錄與具體工件（`git commit`、`GitHub issue`、檔案路徑等）關聯，使 Mulch 能自動將記錄限定在代理正在處理的檔案範圍內。
自訂類型	專案可透過 `mulch.config.yaml` 擴展模式（例如 `hypothesis` 類型）。支援從內建類型繼承。
Prime	輸出 AI 就緒上下文的命令。預設情況下，它會自動根據目前 git 變更與任何證據標籤進行範圍限定，但您也可強制輸出完整資料、清單，或限制特定檔案/領域。

主要 CLI 命令（概覽）

命令	功能
`ml init`	在倉儲中初始化 `.mulch/` 資料夾。
`ml add <domain>`	建立新的領域檔案。
`ml record <domain> --type <type>`	寫入結構化記錄（支援標籤、證據、關係等）。
`ml edit / delete / move`	透過 ID 修改、刪除或移動現有記錄。
`ml query [domain]`	取得記錄，支援可選過濾器（類型、標籤、檔案、結果狀態）。
`ml prime [domains…]`	輸出適合 LLM 注入的精選專業知識區塊。支援 `--manifest`、`--full`、`--files`、`--budget`、`--json` 等。
`ml search <query>`	在領域間進行 BM25 風格的全文搜尋。
`ml rank`	按確認頻率得分對記錄排序（當沒有文字查詢時非常有用）。
`ml compact`	建議或應用記錄壓縮（合併相似記錄）。
`ml diff <ref>`	顯示兩個 git 引用之間的專業知識變化。
`ml status / audit / doctor`	健康檢查命令，報告新鮮度、規則違規與整體語料庫品質。
`ml prune / archive / restore`	軟性歸檔過時或被取代的記錄；使用 `--hard` 可硬刪除。
`ml sync`	根據目前設定重新驗證所有記錄，並將變更暫存以供提交。
`ml setup <provider>`	安裝特定提供者（如 Claude、Cursor、Codex）的鈎子，使代理能自動呼叫 Mulch。
`ml onboard`	產生用於新代理上手的程式碼片段（`AGENTS.md`、`CLAUDE.md`）。
`ml learn`	為新修改的檔案建議領域，幫助開發者捕捉新學習成果。

代理通常如何使用 Mulch

啟動 – 代理執行 ml prime（或等效庫命令）以取得目前程式碼變更集的相關上下文。
工作 – 代理使用該上下文執行任務（程式碼產生、除錯等）。
反思 – 在完成前，代理呼叫 ml record … 以儲存任何新慣例、失敗、決策等。
提交 – .mulch/ 檔案與程式碼一同提交，因此下一次執行（由同一代理或隊友代理）將從增強的知識庫開始。

設定亮點（`.mulch/mulch.config.yaml`）

domains – 定義每個領域的 allowed_types 和額外的 required_fields。
custom_types – 註冊專案特定的記錄模式，包含必填/可選欄位、去重鍵與摘要範本。
disabled_types – 優雅地棄用一個類型；寫入仍成功但會發出警告。
prime.default_mode – 選擇 manifest（快速索引）或 full 作為 ml prime 的預設值。
模式驗證 – 每次寫入時透過 AJV 強制執行；ml doctor 和 ml sync 會揭露任何違規。

典型用例

團隊級最佳實踐圖書館 – 儲存慣例（例如「所有 DB 連接必須使用連接池」），讓代理自動注入提示。
事後分析知識捕獲 – 記錄失敗及其解決方案，避免未來執行中重蹈覆轍。
架構決策日誌 – 保留決策及其理由，並連結到受影響的程式碼檔案。

安裝與開發

CLI – bun install -g @os-eco/mulch-cli 或 npx @os-eco/mulch-cli。
原始碼 – 克隆倉儲，執行 bun install，然後 bun link 以在本地公開 ml 命令。測試、lint 與類型檢查透過 bun test、bun run lint 和 bun run typecheck 提供。

TL;DR

Mulch 是一個 被動的、基於 Git 的知識儲存，讓 AI 代理能夠 持久化 並 跨會話、專案與團隊成員重複使用 結構化學習成果。它提供豐富的 CLI 用於記錄、查詢與匯出知識，格式已準備好用於 LLM 提示，同時提供健康檢查與清理工具以維持語料庫整潔。