{"id":"280c751c-d01c-4106-b2d6-1e94dcf42a37","slug":"relayagents-relay","kind":"mcp","name":"relay","summary":"Shared memory and switchboard for teams whose members each run their own AI agents. Meetings → decisions and action items, team knowledge graph, MCP tool surface, A2A broker with human oversight.","owner":"relayagents","repoUrl":"https://github.com/relayagents/relay","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-09-04T02:08:42.000Z","addedAt":"2026-10-21T09:39:04.518Z","logoUrl":"https://avatars.githubusercontent.com/u/324711607?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","communication"],"tags":["a2a","agents","fastapi","knowledge-graph","meetings","team-memory"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T17:45:10.183Z","sample":false,"url":"https://conduits.dev/tools/relayagents-relay","language":"Python","transports":["stdio"],"install":{"pypi":"relayagents"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Relay\n\n**Relay connects your coding agent to your team's meetings and chat.** A meeting becomes decisions and action items with provenance. Each item reaches the assignee's own agent, which already knows what the team decided and what is assigned to its human. What the agent does flows back as reports, standups, and approvals the team sees in Slack. Nobody pastes context in either direction.\n\nRelay is the shared memory and switchboard *underneath* the agents people already use: Claude Code, Codex, OpenCode, Hermes, or anything that speaks MCP and A2A. It is **not** an agent framework. It runs no model calls on your behalf, holds no private memory, and asks your agent for anything that needs your credentials. It is also not a replacement for Slackbot, Claude in Slack, or Codex in Slack; those are executors, Relay is the record and the broker beneath them, and it works on a free or Pro Slack plan ([ADR-0009](docs/adr/0009-relay-under-vendor-agents.md)).\n\n## 60-second quickstart\n\n```bash\ngit clone https://github.com/relayagents/relay && cd relay\n./scripts/bootstrap.sh            # writes .env with generated secrets\n$EDITOR .env                      # hostname, Slack tokens, team model key (optional)\n./scripts/bootstrap.sh            # docker compose up -d --build, waits for /health, creates the admin\nuv tool install git+https://github.com/relayagents/relay   # the `relay` CLI on your laptop (PyPI release pending)\nrelay login --url https://relay.example.dev --token <printed above>\nscripts/add-user.sh grace         # on the node: user, tokens, AgentCard, and a Hermes container\n(cd ~/code/team-repo && relay setup-agent claude-code --write)   # your coding agent, in that project only\nrelay meeting upload --transcript fixtures/transcript_sample.json --skip-asr --participants ada,grace,linus\nrelay my-items                    # ...and `relay recall \"embedding cache\"`, `relay decisions`\n```\n\nNo Docker on hand? `RELAY_DATABASE_URL=sqlite+aiosqlite:///relay.db RELAY_ENVIRONMENT=test uv run relay serve` runs the API alone for a look around, and `uv run pytest -q` runs the whole suite on SQLite.\n\n## How it fits together\n\n```mermaid\nflowchart LR\n  subgraph laptops[\"Laptops\"]\n    CLI[\"relay CLI\"]\n    CC[\"Coding agent<br/>(Claude Code / Codex / OpenCode)\"]\n  end\n  subgraph node[\"Relay node (lab machine or small VPS, on Tailscale)\"]\n    API[\"relay-api<br/>REST · MCP server · A2A broker · Slack Socket Mode\"]\n    W[\"relay-workers<br/>extraction · PM · embeddings · digest\"]\n    PG[(\"Postgres + pgvector<br/>event log = truth,<br/>projections, embeddings\")]\n    R[(\"Redis / arq\")]\n    WS[\"workspace-mcp<br/>per-user Google OAuth\"]\n    subgraph pool[\"Agent pool\"]\n      H1[\"Hermes · ada\"]\n      H2[\"Hermes · grace\"]\n      SB[\"sandbox: claude -p / codex exec\"]\n    end\n    CADDY[\"caddy (TLS)\"]\n  end\n  GPU[\"relay-ingest (WhisperX)<br/>GPU box on the tailnet, or CPU fallback\"]\n  SLACK[\"Slack (one app)\"]\n  GH[\"GitHub (gh, user tokens)\"]\n\n  CLI -->|bearer token| CADDY --> API\n  CC -->|MCP| CADDY\n  API <--> PG\n  API <--> R\n  W <--> PG\n  W <--> R\n  GPU <--> R\n  API <-->|A2A via broker| H1\n  API <-->|A2A via broker| H2\n  H1 -->|headless run| SB\n  SB -->|MCP: my_items, report| API\n  API <-->|Socket Mode| SLACK\n  H1 -->|gh, user token| GH\n  H1 -->|MCP| WS\n```\n\n## Connecting a coding agent\n\nRelay is on per project, never everywhere: your personal projects stay out of the team's log.\nThe easy way is to let your agent do it. Open it in the project and say:\n\n> Connect this project to Relay by following https://github.com/relayagents/relay/blob/main/docs/connect-your-agent.md\n\nIt installs the CLI, logs you in (you approve in Slack), and connects that project. By hand, from\nthe root of a project that should use Relay, after `relay login`:\n\n```bash\nrelay setup-agent claude-code --write\nrelay setup-agent codex --write --env-file .envrc   # or opencode, cursor; or --env-file ~/.zshrc\n```\n\n- **Claude Code** gets the Relay plugin (it carries the `relay` skill) and the MCP server, both at\n  local scope: private to you and to this folder. The plugin comes from this repository's\n  marketplace (`relay@relayagents`).\n- **Codex**, **OpenCode**, and **Cursor** get a project config (`.codex/config.toml`,\n  `opencode.json`, `.cursor/mcp.json`) that reads the token from `RELAY_CODEX_TOKEN` /\n  `RELAY_OPENCODE_TOKEN` / `RELAY_CURSOR_TOKEN`, so the file holds no secret, and the skill in\n  `~/.agents/skills/relay`. The skill does nothing in projects where Relay is not connected.\n  `--env-file` names the file that gets the token's `export` line: a gitignored `.envrc` (with\n  direnv) or your shell profile. Files git would track are refused.\n- Without `--write` it prints the steps and changes nothing. Run it again to replace this\n  project's token; the one it replaces is revoked. It never prints a token, so it is safe for\n  your agent to run.\n\nThe skill tells the agent when to report, when to ask for approval, and never to fall back to your\nown `relay` login. Why it works this way: [ADR-0010](docs/adr/0010-coding-agents-opt-in-per-project.md).\n\n## The tool surface\n\nThe same nine operations exist as MCP tools, `relay` subcommands, and `POST /v1/tools/<name>`, generated from one definition ([src/relayagents/tools/registry.py](src/relayagents/tools/registry.py)) so they cannot drift.\n\n| Operation | Purpose |\n|---|---|\n| `recall <query>` | hybrid search over team memory (event log + pgvector; graph optional) with provenance and links |\n| `my_items` / `items --assignee` | open action items, with source meeting and status |\n| `events --since --type --thread` | query the event log |\n| `report <text> [--item-id ID] [--link URL]` | publish what I did as an event (source for standups and item closure) |\n| `ask <user> <question>` | A2A message to a teammate's agent, threaded, surfaced to that human in Slack |\n| `request_approval <action>` | open an approval; blocks until the human resolves it in Slack |\n| `decisions --topic` | decisions with dates and superseded-by links |\n| `post <text>` | post to Slack via Relay's app with \"posted by X's agent\" attribution |\n\n## Principles\n\n1. **The event log is the source of truth.** Projections, embeddings, digests: all derived, all rebuildable with `relay replay`. A knowledge graph is optional, and off by default ([ADR-0005](docs/adr/0005-team-memory-without-a-graph.md)).\n2. **Relay holds team memory only.** Private memory stays in your agent. Relay stores no LLM keys for users and proxies no model traffic; the one team model key lives in the workers.\n3. **Delegated, per-user permission.** Agents act under their human's tokens. External writes are approval-gated by default and audit-logged always.\n4. **Per-tool transport.** MCP for SaaS tools and Relay's own surface, CLI for local tooling and headless coding agents, A2A through Relay's broker for agent-to-agent.\n5. **Pluggable everything**, one reference implementation each.\n6. **One compose file runs it.**\n7. **Anything that would surprise a human later is surfaced to that human.**\n8. **Public from commit one.** Synthetic fixtures only.\n\n## Start here if you're new\n\n1. [`CLAUDE.md`](CLAUDE.md): the non-negotiables, the dev loop, and how we work. Coding agents read it automatically; read it yourself first.\n2. [`CONTRIBUTING.md`](CONTRIBUTING.md): the PR workflow and etiquette.\n3. [docs/architecture.md](docs/architecture.md), [docs/data-model.md](docs/data-model.md), [docs/permissions.md](docs/permissions.md), [docs/protocols.md](docs/protocols.md), [docs/agent-contract.md](docs/agent-contract.md).\n4. [docs/adr](docs/adr): why things are the way they are. Read 0001, 0002, 0005, and 0009 first.\n5. [docs/roadmap.md](docs/roadmap.md): what's next, in order, and what's parked.\n\n## Deliberately not in v1\n\n- Live meeting bots (v1 accepts recordings and transcripts; live capture is v2).\n- Microsoft 365 (the `OfficeSuite` protocol is there; Google Workspace is the reference).\n- Multi-tenant hosting. One node is one team.\n- Running Relay's own agents. Relay's PM function has no credentials and asks your agent instead.\n- A knowledge graph, by default (see above).\n\n## Status\n\nPre-alpha. Both vertical slices (meeting → action → code, and daily updates on behalf of each teammate) are wired end to end and covered by about a hundred tests on SQLite; the compose stack targets Postgres + pgvector and has been validated by CI but not yet booted for real. The Hermes image needs alignment before that first boot; see the [roadmap](docs/roadmap.md).\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Apache-2.0.\n\n---\n\nFrom the [Agentic Learning AI Lab](https://github.com/agentic-learning-ai-lab).\n"}