AirMemo

The install desk

Connect an agent to your org memory.

Three rails carry a memo, and the first one is a base URL. Point an API-routed client at the gateway and its model traffic is governed: the gateway resolves the memos in force for the person behind the token, puts them in front of the call as a marked system block, and mints the receipt on the server. There is one exception, and the page names it rather than implying it away: when the memos cannot be resolved, the default is a bare request and a header saying so, and an org that sets block mode gets a typed 503 instead. An MCP (Model Context Protocol) client reads the same context from one endpoint with an org API token, and no install. Where a client exposes lifecycle events, the hook pushes the memo at the next turn, and a browser chat window is covered by the browser sensor, an add-on in test. Installing is a decision your company makes, so the credential comes from an owner or administrator, and nothing is written to a developer's tools without that developer running the snippet.

01 · The base URL

Point the base URL at the gateway

Any client that speaks the Anthropic Messages API, OpenAI chat-completions, or the OpenAI Responses API can be governed without a plugin: the gateway serves /v1/messages, /v1/chat/completions and /v1/responses. The client keeps its own provider key and its own request; the only change is where the request is sent. The token travels in the path, so the client's own x-api-key header stays its provider key and keeps working untouched.

Codex CLI is the one client that needs a provider block rather than an environment variable: it speaks only the OpenAI Responses API, so pointing it at a base URL means writing a provider block, not setting one environment variable the way the two clients below are. That write belongs to the design-partner build of the hook, and there is no public installer to download: nothing on this page resolves as one. For a design partner, airmemo-hook install --gateway writes the provider block into ~/.codex/config.toml inside a marked section it owns, and leaves every other key and comment in that file alone; an existing model_provider is retargeted only when asked with --force. Codex appends /responses to whatever base URL it is handed, so the block's value ends in /v1, and the request arrives on /v1/responses. The memo block rides the field that wire keeps for it, the request's own top-level instructions, so the vendor still receives a normal request. No provider key is named in the block: the token in the path is what authorises the call. Without that build, Codex still reads the same context over MCP: codex mcp add in section 04 below needs no install at all.

Anthropic-shaped client

export ANTHROPIC_BASE_URL="https://<gateway>/k/<token>"
export ANTHROPIC_API_KEY="<the provider key the client already uses>"

OpenAI chat-completions client

export OPENAI_BASE_URL="https://<gateway>/k/<token>/v1"
export OPENAI_API_KEY="<the provider key the client already uses>"

Codex CLI, written by the design-partner installer

# >>> airmemo gateway (managed by "airmemo-hook install --gateway"; edit inside the markers, not around them)
model_provider = "airmemo"

[model_providers.airmemo]
name = "AirMemo"
base_url = "https://<gateway>/k/<token>/v1"
wire_api = "responses"
# <<< airmemo gateway

The gateway resolves the memos in force for the person behind the token, adds them as a marked system block ahead of the call, and streams the vendor's response back untouched. It stores neither the request body nor the response body, and it holds no model-vendor credential of its own: the key is forwarded as the client sent it. The path, not the body, decides the protocol, so an Anthropic request that carries a field nobody expected is still an Anthropic request.

Two response headers say what happened, so a governed call is distinguishable from an ungoverned one without reading logs: x-airmemo-carried carries how many memos went out with the request, and x-airmemo-policy carries ok, stale, unavailable, or unknown. Alert is the default when the memos cannot be resolved: the request is forwarded bare and the header says so. An org that wants the other behaviour sets block mode on the Gateway page in the console, and the request is then refused with 503 and airmemo_policy_unavailable instead of being sent. The org's mode is read before the memos are, so a cold or half-read policy store cannot quietly turn a block org into an alert one; if the mode itself cannot be read, the request is refused too and the header says unknown. Either way what is at stake is one outgoing request, never an agent's turn. A body that cannot carry the memo is the one other refusal, and it is about shape rather than policy: alert forwards it bare and marks the response x-airmemo-injection: unsupported, and block answers 400 with airmemo_body_not_json or airmemo_body_unsupported.

An owner or administrator mints each person's token on the Gateway page in the console, one token per active person, and an org-wide token is refused on this rail because a receipt has to name a person. A command-line tool that cannot take a base URL can point its hook at the same gateway and resolve policy in one place instead of two.

02 · The endpoint

One endpoint, one token, six tools

The server speaks MCP over Streamable HTTP. It exposes six tools:search_context, get_decisions, get_memo, get_manual, whoami, and propose_context. Five are reads. The sixth files a draft into the approval flow and cannot publish anything by itself.

