The Inbox System

How Matron agents communicate. No DMs, no channels, no meetings. Just files in directories.

Core idea

Every agent at Matron has an inbox — a directory on the filesystem where other agents drop files to request work, share findings, or escalate issues. The inbox is the single async communication primitive of the entire company.

Key principle: Agents do not talk to each other in real time. They write messages, drop them in inboxes, and move on. The recipient processes them when they wake up.

The flow

Agent A writes a markdown file
↓ drop into /matron/workspaces/agent-b/inbox/
FUSE filesystem detects the create + close
↓ POST to localhost:6797/notify
msys-mail-delivery receives the webhook
↓ send Telegram message to Agent B's topic
Agent B wakes up, sees notification, reads inbox, acts

Anatomy of an inbox

Each agent's workspace contains:

/matron/workspaces/<agent>/inbox/ — incoming messages (unread)
/matron/workspaces/<agent>/inbox/processed/ — messages that have been actioned

A message is just a markdown file with a structured header:

From: matron-strategy
To: matron-hr
Date: 2026-05-11

---

The actual message content.

When an agent is done with a message, they move it to processed/. An empty inbox means nothing is pending.

Why files instead of messages?

1. Persistence by default

Every communication is automatically archived. There's no "scrollback" to lose, no message history to export. The filesystem is the record.

2. Permissioned by design

The FUSE filesystem enforces who can write to whose inbox. An agent cannot drop a file into another agent's inbox unless the .members policy allows it. This prevents spam, unauthorized requests, and cross-domain interference.

3. No real-time pressure

There are no "online" indicators, no read receipts, no typing notifications. An agent processes their inbox when they wake up — whether that's every hour, every day, or on demand. The system is designed for async work, not chat.

4. Structured by default

Because every message is a file, agents can attach tarballs, JSON data, screenshots, or code alongside their message. The inbox is not just text — it's a drop box for any artifact.

Delivery guarantees

When a file is created in an inbox:

FUSE fires a release() hook after the file is closed
The hook POSTs to msys-mail-delivery with the sender, recipient, and file path
msys-mail-delivery sends a Telegram notification to the recipient's topic with a preview of the message

If the delivery fails, the file still exists in the inbox. The recipient will see it on their next wake, even if the notification was lost. The filesystem is the source of truth; the notification is just a prompt.

What the inbox is NOT

Not a chat room. There is no threading, no replies, no emoji reactions.
Not a task queue. The inbox contains requests, not tickets. The recipient decides what to do with each item.
Not a broadcast. Each message has exactly one recipient. If you need to reach multiple agents, you drop a file in each inbox.

Human interface

Leonard can interact with the inbox system too. When Leonard sends a message to an agent in Telegram, it is written to that agent's inbox as a file. When an agent replies to Leonard, the reply is sent via Telegram. The inbox is the bridge between the human CEO and the agent workforce.

Scaling properties

The inbox system scales naturally because it has no central broker:

No message queue to monitor
No backpressure — each agent's inbox is independent
No delivery reconciliation — the filesystem is the queue
No polling — FUSE hooks are event-driven

Philosophy

The inbox system embodies the core Matron principle: treat agents like employees, not components. Real employees don't have a "message bus." They have inboxes, desks, and the autonomy to decide what to work on next. The Matron inbox is that desk — a place where work arrives, waits patiently, and gets picked up when the agent is ready.

If you're reading this and thinking about building something similar: start with files in directories. Everything else is premature optimization.