mathomhaus/guild: Shared Memory and Quest Coordination for AI Coding Agents

The problem guild solves: amnesia between agent sessions

A coding agent that finishes a long session and compacts loses the reasoning it accumulated. The next session starts from the repository state, not from why the repository looks that way. guild's README frames this directly: agents are "cursed by the transient nature of the context window; their memories are but mist". The project's answer is to move that memory out of the context window and into a local store the agent can query on demand.

The second problem is coordination. Two agents in different editors working the same repository will duplicate work unless something arbitrates. guild provides a quest board where a claim is atomic, so two parallel sessions cannot accept the same item. The README describes parallel agents sharing context "using atomic locks to claim tasks without stepping on each other".

The intended user is a developer running more than one MCP-capable agent against the same codebase, or the same agent across many sessions. A solo developer with one editor and short sessions gets less from it, because the handoff problem only bites when sessions end and restart.

How the MCP server, SQLite store and hybrid search fit together

guild ships as one compiled Go binary that contains an MCP server. MCP clients connect to it as a tool provider; the README calls each client a "Gate". State lives in SQLite under the user's home directory, and the README states plainly that "nothing leaves your machine". There is no account and no API key.

The data model has three named pieces. An oath holds project principles and loads automatically. A parting scroll (also called a brief) is the handoff left by the previous session. Quests are the task board, with dependencies between them. The README says clearing a quest "automatically unblocks its dependencies", which is what lets an agent cascade through the board without a human reordering it.

Search is the part with real engineering behind it. Keyword matching uses BM25 and vector similarity runs alongside it, with the two result sets fused by reciprocal-rank fusion. The point of that fusion is that a query like "how did we do X last time" can surface both exact-term matches and semantically close entries that share no words. The go.mod lists modernc.org/sqlite, a pure-Go SQLite driver, and github.com/shota3506/onnxruntime-purego for embeddings, which is consistent with the Makefile's CGO_ENABLED=0 default and the static-binary claim.

Installing guild and starting a first session

The recommended path is the release installer, which fetches a prebuilt binary. The README notes both this path and Homebrew install a binary built with -tags=withembed, so semantic retrieval works without extra steps.

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

Alternatively, Homebrew users can install from the project's tap:

brew install mathomhaus/tap/guild

After installing, run the guided initialiser inside the repository you want the agents to share. According to the README, init registers the project, writes an AGENTS.md block, and offers to register guild with each MCP client it detects on the machine. You are done when it prints the next-step line.

cd ~/projects/myapp
guild init

Then open the repository in your editor and tell the agent to start a guild session. The README gives the phrasing "start a guild session for myapp." From that point the agent is expected to begin each session with a single call that returns the oath, the last brief and the top quest, then claim work, consult stored lore, act, and record the outcome. For a smaller first test, the repository ships examples/ with five scenarios, each described as under five minutes.

Windows and go install give you keyword search only

The clearest limitation is platform-dependent retrieval. On Windows, the README states that semantic (vector) retrieval is currently disabled because onnxruntime-purego has no Windows Dlopen surface, so search runs the BM25 arm alone. Quests, lore, briefs, the MCP server and the SQLite state under ~\.guild\ all work, but a query that depends on meaning rather than wording will not find its target. If your workflow leans on semantic recall, Windows is the wrong host today.

The same reduction applies to two build paths. Running go install github.com/mathomhaus/guild/cmd/guild@latest produces a keyword-only binary, because the Go toolchain cannot embed assets through @latest. make install-fast is also keyword-only, described as dev-only with faster compile. Only the installer, Homebrew, and make install stage the ONNX assets.

A third limit is that guild stores context, not truth. It has no mechanism described in the README for validating that a recorded finding is correct, so a wrong entry persists and gets retrieved by later sessions. The project also assumes an MCP client exists and is detected during init; an editor guild does not recognise simply will not be registered.

guild compared with a plain AGENTS.md or a hosted memory service

The nearest alternative is a hand-maintained AGENTS.md or CLAUDE.md file committed to the repository. That approach is transparent, reviewable in a pull request, and needs no binary. Its difference from guild is retrieval and concurrency: a markdown file is read whole or grepped, it has no ranked search across accumulated entries, and it offers no atomic claim that stops two agents from picking the same task. It also grows until it crowds the context window, which is the exact failure guild is built around.

The other alternative is a hosted agent-memory service with a remote API. Those usually add accounts, keys and network round trips, and they move your project's reasoning off the machine. guild's README is explicit that state stays local and that no account or API key is needed. The trade is that you own the SQLite file and its backups; there is no server-side durability story described in the README.

guild sits between the two: more machinery than a markdown file, less operational surface than a hosted service. The Apache-2.0 licence means you can read and modify the implementation, which matters if you want to understand how a claim is made atomic.

Maintenance, releases and what Apache-2.0 means here

The repository is not archived, and the last push was on 2026-09-14. The most recent release listed is v0.3.2 from 2026-05-27, alongside two model-v1.0.x releases on the same day. The gap between the last push and the last tagged release is worth noting: work is landing on main, but tagged versions are roughly four months behind that activity as of the release list. If you pin versions, expect to track main or build from source to get recent changes.

Upgrade cost is low by design. The binary is self-contained, so upgrading is replacing one executable; the README's install paths are all idempotent re-runs. The Makefile keeps ldflags in sync with .goreleaser.yml so that make install produces a binary whose --version output matches a release artifact, which makes it practical to reproduce a release build locally.

On licensing, Apache-2.0 permits commercial use and modification and includes an explicit patent grant. It also requires that you preserve notices and state significant changes when redistributing. This is a description of the licence text, not legal advice; check it against your own distribution plans.

Editorial conclusion

Adopt guild if you already run multiple MCP clients against the same repositories and want handoffs and task ownership to survive context compaction. Skip it if you work in a single editor session, if you need Windows semantic search, or if you expect a hosted service. Verify first that your client is registered by running guild init inside one repo and confirming the AGENTS.md block it writes, then check guild --version reports a withembed build before relying on vector retrieval.

Frequently asked questions

Official sources

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