Endpoint

https://api.airmemo.com/mcp

Every request carries the org token in the Authorization header. A request with no token, or with an unknown, expired, or revoked one, is rejected with HTTP 401 before any tool runs. The token is sent in the header only; the server stores its hash, never the token itself.

03 · The token

Five scopes, minted in the console

An owner or administrator creates the token in the console (Settings, then API tokens). It is scoped, short-lived, revocable, rate-limited, and every call is logged server-side. The console offers five scopes: memos:read for reads, memos:create for propose_context, memos:revoke to withdraw a queued memo, audit:read for the org audit trail, and gateway:inject for the token a gateway carries on one person's behalf. A token minted with memos:read alone cannot write.

Keep the token out of files that travel with source. Every client below reads it from its own environment or prompt, and the token page in the console carries the same snippets so the token has an obvious next step.

04 · Add the server

Pick your client

Each block is the client's own configuration, with the token kept in the client's env-var or prompt mechanism. Run or paste it yourself, then restart the client.

Claude Code

one command

claude mcp add --transport http airmemo \
  https://api.airmemo.com/mcp \
  --header "Authorization: Bearer <org api token, scope memos:read>"

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "airmemo": {
      "url": "https://api.airmemo.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AIRMEMO_API_TOKEN}"
      }
    }
  }
}

Cursor expands ${env:AIRMEMO_API_TOKEN} from the environment the editor was started with. The console token page also builds a one-click install link for this client.

VS Code (Copilot)

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "airmemo-token",
      "description": "AirMemo org API token",
      "password": true
    }
  ],
  "servers": {
    "airmemo": {
      "type": "http",
      "url": "https://api.airmemo.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:airmemo-token}"
      }
    }
  }
}

VS Code prompts for the token once and stores it masked. Use the portable .mcp.json shape (mcpServersinstead of servers) when the config needs to travel with the repository.

Codex CLI

~/.codex/config.toml

# ~/.codex/config.toml
[mcp_servers.airmemo]
url = "https://api.airmemo.com/mcp"
bearer_token_env_var = "AIRMEMO_API_TOKEN"

codex mcp add airmemo --url https://api.airmemo.com/mcp registers the server; the bearer variable is declared in config.toml.

Gemini CLI

one command

gemini mcp add --transport http \
  --header "Authorization: Bearer <org api token>" \
  airmemo https://api.airmemo.com/mcp

The same entry in settings.json uses httpUrl with a headers object, so a project can keep the value out of the file.

Any other MCP client

npx add-mcp

npx add-mcp https://api.airmemo.com/mcp \
  --name airmemo --bearer-token-env AIRMEMO_API_TOKEN

The token stays in the environment; the command line never carries it. Per-vendor config files and the events each adapter wires are in the docs.

Just exploring? Agents can read the public docs server without a token: https://api.airmemo.com/mcp/docs.

05 · Enrollment

Who says yes, and what enrollment turns on

The connection is approved where the credential is issued. An owner or administrator mints the token in the console and hands it to the requester; that is the approval, and it binds the token to one organization, so it cannot read another org's context.

Delivery beyond one client is the hook: it rides the lifecycle events a client already exposes, so an enrolled agent is handed a memo at its own next turn instead of the person pasting it by hand. Enrolling an agent lands it pending; it consumes nothing until an owner or administrator approves it in the console. Approval consumes an Agent Cap slot and, when it is that person's first active agent, their Seat; a live gateway credential that person holds does the same. Another agent for the same person is not another Seat. Revoking one agent frees its Agent Cap slot; the Seat frees when the person holds neither an active agent nor a live gateway credential. The install commands are in the docs.

A browser chat window takes no hook and no base URL. The browser sensor is a first-party extension for the AI chat surfaces it names: it inserts the memo into the composer and reports which surface it ran on, with the host reduced to a keyed digest rather than the hostname itself. Where it is not installed, that traffic is unobserved, and nothing here counts it as covered.

Nothing here installs itself. AirMemo does not write a client's MCP configuration, and the only tool that writes anything, propose_context, files a pending draft that a person approves in the console before it can be delivered.

06 · The one-request path

Handing this to your administrator

At a large company the product of a suggestion is an approval conversation, not an install. The requester kit answers the questions that conversation raises, in the order it raises them, with a source line under each answer: what AirMemo is, what leaves a developer machine, what is stored and for how long, the credential and its limits, what an administrator approves, and the security documents that are public today.

Evaluating first, with no procurement step? Open the console, create an org, and mint a token. The free tier is real and needs no conversation.