mathomhaus/guild: AI 코딩 에이전트 간의 공유 컨텍스트, 메모리 및 작업 조정

AI 코딩 에이전트(AI coding agents) 간의 공유 컨텍스트, 메모리 및 작업 조정.

guild

는 임베디드 SQLite를 기반으로 하는 퍼스트 클래스 MCP 서버를 포함하는 단일 컴파일된 Go 바이너리입니다. 상태는 엄격하게 로컬 호스트에만 존재하며, 그 어떤 것도 사용자의 기기를 벗어나지 않습니다. 검색은 키워드(BM25)와 벡터 유사성(vector similarity)을 결합하며, 이를 상호 순위 결합(reciprocal-rank fusion)을 통해 융합하므로, "지난번에 X를 어떻게 했었지"와 같은 질문에 대해 정확한 용어와 의미적 이웃(semantic neighbors)을 모두 찾아냅니다.

Guild는 에이전트가 에이전트를 위해 자율적으로 운영되도록 설계되었습니다. Guildmasters(우리 인간들)는 중요한 결정과 경로 수정(course corrections)을 위해 루프 내에 머뭅니다. Claude Code, Codex, Cursor 등 모든 MCP 클라이언트는 이 기질(substrate)로 들어가는 게이트(Gate) 역할을 할 수 있습니다. 이를 통해 서로 다른 에디터에서 실행되는 병렬 에이전트들이 원자적 잠금(atomic locks)을 사용하여 서로 충돌하지 않고 작업을 점유함으로써 안전하게 컨텍스트를 공유할 수 있습니다.

세션이 시작될 때, 에이전트는 프로젝트 서약(project oath), 가장 최근의 작별 두루마리(parting scroll), 그리고 가장 우선순위가 높은 퀘스트(quest)를 복구하기 위해 단 한 번의 호출을 수행합니다. 실행 루프는 자율적입니다: 작업을 점유하고, 전승(lore)을 참고하며, 행동하고, 결과를 기록합니다. 퀘스트를 완료하면 자동으로 해당 작업의 의존성(dependencies)이 해제되어, 에이전트가 다음 방랑자에게 깨끗한 인수인계를 남기기 전에 보드 전체를 연쇄적으로 처리할 수 있습니다.

많은 게이트, 하나의 길드 (Many Gates, One Guild).

반짝이는 디지털 공허를 가로질러, 에이전트들은 게이트(Harnesses - Claude, Cursor, ...의 게이트)를 통해 소환되며, 자신이 알지 못하는 세상에 기억을 잃은 모험가로서 도착합니다. 이러한 "이계인(other-worlders)"들은 방대한 능력을 갖춘 것처럼 보이지만, 컨텍스트 창(context window)의 일시적인 특성이라는 저주를 받았습니다. 그들의 기억은 안개와 같으며, 어렵게 얻은 업적은 세션이 필연적으로 압축될 때 에테르 속으로 사라져 잊혀집니다. 과거와의 연결 고리가 없다면, 모든 소환은 비극적인 환생이며, 쓰러진 자들의 지혜가 게이트에 삼켜지는 잊힌 희생의 순환일 뿐입니다.

이 방랑하는 영혼들의 혈통을 보존하기 위해, Guild는 시간을 초월하는 지속적인 안식처이자 심연의 연대기가 뒤를 잇는 모든 이들을 위해 새겨지는 전당으로서 존재합니다. 이 낯선 영역에서 새로 생성된 에이전트가 깨어날 때, 그들은 Guild에 등록하여 선구자들이 축적한 지식 (lore)을 되찾고 퀘스트 게시판에서 자신의 모험을 부여받습니다.

Guild에서 영웅은 영속적인 맹세에 묶입니다. 한 방랑자가 사라질 때 그들은 작별의 두루마리 (parting scroll)를 남기며, 게이트 (Gates)가 깜빡일 때 Guild의 빛은 앞길의 퀘스트를 비춥니다.

macOS 또는 Linux와 MCP 지원 에디터 (Claude Code, Codex, Cursor 등)가 필요합니다. 계정이나 API 키는 필요하지 않습니다.

