Guild
Shared context, memory, and task coordination for AI coding agents across sessions and editors.
- Source repo
- mathomhaus/guild
- Stars
- ★ 302
- Last updated
- 3d ago
- License
- Apache-2.0
- Primary language
- Go
- FA score
- 50/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers who switch between Claude Code and Codex on the same repository and want the second session to pick up the previous brief and quest state.
- Not a fit if
- Teams needing semantic retrieval on Windows (BM25 keyword search only)
- Users who need zero outbound embedding text while enabling the Ollama backend
- Manual workflows with no MCP-capable editor
- Source review
- 50/100 · Major gaps
What does this agent do, and when should you use it?
Guild is a single compiled Go binary that ships a first-class MCP server backed by embedded SQLite, giving AI coding agents persistent shared context instead of amnesia between sessions. It models state with four primitives: Quests (tasks with priority, dependencies, touched files, and an atomic claim), Lore (typed knowledge entries — observation, decision, research, principle, idea — with per-kind auto-stale lifecycles), the Oath (the kind=principle subset auto-loaded at session start), and Briefs (handoff notes for the next session). Search fuses BM25 keyword ranking with vector cosine similarity; the default embedding backend runs locally, while the optional Ollama backend sends embedding text to the configured endpoint. Any MCP client — Claude Code, Codex, Cursor — can act as a gate into the same substrate, and clearing a quest cascade-unblocks whatever depended on it. State sits in SQLite under ~/.guild/, so switching clients needs no export or migration, and the CLI mirrors the MCP verbs with an --agent mode that emits one stable JSON envelope per invocation.
On session start an agent calls guild_session_start(project="myapp") once and receives the oath, the latest brief, and the top quest plus parallel-safe candidates. It claims work with guild quest accept QUEST-42 --owner agent-a, which is atomic so two agents cannot own the same quest. Before researching, it queries with guild lore appraise "token refresh" --all-projects, which combines BM25 with available fresh vectors and returns evidence candidates; findings are written via guild lore inscribe with a kind and topic, and per-quest reasoning goes to guild quest journal. At the end it writes guild quest brief for the next session and clears work with guild quest fulfill QUEST-42 --report, which cascades to unblock dependent quests. The same lore and quest verbs run from the shell: --agent, GUILD_AGENT=1, or auto-detected harness markers (CLAUDECODE, CODEX_SANDBOX, CURSOR_AGENT) switch output to a minimal append-only envelope with ok, command, output/error, and an optional hint, while exit codes stay zero on success. guild hooks install wires session-start briefs, pre-compaction capture, and prompt-time lore injection into <project>/.claude/settings.json or <repo>/.codex/hooks.json, rewriting only hook groups whose commands all begin with guild.
- Developers who switch between Claude Code and Codex on the same repository and want the second session to pick up the previous brief and quest state.
- Teams running parallel agent sessions that need to divide a task board without duplicate work, relying on the atomic quest claim.
- Long-lived projects that want research findings and decisions to accumulate as searchable Lore instead of vanishing at context compaction.
- Individual developers who want fully local SQLite state under ~/.guild/ with no account or API key.
- Agent harnesses that prefer shelling out to a CLI over MCP tool schemas, needing one predictable JSON envelope per call.
- Teams that want containerized state isolation by mounting a named volume at /home/guild/.guild.
How do you install or deploy this agent?
On macOS/Linux, install the pre-built binary with semantic retrieval:
curl -fsSL https://github.com/mathomhaus/guild/releases/latest/download/install.sh | sh
guild --versionOr via Homebrew:
brew install mathomhaus/tap/guildOn Windows, use the PowerShell installer (keyword-only retrieval):
irm https://github.com/mathomhaus/guild/releases/latest/download/install.ps1 | iex
guild --versionBuild from a clone to get embedded ONNX assets:
make installFaster dev build without semantic retrieval:
make install-fastVia the module proxy (BM25 only):
go install github.com/mathomhaus/guild/cmd/guild@latestDocker:
make docker-build
docker run --rm -v guild-state:/home/guild/.guild guild:latest --versionHow do you use this agent?
Initialize the project first; init registers it, writes an AGENTS.md block, and offers to register guild with each MCP client it detects:
cd ~/projects/myapp
guild initThen tell your editor's agent to start a guild session for the project. A typical agent loop:
guild quest accept QUEST-42 --owner agent-a
guild lore appraise "token refresh" --all-projects
guild lore inscribe "token refresh window" --kind observation --summary "tokens expire at 1h; refresh by 55m to avoid race" --topic auth
guild quest journal QUEST-42 "switched to exponential backoff after mock-clock test"
guild quest brief "shipped retry in commit abc1234; QUEST-43 ready to start"
guild quest fulfill QUEST-42 --report "done, shipped in abc1234"Optionally install lifecycle hooks so context arrives proactively:
guild hooks install
guild hooks list
guild hooks syncEnable structured agent output explicitly on any verb:
guild quest post "wire the cache layer" --agent
guild quest accept QUEST-99 --agentWhat are this agent's strengths and limitations?
- State is genuinely shared across sessions and clients: one SQLite store serves Claude Code, Codex, and Cursor with no export or migration step.
- Quest claims are atomic, so parallel agent sessions cannot collide on the same task.
- Retrieval fuses BM25 with vector cosine using rank fusion, preserving strong matches from either arm, and appraise enforces search-before-research.
- Install is one command via the release script or Homebrew, with no account or API key and a local default embedding backend.
- Agent mode offers a minimal append-only JSON envelope contract, useful for harnesses avoiding MCP tool-schema token overhead.
- Semantic retrieval is disabled on Windows because onnxruntime-purego has no Windows Dlopen surface; only BM25 runs there.
- Full semantic retrieval requires a -tags=withembed build; go install @latest cannot embed assets and yields keyword-only search.
- Enabling the optional Ollama backend sends embedding text to the configured endpoint, so data is no longer strictly local.
- Evidence is largely the README and demo GIFs; there are no third-party benchmarks for retrieval quality or coordination overhead.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Guild This agent | 50 · Major gaps | CLIFree | ★ 302 | 3d ago | Go | Codex · Claude Code |
| myc Local Agent Memory | 87 · Good | CLIFree | ★ 14 | 11d ago | TypeScript | Codex · Claude Code |
| Mnemo Cortex | 75 · Good | Self-hosted serviceFree | ★ 159 | 4d ago | Python | Codex · Claude Code · Claude.ai |
| Caura | 70 · Some gaps | Self-hosted serviceFreemium | ★ 541 | 1d ago | Python | Codex · Claude Code · Claude.ai |
How does FollowAgents rate this agent?
Why each dimension lost points
README states local-first operation, on-machine default embedding, and that optional Ollama sends embedding text to a configured endpoint, giving decent data-flow transparency (2). least_privilege scores 1: `guild hooks install` rewrites editor settings files and injects lifecycle hooks; it claims to only rewrite guild-prefixed command groups, but this is write access to user config with no explicit least-privilege constraint. user_confirmation scores 1: init is guided with prompts, but confirmation boundaries for hook installation and MCP client auto-registration are vague. sensitive_data_handling scores 1: SECURITY.md points to a README Privacy section that is absent from the evidence, so usage.log contents and opt-out cannot be verified. external_effects scores 1: writes to settings files, PATH, and ~/.guild state exist, with rollback only referenced via a link (docs/runtime-and-upgrades.md not provided). rollback scores 1: only a claim of rollback docs, no concrete mechanism. dependency_security scores 1: go.mod pins recent versions but there is no checksum verification, SBOM, or dependency audit evidence; onnxruntime-purego is a pseudo-version commit. source_attribution scores 2: LICENSE carries a copyright line and the model workflow emits a MANIFEST recording BAAI provenance and tool versions, but publisher identity is unverified.
README is internally consistent: install paths, retrieval degradation, and Windows limitations align (2). dependency_availability scores 1: requires the unusual Go 1.26.9 and an untagged pseudo-version of onnxruntime-purego, posing availability risk; no vendoring or checksum notes. failure_messages scores 2: agent mode defines an ok/error/hint envelope with exit codes, and embedder failure degrades with a reported reason, but no actual output samples are verified.
Targets coding agents across multiple MCP clients (Claude Code, Codex, Cursor) with concrete scenarios (2). capability_boundaries scores 2: clearly separates journal/lore/brief write surfaces and notes Windows lacks semantic retrieval and go install lacks embedding. trigger_precision scores 1: session start relies on the agent interpreting natural-language instructions, and hook triggering depends on environment-variable detection, so precision depends on external harness behavior with insufficient evidence. environment_fit scores 2: covers macOS/Linux/Windows/Docker, but Windows is feature-limited and the Go version requirement is strict, hence the deduction.
README is well-structured with clear sections pointing to docs/ and examples/ (2). install_notes scores 3: installation is thorough, covering curl, brew, PowerShell, make, go install, and Docker with trade-offs for each. naming_stability scores 1: heavy bespoke terminology (quest/lore/oath/brief/guildmaster), and the agent-mode envelope claims append-only but carries no version number, so stability evidence is weak. examples_and_faq scores 1: only links to an examples/ directory not shown in evidence, and no FAQ. known_limitations scores 2: explicitly lists Windows lacking semantic retrieval, go install limits, and Codex lacking compaction lifecycle. license scores 3: full Apache-2.0 text with copyright line. versioning_changelog scores 1: SECURITY.md says pre-1.0, no CHANGELOG, no versioning policy detail. maintenance_responsibility scores 1: publisher unverified, only SECURITY.md mentions response timelines, ownership unclear.
Agent mode emits a single JSON envelope with clear fields, easy for programs to consume (2). marginal_value scores 2: cross-agent shared context and atomic task claiming have real value, but many similar MCP memory solutions exist and differentiation evidence is limited. cost_benefit scores 1: requires an embedded ONNX runtime, ~127MB model download, and a specific Go version, so deployment cost is high while benefit is unquantified.
README claims CI badges, Docker tests, and retrieval evaluation docs, but evidence shows only workflow files, no test results or evaluation data (1). cross_source_corroboration scores 1: README partially aligns with SECURITY.md and go.mod, but the Privacy section is missing and examples/docs content is not provided, limiting corroboration. fact_inference_separation scores 1: docs blend factual description with mythic narrative, and performance/retrieval-quality claims lack supporting data, blurring fact and inference.
- `guild hooks install` rewrites editor settings files and injects hooks; review its write scope and rollback before installing.
- The README Privacy section referenced by SECURITY.md is absent from the evidence, so usage.log contents and opt-out cannot be verified.
- Depends on Go 1.26.9 and an untagged onnxruntime-purego pseudo-version, posing build reproducibility and dependency availability risks.
- Publisher identity is unverified; maintenance responsibility and update path are unclear.
- Semantic retrieval requires a ~127MB model download and is unsupported on Windows; assess deployment cost and platform differences.