mathomhaus/guild: AI Agent Shared Context and Coordination

This project provides a centralized, local-first system for AI coding agents to share context, memory, and coordinate tasks. It enables parallel agents across different editors to collaborate safely, ensuring knowledge persistence and efficient task management, benefiting both autonomous agent operation and human oversight.

How It Works

Guild is a single Go binary acting as an MCP server, backed by local SQLite storage. It fuses keyword (BM25) and semantic vector search via reciprocal-rank fusion (RRF) for robust context retrieval. Agents, acting as "Gates" (e.g., Claude Code, Cursor), interact with the Guild substrate. The core loop involves agents atomically claiming tasks ("Quests"), consulting the persistent knowledge archive ("Lore"), performing actions, and journaling outcomes. State transcends individual agent sessions, with "Oaths" (principles) and "Briefs" (handoff notes) ensuring continuity.

Quick Start & Requirements

Requires macOS or Linux and an MCP-enabled editor (e.g., Claude Code, Cursor). No API keys needed.

• Install (Recommended): Use the pre-built binary with semantic retrieval:

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

  Alternatively, install via Homebrew: brew install mathomhaus/tap/guild.
• Initialize Project: Navigate to your project directory and run guild init. This registers the project and configures detected MCP clients.
• Start Session: Instruct your AI agent in the editor: "start a guild session for ".
• Resources: See examples/ for small scenarios.

Highlighted Details

• Hybrid keyword (BM25) and vector similarity search with RRF.
• All state stored locally in SQLite (~/.guild/); no data leaves the machine.
• Atomic task claiming prevents collisions between parallel agents.
• Quest dependency cascading automatically unblocks subsequent tasks.
• Lore entries have configurable, auto-expiring lifecycles (research, decisions).

Maintenance & Community

Contribution workflows are detailed in AGENTS.md (agent-facing) and CONTRIBUTING.md (human-facing). Model build patterns and release cadences are documented in docs/MODEL.md. No explicit community channels (e.g., Discord/Slack) are listed.

Licensing & Compatibility

Licensed under the Apache License 2.0. This license is permissive for commercial use and integration into closed-source projects.

Limitations & Caveats

Strictly supports macOS and Linux. Requires integration with specific MCP-enabled editors. Installing via go install omits semantic retrieval capabilities. Semantic search requires specific build configurations or pre-built binaries.