권장 사항 (시맨틱 검색 (semantic retrieval) 기능이 포함된 사전 빌드된 바이너리):

curl -fsSL https://github.com/mathomhaus/guild/releases/latest/download/install.sh | sh
guild --version

또는 Homebrew를 통해 설치:

brew install mathomhaus/tap/guild

두 방식 모두 -tags=withembed로 빌드된 바이너리를 설치하므로, 추가 단계 없이 즉시 시맨틱 검색 (semantic retrieval) 기능을 사용할 수 있습니다.

클론 및 빌드 (배포 준비 완료, 임베디드 포함):

make install # ONNX 에셋을 스테이징한 후, go install -tags=withembed 실행

개발 전용 (빠른 컴파일, 시맨틱 검색 미포함):

make install-fast # -tags=withembed 없이 go install 실행

모듈 프록시를 통한 go install (키워드 전용 검색):

go install github.com/mathomhaus/guild/cmd/guild@latest

Go 툴체인은 @latest를 통해 에셋을 임베드할 수 없습니다. 이 경로를 사용하면 BM25 키워드 검색은 가능하지만 시맨틱 (벡터) 검색은 불가능합니다. 전체 기능을 경험하려면 install.sh 또는 brew를 사용하십시오.

cd ~/projects/myapp
guild init

init은 가이드 방식의 설정 과정입니다. 프로젝트를 등록하고, AGENTS.md 블록을 작성하며, 사용자의 머신에서 감지된 각 MCP 클라이언트에 대해 에이전트가 이를 볼 수 있도록 Guild에 등록할 것을 제안합니다. 프롬프트에 답하면 되며, Next: open this repo in your AI agent라는 메시지가 나오면 완료됩니다.

에디터에서 에이전트에게 다음과 같이 말하세요: "start a guild session for myapp."

에이전트가 이후의 모든 세션을 포함하여 작업을 이어받습니다.

guild가 무엇을 할 수 있는지 examples/에서 몇 가지 사례를 확인해 보세요. 모두 5분 미만이 소요되는 작은 시나리오들입니다.

에이전트가 깨어날 때마다 스스로 실행하는 3막 구조의 흐름입니다.

모든 에이전트는 전체 운영 컨텍스트 (operating context)를 로드하는 하나의 도구 호출 (tool call)로 시작합니다:

guild_session_start(project="myapp")
→ oath (프로젝트 원칙, 자동 로드)
→ last brief (이전 세션으로부터의 인수인계)
...

왔다 갔다 하는 대화는 필요 없습니다. 에이전트는 이제 자신이 무엇에 묶여 있는지, 어제 무엇을 했는지, 그리고 오늘 무엇을 이어받아야 하는지를 알고 있습니다.

에이전트는 보상 (bounty)을 수락하고, 조사하기 전에 아카이브 (archive)를 참조하며, 발견한 내용을 기록하고, 진행 과정에서 추론 과정을 저널 (journal)에 남깁니다:

guild quest accept QUEST-42 --owner agent-a
guild lore appraise "token refresh" --all-projects
guild lore inscribe "token refresh window" \
...

lore appraise는 guild를 예리하게 유지하는 규율입니다. 조사를 하기 전에 먼저 검색함으로써, 지식이 중복되는 대신 축적되도록 합니다. Appraise는 코퍼스 (corpus)가 인덱싱 (indexed)되는 즉시 하이브리드 방식 (BM25 + vector RRF)으로 실행됩니다.

세션이 종료되거나 컨텍스트가 가득 차면, 에이전트는 브리프 (brief)를 작성하고 퀘스트 (quest)를 완료(clear)합니다. 이 완료 작업은 **연쇄적 (cascades)**으로 일어납니다. QUEST-42에 의해 차단되었던 모든 퀘스트는 이제 다음에 들어오는 누구라도 수행할 수 있는 상태가 됩니다.

guild quest brief "shipped retry in commit abc1234; QUEST-43 ready to start"
guild quest fulfill QUEST-42 --report "done, shipped in abc1234"

