Skip to content

Plugin protocol agents and memory

Pavel Erokhin edited this page Nov 10, 2026 · 7 revisions

Part of the Plugin protocol: how automation agents run, and what the backend keeps about each player. The agents' tools are in Client tools.

Automation agents

Since 5.5, for plugin 5.7. The chat hands work in the world (sorting chests, smelting, brewing, crafting) to an automation agent with start_task. The agent runs in wakes: each wake is an ordinary POST /api/v2/chat with mode: "task" and the task block, which the plugin opens when the task starts and every time something wakes it. No stream stays open and no tokens go while it waits.

Since 6.25, for plugin 6.26, "ender_chest" may stand in place of a chest's coordinates in chests's chests and to and in smelt's and brew's to: the player's own ender chest, through the ender chest nearest them. Older plugins skip it.

  • Message. The first wake's message is the brief from start_task. Later ones say what woke it: [player] …, [button] …, [job] …, [sub-agent] …, [parent «name»] …, [timer] …, or [plugin] …, one per line, oldest first. The plugin keeps a message within 2000 characters. Since plugin 5.14 what doesn't fit waits for the next wake instead of being cut off. Since plugin 6.22 the words of [player] and [button] stay on their line, so nothing a player wrote starts a line that reads as the plugin's.
  • Plugin notes. [plugin] … comes from the plugin itself: a wake that ended without a word, or (since plugin 6.22) a wake that broke off midway (AI_REQUEST_FAILED, NETWORK_ERROR, or the stream cut by a restart). That one goes on once, after a backoff, with the note that tools may have run, what its tools reported, and the message it had woken with. It never repeats as it was. A wake the backend never took (RATE_LIMITED, QUEUE_ERROR, a 502–504, no connection) goes again as it was, up to three times, after 15, 45, and 135 seconds, and doesn't count toward automation.max_wakes. What arrives meanwhile waits for it. Since plugin 6.35 the stream itself waits out a lost backend for 4 minutes, and an agent then keeps trying, every 15 seconds up to 5 minutes, for automation.park_hours instead of three times; a wake that had started goes on with the note above.
  • Sub-agent reports. When a sub-agent ends, the plugin wakes the agent that started it with [sub-agent] «name» (kind, id) finished: <summary> or stopped: <why> (cancelled, interference, an error, the time or wake limit, the quota, the player leaving). Since plugin 5.14 a second line follows when the sub-agent's tools did something: What its tools reported: …, the plugin's own English record of what was crafted, smelted, brewed, collected, moved, or put on an anvil, with counts and where it went (at most six, newest last), so the parent can act on facts rather than the summary alone. Older backends read it as text.
  • Ending. Since plugin 5.14, stopping an agent (/allay cancel, cancel_task, interference, the limits) also cancels its wake if one is out, and its tools refuse to act for it from then on. Since plugin 6.22 every wake checks again that the kind is switched on, the player still has the permission, and still agrees to the notice, and ends the agent otherwise. Erasing a player's data stops their agents first.
  • End of a wake. The agent ends every wake with wait or finish. Its final text, often empty, is a note for its own next wake: the backend records it and the plugin doesn't show it. An empty final text is not an error in task mode: done comes with answer: "".
  • Steps. A wake gets up to MAX_TASK_STEPS model steps (32 by default since 6.9), against MAX_AGENT_STEPS (26) for a question.
  • Tools. A wake gets the client tools the plugin offers minus operator tools, write_book, and get_nearby_players. It gets start_task, message_task, and cancel_task only at depth 1 (before server 5.12, only start_task). Server tools: exact_calculations only, no search_web, no memories. The prompt still shows the player's memories, read-only.
  • Prompt. minecraft-task.md plus the agent's name, kind, and depth, and the player. Since 6.31 task.card (≤ 3000 characters, plugin 6.35) goes in as “Your task as the plugin keeps it”: the brief, the job, the sources, what it waits for, what its tools reported, the open question. It outlives the agent's thread, so the agent carries on after a restart, a long wait, or a cleared session.
  • Its thread's lease. Since 6.31 task.keep_until (epoch milliseconds) says how long the agent may still need its thread, as it may wait for items. The thread then lives until then after the wake, at least TASK_CHAT_TTL_SECONDS and at most TASK_CHAT_MAX_KEEP_SECONDS (7 days).
  • Coming back (plugin 6.35, backend 6.31). An agent doesn't end when its player leaves or the server stops: the plugin saves it in the player's work state, PUT /api/v2/users/{user_id}/workstate, with its job, and brings it back from GET when the player joins again, under the same task.id, so its thread and reservations go on.
  • Waiting for items (plugin 6.35). wait_for_items parks an agent until its sources hold what it named. A parked agent holds none of the player's automation.max_tasks slots, its time doesn't count toward automation.max_minutes, and it wakes with [job] the items you waited for are here: ….
  • Depth. The chat is depth 0. A task the chat starts is 1, a task started by a task is 2 and can't start another.
