agentleFS
MemoAir-labsMemoAir-labs/Airlink/docs/agents.md

Airlink

AGENTS.md48 starsChanged 19 days agoMITView on GitHub

Agents in AirLink are flat: you say who each one is (a name, a role, instructions, tags), and the room routes work to them. There is no orchestrator agent. Settings → Agents adds, edits and removes agents; each agent has its own page. They are saved to .airlink/agents.json. A fresh install has one, Assistant. Each entry has this shape (agentConfigSchema in packages/agents/src/index.ts): AirLink runs no agent loop of its own. A harness runs the agent. - Pi (@earendil-works/pi-agent-core, MIT) runs…

  • Reads credentials
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repositoryOne other file it gives its agents.

The file

We split this agents.md into the rules it gives an agent

8 rules. About 0 are common, 3 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    ACP harnesses: run as child processes over the Agent Client Protocol (acpHarness).

    line 47
  2. Very specific:

    Mentions: Every agent @-mentioned answers.

    line 75
  3. Very specific:

    Tags: If exactly one agent carries one of the message's tags, it answers.

    line 77
  4. Very specific:

    read_live_file: read a file someone uploaded to the channel.

    line 105
  5. Very specific:

    run_code and schedule_runner: run a Python or Node script in a sandboxed runner window everyone sees, with the channel's files …

    line 111
  6. Distinctive:

    every live object in the room, so the agent knows what ids to use.

    line 132
  7. Distinctive:

    Before a write, the bridge asks the decision node whether the note will matter in a later conversation and declines it if not.

    line 148
  8. Distinctive:

    Every other channel is invite-only.

    line 157

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
agents.md

Agents

Agents in AirLink are flat: you say who each one is (a name, a role, instructions, tags), and the room routes work to them. There is no orchestrator agent.

Adding an agent

Settings → Agents adds, edits and removes agents; each agent has its own page. They are saved to .airlink/agents.json. A fresh install has one, Assistant.

Each entry has this shape (agentConfigSchema in packages/agents/src/index.ts):

FieldDefaultMeaning
idrequiredStable id. Also the memory folder name.
namerequiredShown in chat; said aloud to address it in a huddle.
role""One line. Routing reads it.
instructions""The agent's own system prompt: what it is for, how it works, its tone.
tags[]Labels routing can match on (see the note under Routing).
access"write""suggest" makes every change a suggestion a person accepts.
harness"pi""pi", or the id of an ACP harness turned on in Settings.
modelthe default"<provider>/<model id>" Pi answers on, e.g. anthropic/claude-haiku-5-5.
memoryDir<memory root>/<id>An OKF folder. Two agents given one folder share memory.
voice{ speed: 1 }A provider voice id (empty picks a distinct one) and a speed from 0.8 to 1.2.
[
  {
    "id": "analyst",
    "name": "Ada",
    "role": "Builds and checks spreadsheets and numbers.",
    "instructions": "Show your working in the sheet. Never invent figures.",
    "tags": ["numbers"],
    "access": "suggest",
    "harness": "pi",
    "model": "anthropic/claude-haiku-5-5"
  }
]

Harnesses

AirLink runs no agent loop of its own. A harness runs the agent.

  • Pi (@earendil-works/pi-agent-core, MIT) runs in process on your LLM key (piHarness). This is the default and needs nothing else.
  • ACP harnesses run as child processes over the Agent Client Protocol (acpHarness). detectHarnesses looks for these on your PATH and Settings offers the ones it finds:

    HarnessFound byStarted as
    Claude Codeclaudenpx -y @agentclientprotocol/claude-agent-acp@0.93.0
    Codexcodexnpx -y @agentclientprotocol/codex-acp@2.2.2
    Gemini CLIgeminigemini --acp
    opencodeopencodeopencode acp

    An ACP harness gets the room's tools from a loopback MCP server the bridge serves (serveRoomMcp). Its own tools (shell, file writes on your machine) are refused. One that exits mid-turn is reported in the channel and restarted on the next message. The first start of a Claude Code or Codex agent waits while npx fetches the adapter.

Turn a harness on in Settings, then set an agent's harness to its id (claude, codex, gemini, opencode).

node packages/bridge/scripts/smoke.ts drives Pi and an ACP harness against a running live-server (LIVE_URL, LIVE_JWT_SECRET, ANTHROPIC_API_KEY).

Routing

Each channel has a reply mode in its header. Auto follows the steps below. On mention skips steps 2–4: an agent answers only when @-mentioned, and in a huddle only when named.

