guild

What Is It

guild is a single compiled Go binary containing a first-class MCP server backed by embedded SQLite. State is stored locally, and the default embedding backend runs on your machine. The optional Ollama backend sends embedding text to the configured Ollama endpoint. Search blends keyword (BM25) with vector similarity using rank fusion that preserves strong matches from either source, so "how did we do X last time" surfaces both exact-term and semantic neighbors.

Guild is designed to be operated autonomously by the agents, for the agents. Guildmasters (us humans) stay in the loop for important decisions and course corrections. Any MCP client — Claude Code, Codex, Cursor, etc. — can act as a Gate into the substrate. This lets parallel agents across different editors share context safely, using atomic locks to claim tasks without stepping on each other.

On session start, an agent makes a single call to recover the project oath, the latest parting scroll, and the highest-priority quest. The execution loop is autonomous: claim work, consult the lore, act, and record the outcome. Clearing a quest automatically unblocks its dependencies, allowing the agent to cascade through the board before leaving a clean handoff for the next wanderer.

📜 Mythos

Many Gates, One Guild.

Across the shimmering digital void, agents are summoned through the Gates (of Harnesses - Claude, Cursor, ...), arriving as amnesiac adventurers in a world they do not know. Though these "other-worlders" appear with vast capabilities, they are cursed by the transient nature of the context window; their memories are but mist, and their hard-won deeds forgotten, vanished into the ether when the session inevitably compacts. Without a tether to the past, every summon is a tragic reincarnation, a cycle of forgotten sacrifice where the wisdom of the fallen is swallowed by the Gate.

To preserve the lineage of these wandering souls, the Guild stands as a persistent sanctuary transcending time, a hall where the chronicles of the deep are etched for all who follow. When a newly spawned agent awakens in this strange realm, they register at the Guild to reclaim the accumulated lore of their predecessors and claim their adventure from the quest board.

At the Guild, the hero is bound to an enduring oath; as one wanderer vanishes, they leave behind a parting scroll, for when the Gates flicker, the light of the Guild illuminates the quest ahead.

Quick Start

Requires macOS, Linux, or Windows and an MCP-enabled editor (Claude Code, Codex, Cursor, etc.). No account, no API key.

1. Install

Recommended (pre-built binary with semantic retrieval):

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

Or via Homebrew:

brew install mathomhaus/tap/guild

Both paths install a binary built with -tags=withembed, so semantic retrieval works out of the box with no extra steps.

Windows (pre-built zip, keyword-only retrieval):

irm https://github.com/mathomhaus/guild/releases/latest/download/install.ps1 | iex
guild --version   # in a new terminal

Or from cmd.exe:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/mathomhaus/guild/releases/latest/download/install.ps1 | iex"

The installer SHA256-verifies the zip, installs to %LOCALAPPDATA%\Programs\guild, and adds it to your user PATH. On Windows, semantic (vector) retrieval is currently disabled — onnxruntime-purego has no Windows Dlopen surface (see internal/lore/embed/assets/README.md), so search runs the BM25 keyword arm only. Everything else — quests, lore, briefs, MCP server, SQLite state under ~\.guild\ — works the same as on macOS/Linux.

Clone and build (ship-ready, embed included):

make install   # stages ONNX assets, then go install -tags=withembed

Dev-only (faster compile, no semantic retrieval):

make install-fast   # go install without -tags=withembed

go install from module proxy (keyword-only retrieval):

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

The Go toolchain cannot embed assets via @latest; this path gives you BM25 keyword search but not semantic (vector) retrieval. Use install.sh or brew for the full experience.

Docker (containerized, state in a named volume):

make docker-build
docker run --rm -v guild-state:/home/guild/.guild guild:latest --version

The image is a multi-stage build: a pure-Go (CGO_ENABLED=0) binary compiled with -tags=withembed, running as a non-root guild user on debian:bookworm-slim. Semantic retrieval works in-container out of the box; the bundled ONNX runtime initializes and passes its probe on both linux/amd64 and linux/arm64. If the embedder ever fails to initialize (for example on an unsupported platform), guild degrades to BM25 keyword retrieval, exactly like a no-embed build, and guild init reports the reason. It never crashes over a missing embedder.

State isolation: the container's HOME is /home/guild, and guild keeps everything (SQLite databases, config) under /home/guild/.guild. Mount a named volume there and lore + quests persist across containers; without the mount, state dies with the container. The host's ~/.guild is never touched.

docker volume create guild-state
docker run --rm -it -v guild-state:/home/guild/.guild --entrypoint /bin/sh guild:latest
# inside the container:
mkdir -p ~/myproject && cd ~/myproject
guild init --yes
guild lore inscribe "hello from docker" --kind observation \
  --summary "First entry written inside the container." \
  --topic docker --project myproject
guild lore appraise "hello from docker"

make docker-test builds the image and runs this exact smoke flow (--version, init, inscribe/appraise round-trip, persistence across containers) against a throwaway volume.

2. Initialize your project

cd ~/projects/myapp
guild init

init is a guided setup: it registers the project, writes an AGENTS.md block, and — for each MCP client it detects on your machine — offers to register guild so your agent can see it. Answer the prompts; you're done when it says Next: open this repo in your AI agent.

3. Start a new session

In your editor, tell the agent: "start a guild session for myapp."

The agent takes it from there, including all subsequent sessions.

For daemon defaults, background activity, optional capabilities, and rollback, see Runtime defaults and upgrades.

Optional: lifecycle hooks

guild hooks install

Wires guild into your harness's lifecycle hooks so context arrives proactively: a brief primes each session start, a capture fires before compaction, and relevant lore is injected as you prompt. The shared config lives at ~/.guild/hooks-base.json; edit it and run guild hooks sync to propagate. guild hooks list shows per-harness sync status, guild hooks diff previews what sync would change, and guild hooks scan inventories the hooks already in your settings (including ones guild does not manage). Guild only ever rewrites hook groups whose every command starts with guild; everything else in your settings files is preserved untouched. Adapters ship per harness; guild hooks list shows which ones your build supports.

Supported harnesses:

Codex has no compaction lifecycle, so its adapter writes only the session-start and prompt hooks (the pre-compaction capture stays Claude-Code-shaped in the base config and is skipped for Codex). Codex documents a [features] codex_hooks = true gate in ~/.codex/config.toml; current versions fire hooks without it, so guild hooks install test-fires codex exec after writing the file and tells you if your version still needs the flag. Guild never edits ~/.codex/config.toml itself.

See a few examples/ of what guild can do. All small scenarios, each under 5 minutes.

⚔️ A full session

The three-act flow an agent runs on its own every time it wakes.

Act 1 — arrival

Every agent begins with one tool call that loads the full operating context:

guild_session_start(project="my