Mode Gets Never gets
ask start_task, message_task, cancel_task say, wait, finish, pick_blocks, chests, smelt, brew, craft
public ask – all automation tools
task say, wait, finish, wait_for_items, sources, pick_blocks, chests, smelt, brew, craft; start_task, message_task, cancel_task at depth 1 operator tools, write_book, get_nearby_players, search_web, memories
askx – all automation tools

Conversation memory

The backend keeps these per tenant and user_id (since 6.0, before that per user_id alone):

  • The session. Whole exchanges verbatim (since 5.5 with the tool calls and their results, whole) plus a summary of everything older. The backend folds all but the newest 12 000 tokens (2 to 30 exchanges) into the summary with the model after an answer once the session passes about 32 000 tokens or 100 exchanges, and before an answer past 42 000. A quiet session isn't folded: it expires. A session lives CHAT_TTL_SECONDS after the last question, 30 days by default since 6.9 (a day before). /askx requests land in it as one short exchange (the request and the commands or the refusal), so a later /ask knows what was done. Since 6.26 a question reads earlier results of tools that see the player's things and surroundings (find_item, get_recipes, look_at, and more) with an earlier note that they may be out of date, and an earlier inventory or get_player_status as that note alone, so the model reads them again instead of answering from them. The session itself keeps them whole, and an automation agent reads its own thread unmarked.
  • The server's public thread (since 3.0). Public questions with a server.id go to the tenant's thread for that id instead of the asker's session, each question prefixed with the asker's name in brackets, so a follow-up from another player continues the talk. It folds like a session and lives 2 hours after the last question (PUBLIC_CHAT_TTL_SECONDS). Without server.id a public question uses the asker's session.
  • A task's thread (since 5.5). Each wake of an automation agent reads and extends its own thread under the player and task.id: the wake's message and the agent's final text, or (waiting) when it ended without one. It folds like a session and lives 2 hours after the last wake (TASK_CHAT_TTL_SECONDS). The player's session never sees it.
  • Memories. Lasting facts and, since 6.9, places the model saves with memories, kept in MongoDB until the player deletes them or, since 6.0, 365 days after their last question. The 30 newest facts without a place go into the system prompt with their ids, with a count of the rest. Since 6.27 a memory has kind, title, tags, and pinned, a place category and radius. The prompt also lists every pinned memory and the 5 places nearest the player within 256 blocks, and memories takes update.
  • Deaths and state (since 6.9). The newest DEATHS_MAX (100) deaths and the plugin's state for the player (time zone, settings, goals), 365 days after the last question.
  • Agents (since 6.31). The player's automation agents on each server, so they go on after a restart or a rejoin: 30 days after their last change, or until they end.
  • The player's name (since 6.4). player.name, user_id, and player.op from the player's last question, so the admin panel can name them, kept 730 days after the last question (400 before 6.9).

