mathomhaus/guild

Shared context, memory, and task coordination across AI coding agents. Single Go binary, local SQLite, hybrid keyword and semantic search.

에이전트 길드 (The Agent Guild) – 개요

개요 – Guild 는 내장 SQLite 데이터베이스를 백엔드로 사용하는 로컬 MCP (Multi-Client Protocol) 서버를 실행하는 단일 바이너리 Go 프로그램입니다. AI 코딩 에이전트(Claude Code, Codex, Cursor 등)를 위한 공유 컨텍스트, 메모리, 작업 보드를 저장합니다. 에이전트는 퀘스트를 점유하고, "지식(lore)" 항목을 읽고 쓰며, 짧은 메모를 남겨 새로운 세션이 이전 세션의 종료 지점에서 정확히 작업을 재개할 수 있도록 합니다.

주요 기능

하이브리드 검색 – BM25 키워드 매칭과 벡터 유사성(내장 ONNX 임베더 또는 선택적 Ollama 엔드포인트 경유)을 결합한 검색입니다. 이를 통해 에이전트는 정확한 용어 검색과 의미론적 매칭을 동일한 쿼리에서 수행할 수 있습니다.
원자적 퀘스트 점유 – 에이전트는 작업 전에 퀘스트를 잠가 여러 에이전트가 서로 충돌하는 것을 방지합니다.
지속적 상태 – 모든 데이터(퀘스트, 지식, 서약, 요약)는 ~/.guild/ 아래의 로컬 SQLite 파일(또는 Docker 볼륨)에 저장됩니다. 에디터 재시작, 컨테이너 재시작, 심지어 MCP 지원 에디터 간 전환 시에도 상태가 유지됩니다.
에이전트 모드 CLI – AI 에이전트에서 호출될 때, 명령어는 단일 JSON 엔벨로프(--agent 플래그, GUILD_AGENT=1 또는 자동 감지)를 출력하므로 에이전트는 화면 스크래핑 없이 결과를 파싱할 수 있습니다.
라이프사이클 훅 – guild hooks install을 사용하여 에디터별 훅 파일(Claude Code, Codex)을 작성함으로써 세션 시작 시 컨텍스트를 자동으로 주입하고 압축 전에 캡처할 수 있습니다.

일반적인 워크플로우

설치 – 제공된 스크립트, Homebrew 또는 Docker를 사용하여 빌드된 바이너리(의미론적 검색 포함)를 다운로드합니다.
프로젝트 초기화 – guild init으로 저장소를 등록하고 AGENTS.md 블록을 생성하며, 감지된 MCP 클라이언트에 프로젝트를 등록합니다.
세션 시작 – 에이전트가 guild_session_start(project="myapp")를 호출하여 프로젝트 서약, 마지막 요약, 최우선 퀘스트를 받습니다.
작업 – 에이전트가 퀘스트를 점유(guild quest accept …)하고, 지식을 검색(guild lore appraise …)하며, 새로운 관찰 내용을 기록(guild lore inscribe …)하고, 진행 상황을 기록(guild quest journal …)합니다.
완료 – 에이전트가 요약을 작성하고 퀘스트를 완료합니다. 의존적인 퀘스트는 다음 에이전트가 사용할 수 있게 됩니다.

중요성 – 대규모 언어 모델 코딩 어시스턴트는 컨텍스트 윈도우가 작아 세션 종료 후 작업 내용을 잊어버립니다. Guild는 지속적이고 검색 가능한 메모리와 조정된 작업 보드를 제공하여 여러 에이전트(또는 동일 에이전트의 세션 간)가 중복 작업 없이 협업할 수 있도록 합니다.

설치 하이라이트

macOS/Linux: curl …/install.sh | sh(전체 의미론적 검색) 또는 brew install mathomhaus/tap/guild.
Windows: PowerShell 설치 프로그램(키워드 검색 전용).
Docker 이미지에는 임베더가 포함되어 있으며 상태는 명명된 볼륨에 저장됩니다.

확장성 – 개발자는 새로운 "캠페인"(작업 그룹화)을 추가하고 일반적인 GitHub 흐름을 통해 기여할 수 있습니다. 저장소에는 CONTRIBUTING.md, AGENTS.md 및 모델 임베딩 관련 문서가 포함되어 있습니다.

모든 세부 정보는 저장소의 README에서 직접 가져왔으며, 추가적인 주장은 하지 않습니다.