Guild's semantic search is a build tag, and four of five installs skip it

Two release trains: the binary at 0.3.2 and a model at 1.0.3

The release history has two independent version lines, and that is unusual enough to notice on its own. Three releases are visible, all published on the same morning of 2026-05-27: guild 0.3.2, then guild model 1.0.3, then guild model 1.0.2 minutes earlier. So the tool is pre-1.0 and versioned on its own, while the embedding model that powers semantic retrieval has its own 1.0.x train, published separately and frequently enough to have produced two releases within minutes. The tree confirms the split with a dedicated .model-version file at the root, sitting alongside the ordinary changelog. That separation is the correct engineering choice, because you can upgrade a retrieval model without shipping a new binary, and it is also the thing that will confuse an adopter who assumes one version number covers the product. The last push to main was 2026-09-14, so both trains are a few months behind the working tree. The tool itself is under 1.0 and Apache-2.0 licensed, with the model licences a separate question the repository does not answer in the README.

Semantic retrieval is decided by a build tag, not by a setting

Here is the install matrix, and it is the thing to read carefully before you choose a path. The recommended route is a prebuilt installer.

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

Homebrew is the other recommended route.

brew install mathomhaus/tap/guild

Both of those install a binary built with the withembed tag, so semantic retrieval works with no extra steps. Now the other three. The Windows prebuilt zip installs and checks its checksum but is explicitly labelled keyword-only. A clone-and-build route stages the ONNX assets before installing.

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

A faster dev build skips the assets.

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

And the module proxy path is also keyword-only.

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

The reason given for that last one is precise rather than hand-waving: the Go toolchain cannot embed assets via the latest tag. So a third of the documented paths give you BM25 alone, with no vector arm, and nothing in the command output tells you which one you got. Check whether your search is hybrid before trusting a result you assumed was semantic.

Vector search is disabled on Windows for a specific library reason

The Windows situation is documented better than most projects document anything. The installer there is a PowerShell script that fetches a zip, verifies it by SHA256, installs to the local application programs directory for the current user, and adds it to the user PATH. What it does not give you is semantic retrieval. The stated cause is a library, not a policy decision: the pure-Go ONNX runtime has no Windows Dlopen surface, so the embedding assets cannot be loaded, and search falls back to running the BM25 keyword arm only. The README is careful to scope the damage, saying that everything else, meaning quests, lore, briefs, the MCP server and SQLite state under the user home directory, works the same as on macOS and Linux. It also points at a README inside the embed assets directory as the reference. The gap is narrower than it sounds for anyone whose corpus is full of exact identifiers, ticket numbers and error strings, which BM25 handles well, and wider for anyone asking the question the README uses as its motivating example about how something was done last time.

The SQLite layer is pure Go, which is what makes the binary static

The promise in the project description is a single compiled binary with local SQLite and nothing leaving the machine, and the dependency list shows how that promise is kept. The database driver is a pure-Go SQLite implementation rather than the C binding, which means no C toolchain is needed to build and no libc is needed at runtime. The module targets a recent Go release and depends on the official Model Context Protocol Go SDK, Cobra and pflag for the command line, a TOML parser, a JSON Schema library, and the pure-Go ONNX runtime pinned to a specific commit hash. The Makefile states the rule it follows: CGO_ENABLED is baked to zero to preserve the pure-Go static binary promise, with an explicit escape hatch for anyone who wants to experiment. Two other details there are worth borrowing. Build flags include trimpath, and the linker flags for version, commit and date are mirrored from the release configuration so a locally built binary reports the same version string as a published artefact.

guild init writes an AGENTS.md block and finds your MCP clients

Initialisation is guided rather than scripted, and that choice shows in what it touches. You run it inside the project directory, and it does three things: it registers the project, it writes a block into the project's AGENTS.md, and for every MCP client it detects on your machine it offers to register guild so an agent in that editor can see it. The prompts are answered interactively and the run finishes by printing a specific line telling you to open the repository in your AI agent. Detecting clients rather than making you name one is the useful part, because the whole premise is that several harnesses share one substrate, and the cost is that the setup is not reproducible from a script. Note the interaction with the repository's own agent instructions: guild writes into a file convention that the project itself uses at the root, alongside a separate file for the other harness. So the same convention the tool asks you to adopt is the one it uses on itself, which is at least consistent.

A session is one call, then claim, appraise, inscribe, journal

The session loop is specified tightly enough to copy. Arrival is a single tool call that takes the project name and returns three things: the project oath, which holds project principles and is auto-loaded, the last brief, which is the handoff from the previous session, and the top quest, together with parallel-safe candidates. The README stresses that this involves no back and forth, which is the point, since the alternative is an agent spending its context window asking what it is supposed to be doing. The middle phase is four verbs. Claim a quest with an owner named on the command line. Appraise the lore for a term across all projects before doing any research. Inscribe a finding with a kind, a summary and a topic. Journal reasoning onto the quest. The last phase is a brief plus a clear, and the clear cascades, so any quest that was only blocked on the finished one becomes available for whoever picks it up next.

The lore discipline is search before you research

One instruction in the documentation carries more weight than the rest: search before you research, so knowledge accretes instead of duplicating. The mechanism behind it is the appraise command, and the README is specific that it runs in hybrid mode, combining BM25 with vector retrieval fused by reciprocal-rank fusion, the moment your corpus is indexed. That last clause matters. Before indexing completes, appraise is not hybrid, so the first sessions of a fresh project get weaker recall than the README's headline describes, and nothing warns you about the transition. The three-act structure around it is the part that makes it stick: arrive with the oath, work with the lore, leave with a brief, and the next session starts already knowing what you were bound to. The examples directory makes the same point in miniature, with five scenarios named for hello world, quest decomposition, cross-project work, session handoff and lore-only use, each described as taking under five minutes.

Editorial conclusion

Guild fits a team running several coding agents across different editors on the same repository who keep losing context at session boundaries and want a durable, local record instead of another hosted service. It does not fit anyone on Windows who needs semantic recall, because that arm is unavailable there, and it does not fit anyone who installs through the Go module proxy expecting the documented hybrid search. Before you commit, decide which install path you are using and check whether it carries the embed tag, because the difference is BM25 only versus BM25 fused with vectors, and read the examples directory first, since five short scenarios will tell you in under half an hour whether the quest and lore model matches how your team actually works.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mathomhaus/guild on GitHub
3. Project website
4. README
5. Releases