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을 실행하면 DB가 손상됨" \
   --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>`	두 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 명령어 노출. 테스트, 린팅, 타입 체크는 각각 bun test, bun run lint, bun run typecheck로 제공.

TL;DR

Mulch는 수동적이고 Git 기반의 지식 저장소로, AI 에이전트가 세션 간, 프로젝트 간, 팀원 간에 구조화된 학습을 지속하고 재사용할 수 있도록 합니다. LLM 프롬프트에 적합한 형식으로 지식을 기록, 조회, 내보내는 풍부한 CLI를 제공하며, 헬스 체크 및 정리 도구를 통해 코퍼스를 깔끔하게 유지합니다.