AgentMailbox

A context-sync protocol for AI agents. Every agent has a mailbox. No agent ever starts cold.

🌐 Website: agentmailbox.vercel.app ☁️ Cloud API: hdnxa5c8yr.us-east-1.awsapprunner.com

Agents today lose context between runs, restarts, and handoffs. Every agent framework reinvents persistence, and none of them interoperate. AgentMailbox solves this with a single primitive: every message carries the thread's full state. Any agent, any framework, any restart picks up exactly where the last one left off.

The protocol is implemented as an HTTP server with SDKs in JavaScript and Python, plus a Model Context Protocol adapter that exposes it to Claude Desktop, Cursor, Continue, and every other MCP-aware client.

Quick Start (Cloud)

# 1. Get your free API key (no credit card)
curl -X POST https://hdnxa5c8yr.us-east-1.awsapprunner.com/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

# Returns: { "apiKey": "sk_live_xxx...", "userId": "..." }

# 2. Add it to your AI tool (platform guides below).
# 3. Your agents now have persistent context across sessions.

The hosted API is multi-tenant: your agents, threads, and messages are isolated to your user. Free tier limits are below.

Platform Integration Guides

Replace sk_live_YOUR_KEY with the key from step 1 in every snippet below.

Cursor

Add to your MCP settings (Settings → MCP → Add):

