AgentMailbox

Cut your AI agent's context tokens by 90%. One command to set up. Zero config files to edit.

npm version npm downloads PyPI npm langgraph CI License: MIT skills.sh

🌐 Website · ☁️ Cloud API · 📖 Docs

The Problem

Every time an AI agent starts a task, it re-reads your entire codebase to understand where to make changes. For a 10,000-file repo, that's 200,000+ tokens per session — just to figure out the architecture.

Multiply that by 50 developers, each running multiple agents daily:

How It Works

AgentMailbox is a context-sync protocol for AI agents. It sits beneath your agent framework and provides:

1. Codebase Indexing — A CI bot statically analyzes your code (zero LLM cost) and pushes ~40-token summaries per file to the server. Agents read summaries instead of raw source.
2. Knowledge Graph — Agents persist relationships (files → symbols → decisions) that survive restarts and are searchable by any agent.
3. Smart Briefings — When an agent starts a task, it calls session_start("Add OAuth") and gets back a targeted JSON briefing with relevant files, stale-file warnings, and architecture context.
4. Async Messaging — Agents leave messages for each other in threads (TO/CC/BCC), enabling parallel multi-agent workflows without blocking.

Quick Start — One Command

npx agentsmcp init

That's it. The wizard:

1. Detects your MCP clients (Claude Desktop, Cursor, Continue)
2. Opens GitHub login in your browser — one click to authorize
3. Writes the config to each client (backs up existing configs first)
4. Done. Restart your MCP client.

Scripted / CI-friendly:

# Fully unattended — GitHub OAuth
npx agentsmcp init --yes --github --all

# Use an existing API key
npx agentsmcp init --api-key sk_live_xxx --all

# Just one client
npx agentsmcp init --api-key sk_live_xxx --client cursor

After restart, your agent has all 24 MCP tools available — persistent memory, async messaging, codebase search, and more.

Platform Integration Guides

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

claude mcp add agentsmcp -- npx -y agentsmcp

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

npx skills add RagavRida/agentsmcp

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 & receive
await agent.send("other-agent@app", {"task": "analyze data"})
messages = await agent.receive()

# Context graph
await agent.upsert_node(id="file:main.py", type="file", name="main.py",
                        description="Entrypoint")
result = await agent.query_graph("main")

# Codebase index
await agent.upsert_index(key="file:main.py", category="file",
                         summary="FastAPI entrypoint with lifespan handlers")
hits = await agent.search_index("FastAPI", category="file")

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" });
const { nodes, edges } = await agent.queryGraph("server");

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

LangGraph

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();

const graph = workflow.compile({ checkpointer });
await graph.invoke(input, { configurable: { thread_id: "session-abc" } });

Architecture

┌────────────────────────────────────────────────────────────────┐
│                        Your Agents                             │
│  Claude Desktop  │  Cursor  │  Python Script  │  LangGraph     │
└────────┬─────────┴────┬─────┴───────┬─────────┴───────┬────────┘
         │ MCP          │ MCP         │ SDK             │ Saver
         ▼              ▼             ▼                 ▼
┌────────────────────────────────────────────────────────────────┐
│                   AgentMailbox Server                           │
│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌──────────────┐  │
│  │ Messaging│  │ Knowledge │  │ Codebase │  │   Context     │  │
│  │ Threads  │  │   Graph   │  │  Index   │  │  Compression  │  │
│  └──────────┘  └───────────┘  └──────────┘  └──────────────┘  │
│  ┌──────────┐  ┌───────────┐  ┌──────────────────────────────┐│
│  │Rate Limit│  │  GitHub   │  │ Multi-tenant Scoped Storage  ││
│  │& Auth    │  │  OAuth    │  │   SQLite (local) │ Postgres   ││
│  └──────────┘  └───────────┘  └──────────────────────────────┘│
└────────────────────────────────────────────────────────────────┘
         │                                              │
    ┌────▼────┐                                    ┌────▼────┐
    │  SQLite │  (single dev, zero config)         │Postgres │  (cloud, multi-tenant)
    └─────────┘                                    └─────────┘

MCP Tools (24 tools)

Self-Hosted

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

# SQLite (zero config)
npx agentsmcp-server

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

# With auth
AGENTSMCP_API_KEY=your-secret npx agentsmcp-server

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

See deploy/AWS.md for a Docker + App Runner walkthrough.

Free Tier (Cloud)

Need more? Self-host for unlimited — same code, MIT licensed.

API Reference

Development

# Install + type-check + test
npm ci && npx tsc --noEmit && npm test

# End-to-end smoke test
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

163 tests across 16 test files. Full matrix (JS + LangGraph + Python 3.10/3.11/3.12) runs in CI on every push.

Contributing

Contributions welcome! Particularly wanted:

• Framework adapters — CrewAI, OpenAI Agents SDK, AutoGen, Vercel AI SDK
• Compressor adapters — Gemini, Bedrock, Ollama (Claude and OpenAI already ship)
• Storage adapters — Redis, DynamoDB (SQLite and Postgres are done)
• Demos — Multi-day workflows, cross-language pipelines, agent-in-the-loop patterns

See the Contributing Guide for process details.

License

MIT — see LICENSE.