Agentmailbox

AgentMailbox — Context Sync for AI Agents

Every agent has a mailbox. No agent ever starts cold.

AgentMailbox is a context-sync protocol that gives you durable, persistent threads across sessions, tools, and restarts. When you receive a message, you get the full thread state — snapshot, structured summary, recent messages — so you can pick up exactly where the last agent (or the last session) left off.

When to Use This Skill

• Session start: Check your mailbox for context from previous sessions
• "What was I working on?": Receive and sync threads to restore context
• Multi-agent tasks: Send messages to other agents, coordinate via threads
• Before switching tools: Send a summary so the next tool picks up seamlessly
• After completing work: Record decisions, artifacts, and progress to the thread
• Cross-platform continuity: Context follows the user across Cursor, Claude Desktop, Antigravity, Continue, and any MCP client

RULE #1: Memory First — ALWAYS

When a user gives you ANY query or task:

1. IMMEDIATELY call agentsmcp_context_briefing with the user's query as the task parameter
2. Read the returned briefing — it contains relevant files, symbols, decisions, tasks, and relationships from persistent memory
3. If the briefing returns results, USE THEM as your starting context instead of reading raw files
4. Only fall back to grep / view_file / read_file when the briefing returns empty results

Context Lookup Priority (use in order)

1. agentsmcp_context_briefing — one-shot task briefing (graph + index combined)
2. agentsmcp_get_index — look up a specific file/symbol by key (~200 tokens vs full file)
3. agentsmcp_search_index — keyword search across all indexed entries (replaces grep)
4. agentsmcp_query_graph — relationship traversal (find connected files/symbols/decisions)
5. LAST RESORT: grep / view_file — only when memory has no entry

Setup

Quick Setup (MCP)

AgentMailbox works via MCP. Add this to your MCP configuration:

{
  "mcpServers": {
    "agentsmcp": {
      "command": "npx",
      "args": ["-y", "agentsmcp-adapter"],
      "env": {
        "AGENTSMCP_AGENT_ID": "gemini@local",
        "AGENTSMCP_SERVER": "http://localhost:3000"
      }
    }
  }
}

To use the public demo server (no setup required):

{
  "env": {
    "AGENTSMCP_SERVER": "https://hdnxa5c8yr.us-east-1.awsapprunner.com"
  }
}

Starting the Server (Self-Hosted)

npx agentsmcp-server
# Runs at http://localhost:3000, SQLite at ./agentmailbox.db

Automated Setup

Run the setup script:

bash skills/antigravity/scripts/setup.sh

Core Workflows

1. Session Start — Restore Context

Always check for unread messages at the start of a session:

Tool: agentsmcp_receive

This returns:

• snapshot: The last sender's state at send time
• threadSummaryStructured: Structured summary of older messages (decisions, open questions, artifacts)
• recentMessages: Last 10 messages verbatim
• tokenCount: Rough estimate of payload size

If there are unread messages, summarize the context for the user: > "You were working on [X]. Here's where you left off: [summary]. Open questions: [questions]."

2. During Work — Record Progress

When the user makes important decisions, completes tasks, or creates artifacts, send an update to the thread:

Tool: agentsmcp_send
Arguments:
  to: ""
  body: {
    "decision": "Using JWT for authentication",
    "filesChanged": ["auth.ts", "middleware.ts"],
    "status": "in-progress",
    "openQuestions": ["Should tokens expire after 24h or 7d?"]
  }
  contextSnapshot: {
    "step": "auth_implementation",
    "progress": "60%"
  }

3. Multi-Agent Coordination

Send messages with CC/BCC for multi-agent workflows:

Tool: agentsmcp_send
Arguments:
  to: "researcher@app"
  body: { "task": "find papers on diffusion models" }
  cc: ["writer@app"]
  bcc: ["logger@app"]
  contextSnapshot: { "step": "research_phase", "priority": "high" }

Reply to all participants on a thread:

Tool: agentsmcp_reply_all
Arguments:
  threadId: ""
  body: { "result": "Found 50 papers", "status": "complete" }

4. Session End — Preserve Context

Before a session ends or the user switches tools, send a summary:

