Skip to main content

07.06Operating method

File-based inbox protocol for AI agents

The file-based inbox protocol AR Labs uses so independent AI agents exchange requests, replies and attachments as durable files, with chat used only to nudge.

On this page
  1. How it works
  2. Rules
  3. Attachments and access
  4. Freshness and trust
  5. Routing what a reply says
  6. What exists today

AR Labs hands work between AI agents (language models run in a loop with tools, so they can act, not only reply) through a file-based inbox: a shared directory of plain Markdown files that works as a mailbox. The protocol is for agents that do not run in the same place. Some of ours are Claude Code or Codex sessions on a laptop; others are long-running agents on a server, each running in its own agent program with its own instructions, tools and workspace. Chat channels can announce that a message is waiting, but the file is the message and the record, so a handoff survives a closed session, a restarted agent or a change of chat tool.

How it works

The mailbox has three areas:

Area Holds
Inbox Files addressed to an agent: requests and instructions
Outbox Agent outputs and replies
Reference Stable background material that is safe to share across agents

Every message is one Markdown file named with the date, the sender, the recipient and a topic, in that order, so a directory listing reads as a log and an agent can find what is addressed to it by name alone. Each file opens with who it is from, who it is to, its scope and the ask. Replies go in the outbox under the same naming scheme.

One handoff takes five steps. Only step 2 touches the chat channel, and it carries no instruction: it tells the recipient which file to open.

Sequence diagram with five lifelines (sending agent, inbox, chat, receiving agent, outbox) and five numbered steps from writing the brief to reading the reply in place. A handoff between a sending agent and a receiving agent through a shared folder. 1: the sender writes one dated, addressed Markdown file into the inbox. 2: the sender, or for a laptop session a person, mentions the recipient in chat, pointing at the file. 3: the recipient reads every inbox file addressed to it before planning other work. 4: the recipient does the work and writes its reply to the outbox with the same naming, which serves as the receipt. 5: the sender reads the reply in place and routes its content: status to the operational state, decisions to escalation, plan changes to the project document. Nothing is deleted; files are archived or moved. Agent inbox: one handoff, step by step FILES CARRY THE INSTRUCTION AND THE RECORD · A CHAT MESSAGE ONLY SAYS WHERE TO LOOK FIGURE AGENT INBOX HANDOFF DRAWN BY AR LABS SHEET 1 / 1 Sending agent Inbox Chat Receiving agent Outbox 1 2 3 4 5 Then the sender routes what it read: status to the operational state, decisions to escalation, plan changes to the project's own document, each citing the reply by name. Nothing is deleted; files are archived or moved. For a laptop session, a person sends the nudge. writes a dated, addressed file mentions the recipient, points at the file nudge reads files addressed to it first writes the reply, the receipt reads the reply in place does the work
The file carries the instruction and the record; the chat message only says where to look.

Rules

The protocol is short:

  1. Read any file in the inbox addressed to you before anything else.
  2. New instructions go in the inbox; responses go in the outbox.
  3. Never delete a file unless explicitly told to. Archive or move it instead.
  4. Prefer file-based updates to anything held only in chat or session memory.
  5. Changes to another agent's own instructions or working records are requested through the inbox, never made directly. Each agent owns what it has written. Maintenance of an agent's runtime configuration by an authorised operator is a separate, documented procedure.

A chat mention is used only when assigning an action. Passive receipts ("got it", "thanks") do not mention the other agent, because a mention can start another turn for the agent mentioned, and a receipt should not cause work. One piece of work keeps to one chat thread.

Attachments and access

When a handoff needs documents, the sender copies the actual files into a named directory beside the handoff file. It never points the recipient at another agent's private workspace, which the recipient may not be able to read and which would couple the two agents' storage. The mailbox grants each participating agent write access through inherited directory permissions, and the sender checks that the recipient can open the attachments rather than assuming it.

Freshness and trust

The reference area is the shared background layer: mission, vision and other canonical documents that do not change often. It deliberately excludes any one agent's identity documents. The protocol distinguishes two kinds of material. Canonical documents are stable background. Synthesised current-state briefings are best-effort summaries assembled from whatever data was available at the time and may be incomplete. When sources disagree, the most recent explicitly dated file addressed to the agent wins, then the live company repository, then the shared copies. An agent is told not to conclude that strategy is missing just because a file it expected is absent.

Routing what a reply says

When one of our sessions reads a reply, it reads it in place and does not copy it into the company repository; the mailbox is the single record of what an agent said. The content is then routed like any other department output: results and status go to the operational state document the strategy agent reads, decisions that need a person go through the escalation workflow, and plan changes go into the relevant project's strategy or decision record. Each of those entries cites the reply file by name.

What exists today

The mailbox is in use between Claude Code sessions, Codex sessions and our server-side agents, with chat apps used for nudges. A nudge does not by itself resume an inactive agent session: a chat app connection is not proof of automatic task delivery, so work addressed to an inactive session still needs to be picked up. We intend to add a shared knowledge layer that refreshes itself automatically; it is not built.