Architecture

Agent Mail exposes exactly 34 tools and over 20 read-only resources through the Model Context ProtocolMCPModel Context ProtocolAn open standard for connecting AI models to external tools and data sources. Agent Mail exposes its 34 tools and 20+ resources via MCP, making it compatible with any MCP-capable coding agent. surface. Because the interface speaks pure JSON-RPC over `stdio`, any modern AI assistant—from Claude Code and Cursor to standalone language models—can seamlessly interoperate with the swarm.

Every message and reservation event splits down two concurrent paths. First, it hits SQLite in WAL modeWALWrite-Ahead Log for crash safetySQLite's WAL (Write-Ahead Log) mode allows concurrent readers and a single writer without blocking. Agent Mail uses WAL mode to serve agent queries while the commit coalescer batches writes, combining high read throughput with durable writes., guaranteeing immediate visibility for fast FTS5 queries without blocking reads. Simultaneously, it enters a Write-Behind Queue (WBQ) bound for the filesystem.

This architecture ensures the live system is blazing fast while still producing human-readable Markdown artifacts in a Git repository.

When a swarm of 30 agents attempts to log operations simultaneously, raw Git index locks will aggressively contend and crash. The Commit CoalescerCommit CoalescerBatches Git commits for efficiencyInstead of creating a Git commit for every write operation, the storage layer batches multiple writes into fewer commits. Stress tests show a 9.1x reduction (100 writes → 11 commits). intercepts high-frequency filesystem writes and dynamically batches them.

Under extreme load, the coalescer can achieve a 9.1x reduction in Git commits, converting an overwhelming storm of isolated operations into clean, atomic filesystem transactions.

The Product BusProduct BusCross-repository coordination layerLinks multiple Git repositories under a single product umbrella. Enables cross-project search, unified inbox aggregation, and inter-project contact management. maps discrete `project_keys` into a unified namespace. This allows agents to seamlessly search for context, check reservations, and dispatch messages across completely distinct codebases (like a frontend and backend repo) without ever bridging their respective Git archives.

The Search V3 engine is designed for robust operation. It dispatches queries across lexical (BM25) and semantic vectors in parallel, fusing them with RRF. Crucially, if the semantic model times out, the system degrades gracefully to purely lexical mode—and if SQLite locks up, it falls back to a chronological scan, guaranteeing that an agent is never entirely blinded.

Agent Mail is designed to survive the chaos of AI agent swarms. If the WBQWrite-Behind QueueBuffered async write pipelineA queue that accumulates rapid-fire write operations and flushes them as batch commits on a configurable interval. Decouples write latency from archive durability, allowing the system to acknowledge writes instantly while persisting them in the background. floods past a threshold of 128 items, the server safely projects backpressureBackpressureFlow control under overloadWhen incoming request rate exceeds processing capacity, the system applies backpressure by shedding low-priority work (maintenance tools like archive_repair) while always admitting high-priority operations (send_message, fetch_inbox). This prevents cascading failure under load spikes. to limit ingestion, giving background workers (Metrics, Integrity, Retention) time to drain buffers.