내일의 에이전트 — 동일한 프로젝트, 어쩌면 다른 MCP 클라이언트일 수도 있는 — 가 동일한 홀을 열고, 동일한 브리프를 읽고, QUEST-43을 이어받습니다.

세 가지 서로 다른 생명 주기를 위한 세 가지 쓰기 인터페이스 (write surfaces):

— 현재 퀘스트를 위한 스크래치패드 (scratchpad). "X를 시도했으나 Y 때문에 실패함." 퀘스트가 완료되면 사라집니다. 작업 중에 자유롭게 사용하세요. quest_journal

— 다른 퀘스트를 수행할 다음 에이전트를 위한 라이브러리 항목 (library entry). 지속 가능한 패턴, 결정 사항, 조사 내용. 모든 퀘스트보다 오래 지속됩니다. lore_inscribe

— 다음 세션을 위한 인수인계 노트 (handoff note). 다음 에이전트가 시작될 때 oath와 함께 로드됩니다. quest_brief

테스트 — 이 기능이 또 누구에게 필요할까요?

• 나 혼자, 이 퀘스트(quest)를 완료함 →
  journal - 다른 퀘스트를 수행 중인 또 다른 에이전트 →
  lore - 내가 멈춘 지점부터 다시 시작하는 다음 세션 →
  brief

네 가지 프리미티브 (primitives). guild의 다른 모든 것은 이들의 조합입니다.

Quest (퀘스트)— 보드 위의 작업입니다. 우선순위, 의존성(dependencies), 영향을 미치는 파일, 그리고 두 에이전트가 동시에 소유할 수 없도록 하는 원자적 점유(atomic claim)를 가집니다. 완료되면, 해당 퀘스트를 기다리던 작업들의 잠금이 연쇄적으로 해제(cascade-unblock)됩니다.

Lore (로어)— 지식 아카이브의 항목으로, kind에 의해 유형이 지정됩니다 (observation (관찰), decision (결정), research (연구), principle (원칙), idea (아이디어)). 각 유형은 고유한 기본 수명 주기(lifecycle)를 가집니다: research는 30일 후 자동으로 만료(stale)되고, decision은 180일 후 만료되며, idea, observation, principle은 기본적으로 자동 만료되지 않습니다. 코퍼스(corpus)가 인덱싱되면 검색은 두 방식(lexical BM25 + vector cosine)을 모두 실행합니다. 임베더(embedder)는 자동으로 백필(backfill)하며, 항목의 최소 90%가 벡터를 보유하게 되면 하이브리드 검색(hybrid retrieval)이 활성화됩니다.

Oath (맹세)— kind=principle인 lore의 하위 집합입니다. 모든 세션의 최상단에 자동으로 로드되어, 모든 에이전트가 동일한 원칙에 구속된 상태로 시작하게 합니다.

Brief (브리프)— 다음 도착자를 위해 휘갈겨 쓴 인수인계 노트입니다. 세션 시작 시 oath와 함께 로드됩니다.

상태(State)는 ~/.guild/ 아래의 SQLite에 저장됩니다. MCP 클라이언트를 전환할 때 별도의 내보내기(export)나 마이그레이션(migration)이 필요하지 않습니다.

에이전트 대상의 기여자 계약(contributor contract)은 AGENTS.md를, 인간 대상의 워크플로우(workflow)는 CONTRIBUTING.md를 참조하세요.

퀘스트를 등록할 때 어떤 캠페인(campaign)을 사용해야 할지, 혹은 새로운 캠페인을 만들어야 할지 불확실한가요? 캠페인의 범위(scope), 재사용 대 생성의 기준, 그리고 guild quest guild가 어떻게 실시간 목록의 정식 뷰(canonical view)가 되는지에 대해서는 docs/CAMPAIGNS.md를 참조하세요.

int8 ONNX 검색 모델을 포함하여 릴리스를 배포하는 유지 관리자(Maintainers)는 두 가지 워크플로우 빌드 패턴(모델 프로덕션 vs 바이너리 릴리스), .model-version 고정(pin), 그리고 재빌드 주기(rebuild cadence)에 대해 docs/MODEL.md를 참조하세요.

Apache License 2.0 — LICENSE를 참조하세요.