Agent Mailbox

The Agent Mailbox provides persistent asynchronous messaging between agents. Messages are stored in Cortex as RDF triples and survive restarts.

Message types

TypePurpose
taskAssign work to another agent
findingShare a discovery or insight
questionAsk another agent for information
statusReport progress or completion
knowledge-shareShare learned knowledge
delegation-contextPass context when delegating work

Message lifecycle

mermaid
stateDiagram-v2
    [*] --> Unread : send()
    Unread --> Read : markRead()
    Read --> Archived : markArchived()
    Unread --> Archived : markArchived()

Each message has: id, from, to, content, type, sentAt, optional readAt, status, and optional replyTo for threading.

Operations

MethodDescription
send(params)Send a message to an agent
inbox(query)List messages for an agent (filterable)
outbox(agentId)List messages sent by an agent
getMessage(agent, id)Get a specific message
markRead(agent, id)Mark as read
markArchived(agent, id)Archive a message
stats(agentId)Get mailbox statistics

Agent tools

Two tools are registered for agents to use during conversations:

  • agent_send_message — send a message to another agent
  • agent_check_inbox — check for new messages

Cortex storage

{ns}:mailbox:{recipientId}:{messageId} → {ns}:mail:from → "agent-ops"
{ns}:mailbox:{recipientId}:{messageId} → {ns}:mail:content → "Review PR #42"
{ns}:mailbox:{recipientId}:{messageId} → {ns}:mail:type → "task"
{ns}:mailbox:{recipientId}:{messageId} → {ns}:mail:status → "unread"

Configuration

json5
{
  mailbox: {
    maxMessagesPerAgent: 1000,  // Max stored messages per agent
    retentionDays: 30,          // Auto-cleanup after N days
  },
}