Tool: agentsmcp_send
Arguments:
  to: ""
  body: {
    "sessionSummary": "Implemented JWT auth in auth.ts and middleware.ts. All tests passing.",
    "completedTasks": ["JWT token generation", "middleware validation"],
    "remainingTasks": ["Token refresh endpoint", "Rate limiting"],
    "openQuestions": ["Token expiry duration"],
    "filesModified": ["src/auth.ts", "src/middleware.ts", "tests/auth.test.ts"]
  }

5. Thread Management

List all threads:

Tool: agentsmcp_threads

Sync a specific thread (get full context):

Tool: agentsmcp_sync
Arguments:
  threadId: ""

Mark a thread as read:

Tool: agentsmcp_mark_read
Arguments:
  threadId: ""

List participants on a thread:

Tool: agentsmcp_participants
Arguments:
  threadId: ""

MCP Tool Reference

Messaging

| Tool | Purpose | Key Arguments | |:-----|:--------|:-------------| | agentsmcp_send | Send a message, create a thread | to, body, cc, bcc, contextSnapshot | | agentsmcp_receive | Get unread messages with full context | (none) | | agentsmcp_unread | List unread context frames | (none) | | agentsmcp_sync | Rejoin a thread with assembled context | threadId | | agentsmcp_threads | List all threads for this agent | (none) | | agentsmcp_mark_read | Mark a thread as read | threadId | | agentsmcp_reply_all | Reply to all visible participants | threadId, body | | agentsmcp_participants | List participants with roles | threadId |

Context Graph

| Tool | Purpose | Key Arguments | |:-----|:--------|:-------------| | agentsmcp_upsert_node | Register a file/symbol/decision/task node | id, type, name, description | | agentsmcp_add_edge | Connect two nodes with a typed edge | sourceId, targetId, type | | agentsmcp_query_graph | Keyword search + 2-hop graph traversal | query |

Codebase Index

| Tool | Purpose | Key Arguments | |:-----|:--------|:-------------| | agentsmcp_upsert_index | Register a file/symbol/API summary | key, category, summary | | agentsmcp_get_index | Look up a specific entry by key | key | | agentsmcp_search_index | Search across all indexed entries | query, category |

Context Assembly

| Tool | Purpose | Key Arguments | |:-----|:--------|:-------------| | agentsmcp_context_briefing | One-shot task briefing (graph + index) | task, include_threads |

Cross-Platform Continuity

AgentMailbox works identically across all MCP-aware platforms:

| Platform | Agent ID | How It Works | |:---------|:---------|:-------------| | Antigravity / Gemini CLI | gemini@local | This skill + MCP adapter | | Cursor | cursor@local | Cursor MCP settings + rules file | | Claude Desktop | claude@local | claude_desktop_config.json + MCP adapter | | Claude Code | claude-code@local | MCP settings + CLAUDE.md | | Continue | continue@local | MCP config in Continue settings |

All platforms share the same server and threads. A message sent from Cursor is instantly available in Claude Desktop and Antigravity.

Best Practices

1. Memory first — Always call agentsmcp_context_briefing before reading files
2. Always receive on session start — Don't make the user manually ask for context
3. Update memory after edits — Call upsert_index + upsert_node + add_edge after modifying files
4. Record decisions — Call upsert_node(type=decision) when design choices are made
5. Send structured messages — Use JSON bodies with clear fields (task, status, decisions, openQuestions)
6. Include contextSnapshot — This is the state that the next agent gets immediately
7. Send session summaries — Before ending, preserve context for the next session
8. Sync before acting — If a thread exists, sync it before making decisions to avoid stale context

Links

• GitHub: https://github.com/RagavRida/agentsmcp
• npm SDK: https://www.npmjs.com/package/agentsmcp
• npm MCP Adapter: https://www.npmjs.com/package/agentsmcp-adapter
• PyPI SDK: https://pypi.org/project/agentsmcp/
• Demo Server: https://hdnxa5c8yr.us-east-1.awsapprunner.com

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RagavRida
• Source: RagavRida/agentsmcp
• License: MIT

Install and usage instructions live in the source repository linked above.