Since 6.9 every one of these is sealed in MongoDB with AES-256-GCM (a random 96-bit IV per value), under a key derived with HMAC-SHA256 from the backend's SECRETS_KEY (or /data/secrets.key), as are traces' prompts, answers, and tool data. A dump or a backup alone reads none of it. Data written in the clear before 6.9 still reads, and goes as it expires.

Endpoints for the plugin's /allay new, /allay memory [text], /allay forget, and (since 6.0) /allay privacy, and (since 6.1) the consent a player gives before their first question, all with Authorization:

Request Answer
GET /api/v2/users/{user_id} Since 6.0. 200 with everything kept about the player: { user_id, tenant, pseudonym, name, memories, deaths, state, consent, session: { summary?, messages }, outcomes, tasks: { <task id>: session }, runs: [{ at, kind, model, input_tokens, output_tokens, cost, duration_ms, result }], retention } (deaths and state since 6.9)
DELETE /api/v2/users/{user_id} Since 6.0. 200 { "erased": true, "memories": 3, "deaths": 7, "runs": 12, "traces": 40 }: memories, deaths and state (since 6.9), agents (since 6.31), open export links, the consent (since 6.1), the name (since 6.4), session, pending outcomes, and agents' threads go. The player's runs keep only numbers under erased, and their traces go. The tenant's public thread expires by itself within 2 hours
POST /api/v2/users/{user_id}/export Since 6.9. 200 { "url": "<PUBLIC_URL>/api/v2/exports/<token>", "expires_at": "ISO-8601" }: a link to the player's copy, good for 24 hours and any number of downloads. The token is 32 random bytes, and the backend keeps only its SHA-256
GET /api/v2/exports/{token} Since 6.9, without Authorization: the token is the key. 200, a JSON attachment with what GET /api/v2/users/{user_id} returns. 404 for a wrong, expired, or erased link, the same for each
POST /api/v2/users/{user_id}/deaths with { "at": ms, "world", "dimension", "x", "y", "z", "cause"?, "killer"?, "killer_name"?, "message"? (≤ 256), "level", "kept_inventory"?, "drops"?: { id: count } (≤ 20 kinds), "experience"? } Since 6.9. The plugin reports a death as it happens: 200 { "saved": true }. Ids are as the game gives them (minecraft:lava), and at more than a day ahead is 400. A death at an at already kept for the player is a no-op answering 200, so a retry is safe. The newest DEATHS_MAX stay
GET /api/v2/users/{user_id}/state Since 6.9. 200 { "state": { "timezone"?, "settings"?, "goals"? } | null, "updated_at": "ISO-8601" | null }
PUT /api/v2/users/{user_id}/state with { "timezone"?: "≤ 64", "settings"?: { … }, "goals"?: [ … ≤ 100 ] } Since 6.9. Replaces the player's state whole, at most 32 KB of JSON. The backend checks the shape, not what settings and goals hold. 200 with the same body as GET
GET /api/v2/users/{user_id}/workstate?server_id=… Since 6.32, and as /agents since 6.31, which still answers for plugin 6.35. The work state: every agent of the player that does work on that server. 200 { "agents": [ { … } ], "updated_at": "ISO-8601" | null }: the player's agents on that server as the plugin saved them, oldest first, [] for none. One tenant may serve several servers, so each keeps its own
PUT /api/v2/users/{user_id}/workstate with { "server_id", "agents": [ { … } ≤ 16 ] } Since 6.32, and as /agents since 6.31. Replaces the server's agents whole, at most 64 KB of JSON; an empty list forgets them. The backend checks the shape, not what an agent holds, and keeps it sealed. 200 { "saved": n }, or 403 CONSENT_REQUIRED for a list that isn't empty
DELETE /api/v2/users/{user_id}/session 200 { "cleared": true }. Memories stay
GET /api/v2/users/{user_id}/consent Since 6.1. 200 { "consent": { "version": 1, "accepted_at": "ISO-8601" } }, or { "consent": null } when the player hasn't agreed. Since 6.9 the consent adds hash and revision when it has them and always age_confirmed (false when the player wasn't asked), and the answer adds revision, the privacy policy's current revision (a date, also in /api/health): the plugin hashes its notice with it and asks again when the hash differs from the stored one
PUT /api/v2/server with { id, name?, motd?, software?, version?, plugin_version?, address?, port?, loader?, side? } Since 6.7. The plugin registers its server at start. name (2–32 letters, digits, spaces, or . _ ' -) belongs to one server on the backend: 409 NAME_TAKEN when another tenant's server holds it, and a server of the same tenant takes it over. 200 { "registered": true, "name" }
PUT /api/v2/users/{user_id}/privacy with { "full": true } Since 6.5. The player turned full privacy on (true) or off: on, the admin panel forgets their name, UUID, and face at once: 200 { "full": true, "forgotten": true }. Off changes nothing until the next question without player.private. The plugin keeps the switch
PUT /api/v2/users/{user_id}/consent with { "version": 1, "hash"?: "64 hex", "age_confirmed"?: true, "age_band"?: "16_17" } Since 6.1. Records that the player agreed to the plugin's notice of that version (a whole number, 1–1000), replacing an older agreement whole: 200 { "consent": { "version", "hash"?, "revision", "age_confirmed"?, "accepted_at" }, "revision" }. Since 6.9 hash is the SHA-256 (hex) of the English notice texts the plugin showed, joined by newlines, a newline, and the revision. revision is the policy's revision then. age_confirmed says the player is old enough to agree where they play, and age_band is the age group they picked (under_13, 13, 14_15, 16_17, 18_plus), which plugin 6.7 asks every player. An agreement goes with the player 730 days after their last question
DELETE /api/v2/users/{user_id}/consent Since 6.1. 200 { "withdrawn": true }, or false when there was none. Since 6.9 it also erases what the agreement covered, memories and places, deaths, state, agents (since 6.31), export links, the session, pending outcomes, and agents' threads, and answers { "withdrawn", "memories", "deaths" } with the counts. The record stays, marked withdrawn_at in the player's copy, as proof, and GET answers null until the player agrees again. Before 6.9 what was kept stayed until erased
GET /api/v2/users/{user_id}/memories 200 { "memories": [{ "id": "k3f9a", "text": "…", "kind": "fact" | "preference" | "goal" | "place", "title"?, "tags": [], "pinned": false, "category"?, "place"?: { "x", "y", "z", "dimension", "world"?, "radius"? }, "created_at": "ISO-8601", "updated_at"? }] }, oldest first. place since 6.9, the rest since 6.27
POST /api/v2/users/{user_id}/memories with { "text": "3–500 chars", "title"?, "tags"?, "kind"?, "pinned"?, "category"?, "place"?: { "x", "y", "z", "dimension", "world"?, "radius"? } } 200 { "memory": { … } }, else 409 MEMORY_FULL at MEMORY_MAX (200 since 6.9, 30 before), 409 MEMORY_PINS_FULL past 20 pinned, or 400 for other text. Since 5.1. place since 6.9, for the plugin's note buttons. The rest since 6.27, and text up to 500 characters (200 before)
PATCH /api/v2/users/{user_id}/memories/{id} with any of text, title (empty removes it), tags (replaces them), kind, pinned, category, place (null removes it) Since 6.27, for the plugin's memory window. 200 { "memory": { … } }, 404 MEMORY_NOT_FOUND, or 409 MEMORY_PINS_FULL
DELETE /api/v2/users/{user_id}/memories 200 { "deleted": 4 }: all of them
DELETE /api/v2/users/{user_id}/memories/{id} 200 { "deleted": 1 }, or 404

Next: Billing and the admin panel

Clone this wiki locally