Self-hosted on your own Supabase project. MCP-native for Claude Code. Once installed, just talk to Claude — the CLI is optional. From clone to first conversational deposit in under 10 minutes.
If you're running Claude Code already, paste the prompt below into any session. The agent will clone the repo, build the CLI, link it globally, configure local SQLite storage, install the using-relay skill into ~/.claude/skills/, register the MCP server in your Claude Code config, and verify everything works. Then restart Claude Code so the new skill and MCP server register.
# Paste this into Claude Code I want to set up Relay on this machine. Its public repo is https://github.com/tensorpunk-labs/relay. Please: 1. Clone it as a sibling directory of this repo. 2. Run pnpm install && pnpm build inside it. 3. Link the CLI globally: pnpm --filter @relay/cli link --global. 4. Configure local SQLite storage and set my actor identity: relay config set storage sqlite relay config set actor-id <me> relay config set actor-type human 5. Install the using-relay skill: copy skills/using-relay/ into ~/.claude/skills/. 6. Register the MCP server in my Claude Code config so the agent can deposit and pull context directly. The entry point is packages/mcp/dist/index.js inside the cloned relay repo. 7. Verify the setup with relay projects list and relay --version. If any step fails, stop and tell me what went wrong before continuing.
Not using Claude Code? The manual steps are right below.
Relay runs against your own Supabase project. You own the data, the schema, and the storage bucket. No vendor dependency beyond Supabase itself.
Prerequisites
node --version to checknpm install -g pnpm if missingGo to supabase.com, create a new project, then run the migration in the SQL editor:
Then create a Storage bucket named context-packages (private, 50MB limit per file).
alias relay="node /path/to/relay/packages/cli/dist/index.js" to your shell profile so relay is available globally.
Relay ships an MCP server that exposes nine tools directly inside Claude Code.
Once registered, every session can call relay_session_orient, relay_deposit,
relay_orchestrate, and more — no manual CLI invocation needed.
Open (or create) ~/.claude/mcp.json and add the relay server entry:
/path/to/relay with your actual clone path. On Windows use forward slashes or escaped backslashes: X:\\path\\to\\relay.
Fully quit and reopen Claude Code. The MCP server initializes on startup. You should see "relay" appear in the connected servers list.
In a Claude Code session, ask Claude to run:
Or from the terminal:
Add relay orient to Claude Code's SessionStart hook so every session begins pre-oriented without asking:
Once the MCP server is configured, you don't need to memorize commands or switch terminals. Claude speaks Relay natively. Ask in plain English — Claude calls the right MCP tools behind the scenes. The CLI exists for scripting, hooks, and power users.
relay_deposit, relay_pull_context, relay_orchestrate,
relay_session_orient, relay_assert_fact, and relay_query_facts
based on the context of the conversation.
At the end of a meaningful unit of work, just tell Claude to remember it:
Claude packages the context, adds a handoff note, and calls relay_deposit. You stay in the flow.
Starting a new session? Jumping to another project? Ask Claude to get you oriented:
Claude picks the right call — semantic search, latest packages, or filtered by project.
When you need the big picture, not just one package, use orchestrate. Claude synthesizes across everything:
Relay assembles context packages + facts + handoff notes across sessions; Claude writes the synthesis.
Packages are the immutable journal. Facts are the mutable whiteboard — use them when "the truth changed":
Claude calls relay_assert_fact or relay_query_facts. Old assertions auto-supersede. No history is rewritten.
Install a Stop hook so every session automatically captures git state as a package. Pairs with your conversational deposits for full coverage:
Auto-deposits capture what changed (git diff, branch, files). Your conversational deposits capture why (decisions, reasoning, intent). Both together make your session history complete.
The CLI exists for scripting, hooks, and power-user workflows. Jump to the CLI Reference when you want to:
--as-of time-travelFor day-to-day usage, conversational Relay is the whole product.
Two small habits keep Relay healthy as it accumulates context: archive projects when they go dormant so they stop leaking into your digests, and back up your active projects periodically so you can move, mirror, or restore them at will.
When a project goes dormant, soft-archive it with relay projects archive <id>.
Archiving is reversible — no data is deleted — but it stamps an archived_at
timestamp that hides the project from relay projects list, drops it out of
relay orchestrate's global digest, and causes auto-deposits routed to it (e.g. via the
stop hook) to skip cleanly instead of polluting a dead journal. Run relay projects restore <id>
to bring it back later.
proj_dev_relay) without an explicit --force flag. The meta project tracks
Relay itself; silencing it by accident would leave you blind to your own context system.
relay backup dumps a project's packages, facts, sessions, and blob deliverables to a
local directory as protocol-portable NDJSON plus a blobs/ folder. The wire format is the
Agentic Protocol's — any conformant implementation, not just Relay, can ingest the output.
The command is read-only against the live store, so it's safe to run while Relay is in use, and it
pairs naturally with cron or a scheduled task. Use it for disaster recovery, for migrating between
Supabase projects, or for moving to a different Relay-compatible backend later.
What's next