by mathomhaus
Shared context, memory, and task coordination across AI coding agents. Single Go binary, local SQLite, hybrid keyword and semantic search.
# Add to your Claude Code skills
git clone https://github.com/mathomhaus/guildShared context, memory, and task coordination across AI coding agents.
guild is a single compiled Go binary containing a first-class MCP server backed by embedded SQLite. State lives strictly on local host; nothing leaves your machine. Search blends keyword (BM25) with vector similarity, fused via reciprocal-rank fusion, 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.
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.
No comments yet. Be the first to share your thoughts!
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.
Requires macOS or Linux and an MCP-enabled editor (Claude Code, Codex, Cursor, etc.). No account, no API key.
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.
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.
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.
In your editor, tell the agent: "start a guild session for myapp."
The agent takes it from there, including all subsequent sessions.
See a few examples/ of what guild can do. All small scenarios, each under 5 minutes.
The three-act flow an agent runs on its own every time it wakes.
Every agent begins with one tool call that loads the full operating context:
guild_session_start(project="myapp")
→ oath (project principles, auto-loaded)
→ last brief (handoff from the previous session)
→ top quest (+ parallel-safe candidates)
No back-and-forth. The agent now knows what it's bound to, what was done yesterday, and what to pick up today.
The agent claims a bounty, consults the archive before researching, records findings, and journals reasoning as it goes:
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"
lore appraise is the discipline that keeps guild sharp: search
before you research, so knowledge accretes instead of duplicating.
Appraise runs hybrid (BM25 + vector RRF) the moment your corpus is
indexed.
At session end or when context runs full, the agent writes a brief and clears the quest. The clear cascades: any quest that was only blocked on QUEST-42 is now available for whoever walks in next.
guild quest brief "shipped retry in commit abc1234; QUEST-43 ready to start"
guild quest fulfill QUEST-42 --report "done, shipped in abc1234"
Tomorrow's agent — same project, maybe a different MCP client — opens the same hall, reads the same brief, picks up QUEST-43.
Three write surfaces for three different lifetimes:
quest_journal — scratchpad for THIS quest. "Tried X, failed
because Y." Dies when the quest clears. Use freely during work.lore_inscribe — library entry for the next agent on a
DIFFERENT quest. Durable patterns, decisions, research. Outlasts
every quest.quest_brief — handoff note for the next SESSION. Loaded
alongside the oath when the next agent starts.The test — who else needs this?
Four primitives. Everything else in guild is a composition of these.
kind
(observation, decision, research, principle, idea). Each
kind has its own default lifecycle: research auto-stales after 30
days, decisions after 180 days, and ideas, observations, and
principles do not auto-stale by default. Search runs both arms
(lexical BM25 + vector cosine) once the corpus is indexed. The
embedder backfills automatically; hybrid retrieval activates once
at least 90% of entries have vectors.kind=principle. Auto-loaded
at the top of every session so every agent starts bound by the
same principles.State lives in SQLite under ~/.guild/. Switching MCP clients requires no export, no migration.
See AGENTS.md for the agent-facing contributor contract and CONTRIBUTING.md for the human-facing workflow.
Filing a quest and unsure which campaign to use, or whether to invent
a new one? See docs/CAMPAIGNS.md for how
campaigns are scoped, when to reuse vs create, and how guild quest guild is the canonical view of the live list.
Maintainers shipping releases that embed the int8 ONNX retrieval
model: see docs/MODEL.md for the two-workflow build
pattern (model production vs binary release), the .model-version
pin, and the rebuild cadence.
Apache License 2.0 — see LICENSE.