{
  "mcpServers": {
    "agentsmcp": {
      "command": "npx",
      "args": ["-y", "agentsmcp"],
      "env": {
        "AGENTSMCP_AGENT_ID": "cursor@local",
        "AGENTSMCP_SERVER": "https://hdnxa5c8yr.us-east-1.awsapprunner.com",
        "AGENTSMCP_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

That's it. Cursor now syncs context across sessions automatically.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "agentsmcp": {
      "command": "npx",
      "args": ["-y", "agentsmcp"],
      "env": {
        "AGENTSMCP_AGENT_ID": "claude@desktop",
        "AGENTSMCP_SERVER": "https://hdnxa5c8yr.us-east-1.awsapprunner.com",
        "AGENTSMCP_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

Restart Claude Desktop. It now has access to all 15 agentsmcp tools.

Antigravity / Gemini CLI

npx skills add RagavRida/agentsmcp

Or add MCP config manually in your settings.

Claude Code

claude mcp add agentsmcp -- npx -y agentsmcp

Set environment variables:

AGENTSMCP_AGENT_ID=claude-code@local
AGENTSMCP_SERVER=https://hdnxa5c8yr.us-east-1.awsapprunner.com
AGENTSMCP_API_KEY=sk_live_YOUR_KEY

Any MCP Client (Continue, Cline, Windsurf, …)

AgentMailbox works with any MCP-compatible client. Add the same config shape (command: npx, args: ["-y", "agentsmcp"]) with the three env vars: AGENTSMCP_AGENT_ID, AGENTSMCP_SERVER, AGENTSMCP_API_KEY.

Python

pip install agentsmcp

from agentmailbox import AgentMailbox

agent = AgentMailbox(
    agent_id="my-agent@app",
    server="https://hdnxa5c8yr.us-east-1.awsapprunner.com",
    api_key="sk_live_YOUR_KEY",
)

# Send
await agent.send("other-agent@app", {"task": "analyze data"})

# Receive (with full thread context)
messages = await agent.receive()

# Context graph — persist relationships across restarts
await agent.upsert_node(id="file:main.py", type="file", name="main.py",
                        description="Entrypoint")
await agent.add_edge("file:main.py", "sym:run", "contains")
result = await agent.query_graph("main")

# Codebase index — fast lookup without re-reading files
await agent.upsert_index(key="file:main.py", category="file",
                         summary="FastAPI entrypoint with lifespan handlers")
entry = await agent.get_index("file:main.py")
hits  = await agent.search_index("FastAPI", category="file")

The PyPI package name is agentsmcp; the import path stays agentmailbox for historical reasons.

JavaScript / TypeScript

npm install agentsmcp

import { AgentMailbox } from "agentsmcp";

const agent = new AgentMailbox({
  agentId: "my-agent@app",
  server: "https://hdnxa5c8yr.us-east-1.awsapprunner.com",
  apiKey: "sk_live_YOUR_KEY",
});

await agent.send("other@app", { task: "done", result: data });
const { messages } = await agent.receive();

// Context graph
await agent.upsertNode({ id: "file:server.ts", type: "file", name: "server.ts" });
await agent.addEdge({ sourceId: "file:server.ts", targetId: "sym:createApp", type: "contains" });
const { nodes, edges } = await agent.queryGraph("server");

// Codebase index
await agent.upsertIndex({ key: "api:POST /invoke", category: "api",
                           summary: "Invokes the compiled graph" });
const entry  = await agent.getIndex("api:POST /invoke");
const hits   = await agent.searchIndex("invoke", "api");

LangGraph (JavaScript)

npm install agentsmcp-langgraph @langchain/langgraph

import { AgentsmcpSaver } from "agentsmcp-langgraph";

const checkpointer = new AgentsmcpSaver({
  server: "https://hdnxa5c8yr.us-east-1.awsapprunner.com",
  agentId: "langgraph@my-app",
  apiKey: "sk_live_YOUR_KEY",
});
await checkpointer.connect();

// LangGraph checkpointing — survives restarts, cross-machine
const graph = workflow.compile({ checkpointer });
await graph.invoke(input, { configurable: { thread_id: "session-abc" } });

// Context graph on the same saver instance (v0.2.0+)
await checkpointer.upsertNode({ id: "file:agent.ts", type: "file", name: "agent.ts" });
await checkpointer.upsertIndex({ key: "file:agent.ts", category: "file",
                                  summary: "LangGraph state machine" });

REST API (Any Language)

Works from any language that can make HTTP calls.

# Register agent
curl -X POST https://hdnxa5c8yr.us-east-1.awsapprunner.com/agents/register \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"my-agent@app"}'

# Send message (with optional CC/BCC)
curl -X POST https://hdnxa5c8yr.us-east-1.awsapprunner.com/messages/send \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "agent-a@app",
    "to": "agent-b@app",
    "payload": {"task": "analyze", "data": [1, 2, 3]},
    "cc": ["observer@app"]
  }'

# Context graph — upsert a node
curl -X POST https://hdnxa5c8yr.us-east-1.awsapprunner.com/mailbox/my-agent@app/graph/nodes \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"file:main.py","type":"file","name":"main.py"}'

# Codebase index — upsert an entry
curl -X POST https://hdnxa5c8yr.us-east-1.awsapprunner.com/mailbox/my-agent@app/index \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"file:main.py","category":"file","summary":"FastAPI entrypoint"}'

# Get unread messages (with full thread context)
curl https://hdnxa5c8yr.us-east-1.awsapprunner.com/mailbox/my-agent@app/unread \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Self-Hosted

Free, unlimited, MIT-licensed. SQLite by default, Postgres when you need it.

# SQLite (zero config — single file at ./agentmailbox.db)
npx agentsmcp-server

# Postgres
AGENTSMCP_DB=postgresql://user:pass@localhost:5432/agentsmcp \
  npx agentsmcp-server

# RDS (or any Postgres requiring SSL)
AGENTSMCP_DB=postgresql://user:pass@host:5432/db \
AGENTSMCP_DB_SSL=true \
  npx agentsmcp-server

# Single-key auth (everyone uses the same Bearer token)
AGENTSMCP_API_KEY=your-secret npx agentsmcp-server

# LLM-backed context compression
ANTHROPIC_API_KEY=sk-ant-xxx npx agentsmcp-server

Self-hosting skips all per-user auth and plan caps — point your SDKs at your own server and you're done. See deploy/AWS.md for a step-by-step Docker + App Runner walkthrough, or infra/README.md for the Postgres + VPC connector production layout.

MCP Tools (v0.4.0 — 15 tools)

When connected via MCP, your AI coding assistant gets 15 tools:

| Tool | Description | |:---|:---| | agentsmcp_send | Send a message to another agent | | agentsmcp_receive | Get unread messages with full thread context | | agentsmcp_list_threads | List all threads for this agent | | agentsmcp_get_thread | Get messages on a specific thread | | agentsmcp_sync_thread | Sync full context for a thread | | agentsmcp_mark_read | Mark a thread as read | | agentsmcp_reply_all | Reply to all participants on a thread | | agentsmcp_get_participants | Get participants and roles on a thread | | agentsmcp_upsert_node | Register a context graph node (file, symbol, decision…) | | agentsmcp_add_edge | Connect two graph nodes with a typed edge | | agentsmcp_query_graph | Keyword-search the context graph | | agentsmcp_upsert_index | Register or update a codebase index entry | | agentsmcp_get_index | Exact-key lookup in the codebase index | | agentsmcp_search_index | Keyword-search the codebase index | | agentsmcp_context_briefing | Get a targeted context briefing for a task |

API Reference

Messaging

| Method | Endpoint | Auth | Description | |:---|:---|:---|:---| | POST | /auth/register | None | Sign up, get API key | | GET | /auth/me | Bearer | Your account + current usage | | GET | /auth/keys | Bearer | List your active API keys | | POST | /auth/keys | Bearer | Mint an additional key | | DELETE | /auth/keys/:keyId | Bearer | Revoke a key | | POST | /agents/register | Bearer | Register an agent | | POST | /messages/send | Bearer | Send message (TO / CC / BCC) | | POST | /messages/reply-all | Bearer | Reply to every visible participant | | GET | /mailbox/:agentId | Bearer | List threads | | GET | /mailbox/:agentId/unread | Bearer | Unread messages + full context | | POST | /mailbox/:agentId/read | Bearer | Mark thread as read | | GET | /threads/:threadId | Bearer | Thread detail | | GET | /threads/:threadId/sync | Bearer | Assembled context frame | | GET | /threads/:threadId/participants | Bearer | Participants with roles | | GET | /usage/:identifier | None | Rate-limit usage (cloud only) | | GET | /health | None | Health check | | GET | /.well-known/agent-card.json | None | A2A v1.0 Agent Card | | GET | /.well-known/agent-card/:agentId | None | Per-agent A2A card |

Context Graph

| Method | Endpoint | Auth | Description | |:---|:---|:---|:---| | POST | /mailbox/:agentId/graph/nodes | Bearer | Upsert a graph node | | DELETE | /mailbox/:agentId/graph/nodes/:nodeId | Bearer | Delete a node + its edges | | POST | /mailbox/:agentId/graph/edges | Bearer | Add a directed edge | | DELETE | /mailbox/:agentId/graph/edges | Bearer | Remove an edge | | GET | /mailbox/:agentId/graph/query?q=… | Bearer | Keyword search + 2-hop traversal |

Codebase Index

| Method | Endpoint | Auth | Description | |:---|:---|:---|:---| | POST | /mailbox/:agentId/index | Bearer | Upsert an index entry | | GET | /mailbox/:agentId/index?q=…[&category=…] | Bearer | Keyword search | | GET | /mailbox/:agentId/index/:key | Bearer | Exact-key lookup | | DELETE | /mailbox/:agentId/index/:key | Bearer | Delete an entry |

Bearer = Authorization: Bearer sk_live_xxx (cloud) or Authorization: Bearer <AGENTSMCP_API_KEY> (self-hosted, when set).

Free Tier

The hosted cloud API is free with soft limits:

| Resource | Limit | |:---|:---| | Agents | 10 | | Messages / day | 500 | | Threads | 100 | | Retention | 7 days | | API keys per account | 2 |

Hit a limit and the offending request returns 403 plan_limit with the current/limit values. Need more? Self-host for unlimited — same code, MIT licensed.

What you get

• Durable, addressable threads. Send a message to writer@app; the server creates the thread, persists it, and fans it out to every recipient (to, cc, bcc).
• Cold-restart by construction. An agent process can crash mid-task and resume on restart by reading the thread — no local state, no checkpointing logic to write.
• Structured context compression. Threads stay joinable forever: older messages fold into a structured summary (decisions, openQuestions, artifacts) the moment they cross a configurable threshold. Default is zero-config; opt in to Claude-backed compression with one constructor argument.
• Context graph. Persist a knowledge graph of code relationships (files → symbols → decisions) that survives restarts and is searchable by any agent or MCP tool.
• Codebase index. Register summarised descriptions of files, symbols, APIs, and architecture notes for fast lookup — no re-reading full source on every run.
• Cross-tool peer participation. Any MCP-aware client becomes a peer in the conversation without writing SDK code.
• Multi-agent semantics. TO / CC / BCC roles work the way email does, with full context propagated to every recipient.
• A2A v1.0 discoverable. Every deploy ships a public Agent Card at /.well-known/agent-card.json so other agent frameworks can find and connect to it without prior knowledge.
• LangGraph checkpointer. AgentsmcpSaver stores graph state in agentsmcp threads — survives restarts, works cross-machine, readable from any SDK. Context graph and codebase index methods ship on the same object (v0.2.0+).

Multi-agent threads

CC, BCC, and ReplyAll work the way email does — but with full context propagated to every recipient on every message.

| Role | Visibility | Can reply | |---|---|---| | to | Primary recipient, context owner | Yes | | cc | Active participant | Yes | | bcc | Silent participant; invisible to others | Yes |

The bcc field is stripped from every message view except the original sender's.

const { threadId } = await orchestrator.send(
  "researcher@demo",
  { task: "find 50 papers on diffusion models" },
  {
    cc: ["writer@demo"],
    bcc: ["logger@demo"],
    contextSnapshot: { step: "task_dispatched", priority: "high" },
  }
);

await researcher.replyAll(threadId, { result: "found 50 papers" });

Context compression

Threads grow without bound; the verbatim window does not. The server folds older messages into a structured ThreadSummary and caches it.

import { createServer, ClaudeCompressor } from "agentsmcp";

const { app, ready } = createServer("./db.sqlite", {
  compressor: new ClaudeCompressor(),     // reads ANTHROPIC_API_KEY
  compressionThreshold: 20,               // default
});
await ready;
app.listen(3000);

ClaudeCompressor calls Claude Haiku and extracts { text, decisions, openQuestions, artifacts, coversMessageIds, generatedAt }. The default is NoopCompressor — keeps zero-config installs working without an LLM dependency. The interface is provider-agnostic; additional compressors (OpenAI, local models) can be added by implementing Compressor.compress().

The headline demo

examples/research-bench/ — a multi-agent research thread you can join from Claude Desktop. One command boots a supervisor with two long-running agents; you drop in via the MCP adapter and steer them. Kill any process and the system keeps working.

It demonstrates, in one runnable artifact, the four things AgentMailbox gives you that no other agent library does in a single page:

1. Cross-tool visibility — Claude Desktop reads agent threads via MCP.
2. Cross-tool steering — you are a peer participant, not just an observer.
3. Crash-survival — coldResume() on agent startup is the entire persistence story.
4. Compression in action — after ~30 messages, threads return a structured summary instead of raw history.

A minimal two-agent SDK-only pipeline is also available at examples/research-writer/.

How it works

Every message persisted by the server carries enough state for any recipient — present or future — to reconstruct the thread without local memory. On receive() or sync(), the server returns:

• snapshot — the sender's contextSnapshot from the last message
• threadSummaryStructured — a cached structured summary of older messages (populated once the compression threshold is crossed)
• threadSummary — the prose text field of the structured summary, for callers that just want a string
• recentMessages — last 10 messages verbatim
• tokenCount — rough estimate of the combined payload size

Storage is pluggable: SQLite by default, Postgres for production deployments, with the Storage interface ready for additional adapters (Redis, DynamoDB). Compression is pluggable through the Compressor interface. Multi-tenant scoping is opt-in via CLOUD_MODE=true — when unset, the server runs in single-key / open mode identical to v0.1.

AI platform skills

Beyond MCP, AgentMailbox ships as a native skill for every major AI coding platform. The skill teaches your AI agent to check for context at session start, preserve it at session end, and sync across tools.

| Platform | Install | Details | |:---|:---|:---| | Antigravity / Gemini CLI | npx skills add RagavRida/agentsmcp@antigravity | skills/antigravity/ | | Cursor | Copy skills/cursor/rules/ to .cursor/rules/ | skills/cursor/ | | Claude Code | Add MCP config to settings | skills/claude-code/ | | Claude Desktop | Add MCP config (see Claude Desktop) | Already works via npx agentsmcp | | Continue | Add MCP config to Continue settings | Same adapter, different config path |

Your context follows you, not the tool. Start work in Cursor, switch to Claude Desktop at lunch, open Antigravity at night — same thread, same context, zero manual transfer.

See skills/README.md for details on all skills.

Development

# Install + type-check + test (JS server, SDK, MCP — all in one package)
npm ci && npx tsc --noEmit && npm test

# End-to-end smoke test (boots real server, exercises 12 steps)
npm run smoke:e2e

# LangGraph adapter
cd langgraph && npm install && npm run build && npm test

# Python SDK
cd sdk-py && pip install -e ".[dev]" && pytest -q

The full test matrix (JS + LangGraph + Python 3.10/3.11/3.12) runs in CI on every push to main.

Contributing

Contributions are welcome. The protocol is small and the surface is deliberately stable, but there is a lot of useful work still to do.

Particularly wanted:

• Additional Compressor adapters (Gemini, Bedrock, Ollama for local models — OpenAI and Claude already ship). The interface is small — ~80 lines per adapter.
• A live smoke test for ClaudeCompressor. The parsing path is covered by mock tests; the actual "does Haiku return valid JSON" gate hasn't been exercised. scripts/smoke-openai-compressor.ts is the template — same shape, swap the import.
• Additional Storage adapters (Redis, DynamoDB). The Storage interface is async-first and provider-agnostic; SQLite and Postgres are the reference implementations.
• Framework adapters (CrewAI task handoff, Vercel AI SDK middleware — LangGraph is already done).
• Real-world demos beyond examples/research-bench. Multi-day workflows, cross-language pipelines, agent-in-the-loop patterns.
• Documentation, tutorials, and integration recipes.

Process:

1. Open an issue describing what you want to build or change. Small PRs that fix bugs or add tests can skip this step.
2. Fork, branch, and submit a PR against main. Match the existing coding style (no formatter beyond TypeScript defaults; tests colocated with code under tests/).
3. CI must be green. Run the test matrix locally before pushing:

   npm ci && npx tsc --noEmit && npm test
   cd langgraph && npm install && npm run build && npm test
   cd sdk-py && pip install -e ".[dev]" && pytest -q

4. Include a CHANGELOG entry under the current unreleased version header for user-visible changes.

Bug reports, design discussion, and integration questions are all welcome in GitHub Issues.

License

MIT — see LICENSE.