jayminwest/mulch

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

1. 启动 – 代理运行 ml prime（或等效库命令）以获取当前代码变更集的相关上下文。
2. 工作 – 代理使用该上下文执行任务（代码生成、调试等）。
3. 反思 – 在完成前，代理调用 ml record … 以存储任何新惯例、失败、决策等。
4. 提交 – .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 提示，同时提供健康检查和清理工具以保持语料库整洁。