mathomhaus/guild

The Agent Guild – Quick Overview

What it is – Guild is a single‑binary Go program that runs a local MCP (Multi‑Client Protocol) server backed by an embedded SQLite database. It stores shared context, memory, and a task board for AI‑coding agents (Claude Code, Codex, Cursor, etc.). Agents can claim quests, read/write “lore” entries, and hand off brief notes so that each new session picks up exactly where the last one left off.

Key features

• Hybrid retrieval – searches combine BM25 keyword matching with vector similarity (via an embedded ONNX embedder or an optional Ollama endpoint). This lets agents find exact‑term and semantic matches in the same query.
• Atomic quest claims – agents lock a quest before working on it, preventing two agents from stepping on each other.
• Persistent state – all data (quests, lore, oath, briefs) lives in a local SQLite file under ~/.guild/ (or a Docker volume). The state survives editor restarts, container restarts, and even switching between different MCP‑enabled editors.
• Agent‑mode CLI – when invoked from an AI agent, commands emit a single JSON envelope (--agent flag, GUILD_AGENT=1, or auto‑detect) so the agent can parse results without screen‑scraping.
• Lifecycle hooks – guild hooks install can write editor‑specific hook files (Claude Code, Codex) so context is automatically injected at session start and captured before compaction.

Typical workflow

1. Install – download a pre‑built binary (includes semantic retrieval) via the provided script, Homebrew, or Docker.
2. Initialize a project – guild init registers the repo, creates an AGENTS.md block, and registers the project with any detected MCP clients.
3. Start a session – the agent calls guild_session_start(project="myapp") and receives the project oath, the last brief, and the highest‑priority quest.
4. Work – the agent claims a quest (guild quest accept …), searches the lore (guild lore appraise …), inscribes new observations (guild lore inscribe …), and journals progress (guild quest journal …).
5. Finish – the agent writes a brief and fulfills the quest; dependent quests become available for the next agent.

Why it matters – Large‑language‑model coding assistants have tiny context windows and forget what they did after a session ends. Guild gives them a durable, searchable memory and a coordinated task board, enabling multiple agents (or the same agent across sessions) to collaborate without duplicating effort.

Installation highlights

• macOS/Linux: curl …/install.sh | sh (full semantic retrieval) or brew install mathomhaus/tap/guild.
• Windows: PowerShell installer (keyword‑only retrieval).
• Docker image includes the embedder and stores state in a named volume.

Extensibility – Developers can add new “campaigns” (task groupings) and contribute via the usual GitHub flow; the repo includes CONTRIBUTING.md, AGENTS.md, and docs on model embedding.

---

All details are taken directly from the repository’s README; no additional claims are made.