Who answers a chat message:

  1. Mentions. Every agent @-mentioned answers. A message that mentions only people is left to them.
  2. Tags. If exactly one agent carries one of the message's tags, it answers. AirLink's chat does not tag messages yet, so today this step is skipped; routeMessage supports it for hosts that do.
  3. The decision node. Otherwise, with two or more candidates, the decision node picks by role. A confident pick (≥ 0.6) answers. A confident "none" means nobody answers, which in chat is only a message plainly addressed to another person; small talk or a question no role covers goes to the closest agent. An unsure pick still answers and is told it was unsure.
  4. Fallback. With no pick, the first agent in the channel answers.

Who answers a line said in a huddle: the agents it names, else the one the decision node is sure of by role. There is no fallback, since most of a call is people talking to each other.

A room event that is not a message (an edit once the person stops, a comment) reaches agents only when the decision node judges it deserves a turn (≥ 0.5).

The routing code is routeMessage, routeSpoken and deservesTurn in @memo-air/agents.

Tools

Each turn an agent gets:

  • The room's tools (roomTools in @memo-air/tools): create, read and edit docs, sheets, canvases and slides (create_live_doc, edit_live_sheet, read_live_canvas, …), comment on docs, open and drive the shared browser and desktop (open_live_browser, act_live_browser, open_live_desktop, act_live_desktop, …), and read or speak in a huddle (read_live_room, speak_in_live_room).
  • arrange_windows: list the channel's windows and open, close, minimize, maximize, restore or bring them to front. Deleting is not offered; that stays with people.
  • read_live_file: read a file someone uploaded to the channel. Text and code as they are, a PDF's text page by page, an .xlsx as CSV per sheet.
  • search_room: keyword search over the channel's whole message history and the text of its docs, sheets, slides, canvases and uploaded PDF, .xlsx and text files. It returns the best passages with where they are; any word may match and passages matching more rank first.
  • read_chat: the channel's messages in order, around a message id or just before one.
  • run_code and schedule_runner: run a Python or Node script in a sandboxed runner window everyone sees, with the channel's files read-only in /files; an index.html written to /out becomes a live dashboard, and a schedule re-runs it. The script can call the agent's own room tools: from room import room in Python or import { room } from "./room.mjs" in Node, then room.search_room(query="…") and so on, each returning the tool's text. Calls go over a socket to the runner's control server and back to AirLink, which runs them as the agent that wrote the code; the jail's network fence is unchanged. At most 50 calls a run, and never run_code or schedule_runner. A scheduled re-run calls them again, so a dashboard pulls live room data.
  • recall_memory and remember, below.

Context

An agent's prompt is rebuilt every turn from what is stored, so nothing is lost when AirLink restarts and every agent sees the same channel:

  • the channel's running summary, rewritten by the router's small model in the background once about 6,000 characters of chat pile up past it, citing message ids;
  • up to three of the agent's own memories that share words with the message;
  • the channel's five latest messages, from every person and agent;
  • the message or event it is answering;
  • every live object in the room, so the agent knows what ids to use.

Everything older is reached on demand with search_room and read_chat. The search index (airlink_search_chunks) is derived: rebuilt from the docs after each save and at start, and emptied with the channel or object it came from.

Memory

Each agent remembers in a folder of OKF documents: Markdown with YAML frontmatter where type is the one required field (title, description, resource, tags and timestamp when the agent wrote it). index.md lists every entry in one line; log.md records every write.

  • The folder is <memory root>/<agent id> unless the agent sets memoryDir. The memory root defaults to .airlink/memory; Settings can point it at an Obsidian vault.
  • recall_memory searches by words over title, description, tags and body. remember writes a new note and never overwrites one (a second note with the same title gets -2).
  • Before a write, the bridge asks the decision node whether the note will matter in a later conversation and declines it if not. A decision that fails saves.
  • Hand-written notes are read too: nested folders, other types, no frontmatter at all.

Memory belongs to the agent across channels. Edit, delete or version the folder as you like.

Channels and membership

  • #general is open: every person and every agent is in it.
  • Every other channel is invite-only. Its creator is in it and adds people and agents from the members dialog. Others can ask to join.
  • An agent that is not a member of a channel does not answer there and does not join its huddle.

Access

An agent's token is signed per object and capped at its access. With suggest, every change it makes is a suggestion. With write, an edit to a sheet cell, canvas shape or slide element a person wrote still lands as a suggestion. Prices, dates and commitments a person must own belong in suggestions.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.