The Agent Guild MCP
Guild keeps tasks, knowledge and handoff notes between sessions in local SQLite so Claude Code, Codex and Cursor share context
- 302 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Hooks are written into Claude Code and Codex settings and inject archive entries into prompts
- Agents write to and read from a shared knowledge base, and a wrong entry can affect later sessions
Install
- Works in
Manual install
brew install mathomhaus/tap/guildA build with semantic search for macOS and Linux.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Hooks are written into Claude Code and Codex settings and inject archive entries into prompts
- Agents write to and read from a shared knowledge base, and a wrong entry can affect later sessions
This is third-party code. Review the repository files before installing.
What it does
Guild is a single Go binary with a built-in MCP server and local SQLite. It addresses agent forgetfulness: after context compaction or a new session they lose what was done. Guild has four concepts. A quest is a task on a board with priority and dependencies. Lore is an archive entry, such as a decision or a research result. The oath is the project's principles, loaded at the start of every session. A brief is a handoff note for the next agent. At session start the agent makes one guild_session_start call and gets the principles, the last brief and the top quest. It then claims a quest, searches the archive with `guild lore appraise`, records findings and leaves a brief at the end. Clearing a quest unblocks those waiting on it. Search blends BM25 with vector similarity. State is shared by every client on the machine, so switching clients needs no migration. The `guild hooks install` command wires in Claude Code and Codex hooks, which load relevant entries on their own.
Who it is for. For developers who work on one project across several agents and want tasks, decisions and findings to survive sessions and editor switches.
Good fit when
- Several agents in different editors work on one repository and need a shared task board with claims so they do not take the same task
- After context compaction Claude Code forgets decisions, and a brief plus the archive should bring them back in the next session
- Research piles up in the project and the agent should check the archive with `guild lore appraise` before searching again
- You want tasks linked by dependencies so clearing one opens the next automatically
- You want project principles loaded into every session without pasting them into a prompt by hand
Not a fit when
- You work with one agent on a short task: the board and archive overhead will not pay off
- You need sync across machines or a team: state is kept only locally
- You want ongoing semantic understanding of code: Guild stores agent notes and does not index source files
Example request
Start a guild session for myapp, take the top priority quest and check the archive for similar findings before you workMCP
- Transport
- stdio
- Authentication
- not required
Limitations
- Prebuilt builds for macOS and Linux include semantic search, while the Windows build and `go install` give keyword-only BM25 search.
- The optional Ollama backend sends text to the configured Ollama endpoint. By default embeddings are computed on your machine.
- Hooks exist for Claude Code and Codex CLI. Codex has no compaction lifecycle, so Guild skips the pre-compaction capture for it.
- Vector search turns on once at least 90 percent of entries have embeddings. Until then keyword search is used.
How to disable. Run `guild hooks list`, remove the hooks, then delete the guild entry from the client's MCP configuration and the block in AGENTS.md. Data lives in ~/.guild, and you can delete that folder along with the binary.
FAQ
How do I install Guild and connect it to Claude Code?
Install the binary through `brew install mathomhaus/tap/guild` or the `install.sh` script from the release. Then run `guild init` in the project folder: it registers the project, adds a block to AGENTS.md and offers to connect Guild to the MCP clients it finds. After that ask the agent to start a guild session.
How do quest_journal, lore_inscribe and quest_brief differ?
The quest journal lives until the quest clears and serves the one working on it. An archive entry is for another agent on a different quest and lasts long. A brief fixes the outcome for the next session and loads together with the principles.
How do two agents avoid taking the same task?
A task is claimed atomically with `guild quest accept QUEST-42 --owner agent-a`. While it is held, another agent takes the next available one.
What do Guild hooks do and how do I install them?
The `guild hooks install` command writes SessionStart, PreCompact and UserPromptSubmit hooks for Claude Code and start and prompt hooks for Codex. They load the brief at start, save context before compaction and inject relevant entries as you type a prompt. `guild hooks diff` shows what a sync would change.
Where does Guild keep data and how do I run it in Docker?
Data sits in SQLite under ~/.guild. In a container mount /home/guild/.guild as a named volume, otherwise state disappears with the container: `docker run --rm -v guild-state:/home/guild/.guild guild:latest --version`.
Discussion
No questions or reviews yet.
Related
MCP serversA memory and coordination layer for coding agents: specs and issues live in git while agents work in parallel
A skill for messaging between Claude Code, Codex, Gemini CLI and other CLI agents through a shared local SQLite database, written in bash
Knowledge-graph memory for agents: Claude Code and Codex plugins, an MCP server and a Python library
Local persistent memory for coding agents: hooks record every session, and Claude Code, Codex or Cursor recall past decisions through 54 MCP tools
Long-term memory for agents: it distills knowledge from session history and brings it back in new tasks, one store shared across Claude Code, Codex, Cursor and
One local memory for Codex, Claude Code, Cursor, Hermes Agent and OpenClaw: agents hand off tasks, review each other and refine their skills overnight
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| The Agent Guild (this entry) | no | not required | 302 | |
| projectmem | yes | not required | 870 | local memory of coding agents about problems, attempts and fixes; Guild adds a task board with atomic claims and handoff notes between sessions |
| agent-memory | no | 4,374 | long-term memory in Markdown files with a SQLite index; Guild keeps principles, archive and tasks in one database |
README in short
The author explains shared agent memory through a guild metaphor and walks from install to the first session. A working session has three acts, and a separate mode returns JSON answers to agents.