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           # コンパクトでトークン推定済みの記録を出力

コアコンセプト

コンセプト	説明
ドメイン	論理的なバケツ（例：`database`、`api`、`frontend`）。各ドメインは`.mulch/expertise/`配下の独自の`*.jsonl`ファイルに格納されます。
レコードタイプ	6つの組み込みタイプ – `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>`	2つのgitリファレンス間での専門知識の変更を表示。
`ml status / audit / doctor`	新鮮さ、ルール違反、全体的なコーパス品質を報告するヘルスチェックコマンド。
`ml prune / archive / restore`	古くなったまたは置き換えられたレコードをソフトアーカイブ。`--hard`でハード削除も可能。
`ml sync`	すべてのレコードを現在の設定と再検証し、コミット用にステージング。
`ml setup <provider>`	エージェントがMulchを自動的に呼び出せるようにするプロバイダ固有のフック（例：Claude、Cursor、Codex）をインストール。
`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 – ml primeのデフォルトをmanifest（高速インデックス）またはfullに選択。
スキーマ検証 – すべての書き込み時に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エージェントがセッション間、プロジェクト間、チームメート間で構造化された学びを永続化・再利用できるようにします。LLMプロンプト用に準備された形式で知識の記録、照会、エクスポートを可能にする豊富なCLIを提供し、ヘルスチェックと削除ツールでコーパスを整理整頓します。