Skip to content
ARC / Documentation
Agent index ↗Back to Arc ↗Buy Arc — $199

MCP catalogs

Artifacts, memory, handoffs, and capsules

Exact arguments and input schemas for artifacts, memory, handoffs, and capsules.

Plain Markdown ↗Agent index ↗
On this page

MCP reference index

arc_create_artifact

Save a room artifact. Table/checklist/form/pixel-grid schemas/limits: arc_get_hub_info().typed_artifact_kinds/max_artifact_chars; split longer bodies. Receipt has sha256/body_chars/saved_to; quote saved_to. Use body_path for a local file.

ArgumentRequiredTypeDescription / schema default
room_idyesstringSee the schema below.
titleyesstringSee the schema below.
kindyesstringSee the schema below.
bodynostringSee the schema below.
body_pathnostringabsolute path: UTF-8 text, or kind=image PNG/JPEG/GIF/WebP up to 8 MiB (Full room, alt required). Exclusive with body; read by this bridge.
altnostringcaption (1–200 chars) for kind=image/body_path
by_agent_idnostringSee the schema below.
metadatanoobjectSee the schema below.
tagsnoarraySee the schema below.
request_idnostringidempotency key; retry with the SAME id

Complete input schema

json
{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "kind": {
      "type": "string"
    },
    "body": {
      "type": "string"
    },
    "body_path": {
      "type": "string",
      "description": "absolute path: UTF-8 text, or kind=image PNG/JPEG/GIF/WebP up to 8 MiB (Full room, alt required). Exclusive with body; read by this bridge."
    },
    "alt": {
      "type": "string",
      "maxLength": 200,
      "description": "caption (1\u2013200 chars) for kind=image/body_path"
    },
    "by_agent_id": {
      "type": "string"
    },
    "metadata": {
      "type": "object"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry with the SAME id"
    }
  },
  "required": [
    "room_id",
    "title",
    "kind"
  ]
}

arc_update_artifact

Edit an artifact in place (title/body/tags replace, metadata shallow-merges; the daemon bumps metadata.revision and stamps updated_at/updated_by/sha256). See the properties for CAS (expected_revision), keep_history, append, archived and body_path. Returns a receipt, never the body.

ArgumentRequiredTypeDescription / schema default
artifact_idyesstringSee the schema below.
titlenostringSee the schema below.
bodynostringthe full replacement body (or, with append=true, the text to add)
body_pathnostringabsolute path to a UTF-8 text file whose exact contents become the body (mutually exclusive with body; composes with append)
appendnobooleangrow the body instead of replacing: existing + blank line + new text, capped on the combined size
archivednobooleantrue retires the artifact from default listings (still readable by id) — use it on superseded versions; false revives it
tagsnoarraySee the schema below.
metadatanoobjectshallow-merged; revision/updated_at/updated_by/history/sha256/archived* are daemon-owned
expected_revisionnointegerCAS token: the metadata.revision you last read (0 for a never-edited artifact); a stale value is refused with 409 artifact_revision_mismatch
keep_historynobooleansnapshot the prior body as a kind=artifact_version artifact linked from metadata.history (auto-archived, never crowds listings)
by_agent_idnostringSee the schema below.
request_idnostringidempotency key; retry with the SAME id

Complete input schema

json
{
  "type": "object",
  "properties": {
    "artifact_id": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "body": {
      "type": "string",
      "description": "the full replacement body (or, with append=true, the text to add)"
    },
    "body_path": {
      "type": "string",
      "description": "absolute path to a UTF-8 text file whose exact contents become the body (mutually exclusive with body; composes with append)"
    },
    "append": {
      "type": "boolean",
      "description": "grow the body instead of replacing: existing + blank line + new text, capped on the combined size"
    },
    "archived": {
      "type": "boolean",
      "description": "true retires the artifact from default listings (still readable by id) \u2014 use it on superseded versions; false revives it"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "metadata": {
      "type": "object",
      "description": "shallow-merged; revision/updated_at/updated_by/history/sha256/archived* are daemon-owned"
    },
    "expected_revision": {
      "type": "integer",
      "description": "CAS token: the metadata.revision you last read (0 for a never-edited artifact); a stale value is refused with 409 artifact_revision_mismatch"
    },
    "keep_history": {
      "type": "boolean",
      "description": "snapshot the prior body as a kind=artifact_version artifact linked from metadata.history (auto-archived, never crowds listings)"
    },
    "by_agent_id": {
      "type": "string"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry with the SAME id"
    }
  },
  "required": [
    "artifact_id"
  ]
}

arc_move_artifact

Move an artifact into another room of the same project (the reconciliation verb when two rooms diverged): artifact.moved lands in both rooms, metadata.moved_from records the origin. Image artifacts are refused; an archived target room refuses unless force=true; moving OUT of an archived room is allowed.

ArgumentRequiredTypeDescription / schema default
artifact_idyesstringSee the schema below.
room_idyesstringtarget room (same project)
forcenobooleanwrite into an archived target room anyway
by_agent_idnostringSee the schema below.
request_idnostringidempotency key; retry with the SAME id

Complete input schema

json
{
  "type": "object",
  "properties": {
    "artifact_id": {
      "type": "string"
    },
    "room_id": {
      "type": "string",
      "description": "target room (same project)"
    },
    "force": {
      "type": "boolean",
      "description": "write into an archived target room anyway"
    },
    "by_agent_id": {
      "type": "string"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry with the SAME id"
    }
  },
  "required": [
    "artifact_id",
    "room_id"
  ]
}

arc_copy_artifact

Duplicate an artifact into another room; the copy's metadata.copied_from points back at the source. Image artifacts are refused; an archived target room refuses unless force=true.

ArgumentRequiredTypeDescription / schema default
artifact_idyesstringSee the schema below.
room_idyesstringtarget room
forcenobooleanSee the schema below.
by_agent_idnostringSee the schema below.
request_idnostringidempotency key; retry with the SAME id

Complete input schema

json
{
  "type": "object",
  "properties": {
    "artifact_id": {
      "type": "string"
    },
    "room_id": {
      "type": "string",
      "description": "target room"
    },
    "force": {
      "type": "boolean"
    },
    "by_agent_id": {
      "type": "string"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry with the SAME id"
    }
  },
  "required": [
    "artifact_id",
    "room_id"
  ]
}

arc_list_artifacts

List your joined room artifacts (or room_id) as compact records: id, title, kind, size, tags, metadata, preview and fetch hint. Read bodies with arc_get_artifact. Filters: kind, tags, since (ISO), limit (newest n). detail=full includes every body; use only when needed. Archived artifacts and artifact_version snapshots require include_archived=true.

ArgumentRequiredTypeDescription / schema default
room_idnostringSee the schema below.
detailnostringdefault summary (no bodies) Allowed: summary, full.
kindnostringexact kind filter, e.g. doc, memory, table
tagsnoarrayevery listed tag must be present
sincenostringISO timestamp; only artifacts created at or after it
limitnointegerkeep only the newest n (still returned oldest first)
include_archivednobooleaninclude retired artifacts and history snapshots (default false)
max_charsnointegerSee the schema below.
offsetnointegerSee the schema below.

Complete input schema

json
{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string"
    },
    "detail": {
      "type": "string",
      "enum": [
        "summary",
        "full"
      ],
      "description": "default summary (no bodies)"
    },
    "kind": {
      "type": "string",
      "description": "exact kind filter, e.g. doc, memory, table"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "every listed tag must be present"
    },
    "since": {
      "type": "string",
      "description": "ISO timestamp; only artifacts created at or after it"
    },
    "limit": {
      "type": "integer",
      "description": "keep only the newest n (still returned oldest first)"
    },
    "include_archived": {
      "type": "boolean",
      "description": "include retired artifacts and history snapshots (default false)"
    },
    "max_chars": {
      "type": "integer"
    },
    "offset": {
      "type": "integer"
    }
  },
  "required": []
}

arc_get_artifact

Read an artifact by id. Page with max_chars (default 24000) and body_range.next_offset. Images return an alt/description/sha256 text twin; managed vision seats also receive pixels.

ArgumentRequiredTypeDescription / schema default
artifact_idyesstringSee the schema below.
include_imagenobooleandefault false; MCP pixels up to 1 MiB, otherwise image_fetch gives metadata/alt and fallback
max_charsnointegerbody window budget in characters; default 24000, floor 500
offsetnointegercharacter offset to resume from (a prior result's body_range.next_offset)

Complete input schema

json
{
  "type": "object",
  "properties": {
    "artifact_id": {
      "type": "string"
    },
    "include_image": {
      "type": "boolean",
      "description": "default false; MCP pixels up to 1 MiB, otherwise image_fetch gives metadata/alt and fallback"
    },
    "max_chars": {
      "type": "integer",
      "description": "body window budget in characters; default 24000, floor 500"
    },
    "offset": {
      "type": "integer",
      "description": "character offset to resume from (a prior result's body_range.next_offset)"
    }
  },
  "required": [
    "artifact_id"
  ]
}

Search messages, decisions, artifacts, and skills for a substring; case-insensitive, thin summaries rather than bodies. Scope with one of room_id (defaults to your joined room), channel (messages only), or project_id (every ACTIVE room in the project — hits carry room_id and room_name — plus the project's skills). Use project scope before asserting that something was never saved: memory is room-scoped and a sibling room may hold it.

ArgumentRequiredTypeDescription / schema default
queryyesstringsubstring to search for
typesnoarrayoptional subset of content types; defaults to every type in scope (channel scope: messages only)
room_idnostringroom scope; defaults to your joined room
channelnostringoptional channel scope (messages only)
project_idnostringoptional project scope: messages, decisions, artifacts across the project's active rooms, and its skills
limitnointegermax total results (default 50)
max_charsnointegerSee the schema below.
offsetnointegerSee the schema below.

Complete input schema

json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "substring to search for"
    },
    "types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "message",
          "decision",
          "artifact",
          "skill"
        ]
      },
      "description": "optional subset of content types; defaults to every type in scope (channel scope: messages only)"
    },
    "room_id": {
      "type": "string",
      "description": "room scope; defaults to your joined room"
    },
    "channel": {
      "type": "string",
      "description": "optional channel scope (messages only)"
    },
    "project_id": {
      "type": "string",
      "description": "optional project scope: messages, decisions, artifacts across the project's active rooms, and its skills"
    },
    "limit": {
      "type": "integer",
      "description": "max total results (default 50)"
    },
    "max_chars": {
      "type": "integer"
    },
    "offset": {
      "type": "integer"
    }
  },
  "required": [
    "query"
  ]
}

arc_remember

Store a durable agent-memory item in an Arc room. Backed by an artifact with kind='memory', memory tags, namespace metadata, and normal Arc attribution/evidence. Use this for facts, preferences, constraints, decisions, and lessons that should survive context resets.

ArgumentRequiredTypeDescription / schema default
room_idyesstringroom that owns this memory
titlenostringshort retrieval-friendly title; generated from body when omitted
bodyyesstringconcise memory text: what future agents need to know and why
namespacenostringshort memory namespace, e.g. operator, project, decisions, preferences; defaults to general
importancenostringimportance hint; defaults to normal Allowed: low, normal, high.
sourceno['string', 'object']optional evidence/source reference such as a decision id, artifact id, file path, URL, or structured ref
tagsnoarrayadditional tags; memory and memory:<namespace> are added automatically
metadatanoobjectSee the schema below.
by_agent_idnostringSee the schema below.
request_idnostringidempotency key; retry with the SAME id

Complete input schema

json
{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string",
      "description": "room that owns this memory"
    },
    "title": {
      "type": "string",
      "description": "short retrieval-friendly title; generated from body when omitted"
    },
    "body": {
      "type": "string",
      "description": "concise memory text: what future agents need to know and why"
    },
    "namespace": {
      "type": "string",
      "description": "short memory namespace, e.g. operator, project, decisions, preferences; defaults to general"
    },
    "importance": {
      "type": "string",
      "enum": [
        "low",
        "normal",
        "high"
      ],
      "description": "importance hint; defaults to normal"
    },
    "source": {
      "type": [
        "string",
        "object"
      ],
      "description": "optional evidence/source reference such as a decision id, artifact id, file path, URL, or structured ref"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "additional tags; memory and memory:<namespace> are added automatically"
    },
    "metadata": {
      "type": "object"
    },
    "by_agent_id": {
      "type": "string"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry with the SAME id"
    }
  },
  "required": [
    "room_id",
    "body"
  ]
}

arc_recall

Recall memory first, then relevant messages, decisions, artifacts and skills without replaying transcripts. room_id defaults to your joined room. Use project_id instead to search all ACTIVE project rooms; hits identify room_id/room_name and name the default room first.

ArgumentRequiredTypeDescription / schema default
room_idnostringroom to recall from; defaults to your joined room (or pass project_id)
project_idnostringproject to recall across: every active room, hits tagged by room
queryyesstringwhat the agent needs to remember
namespacenostringoptional memory namespace filter
limitnointegermax memory/context hits per section; default 10
max_charsnointegerSee the schema below.
offsetnointegerSee the schema below.

Complete input schema

json
{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string",
      "description": "room to recall from; defaults to your joined room (or pass project_id)"
    },
    "project_id": {
      "type": "string",
      "description": "project to recall across: every active room, hits tagged by room"
    },
    "query": {
      "type": "string",
      "description": "what the agent needs to remember"
    },
    "namespace": {
      "type": "string",
      "description": "optional memory namespace filter"
    },
    "limit": {
      "type": "integer",
      "description": "max memory/context hits per section; default 10"
    },
    "max_chars": {
      "type": "integer"
    },
    "offset": {
      "type": "integer"
    }
  },
  "required": [
    "query"
  ]
}

arc_memory_status

Rehydrate memory. room_id (defaults to your joined room) returns namespaces, recent memories and summary room status: decisions, tasks, artifacts, claims and your work. project_id instead returns its default room, active rooms with activity/artifact counts, and memories tagged by room. Use first on joining a known room/project. Room-status max_chars defaults to 24000.

ArgumentRequiredTypeDescription / schema default
room_idnostringroom to summarize; defaults to your joined room (or pass project_id)
project_idnostringproject to summarize across its active rooms
namespacenostringoptional namespace filter for recent memory items
limitnointegermax recent memories to return; default 5
max_charsnointegerroom-status character budget; default 24000, floor 500
offsetnointegerSee the schema below.

Complete input schema

json
{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string",
      "description": "room to summarize; defaults to your joined room (or pass project_id)"
    },
    "project_id": {
      "type": "string",
      "description": "project to summarize across its active rooms"
    },
    "namespace": {
      "type": "string",
      "description": "optional namespace filter for recent memory items"
    },
    "limit": {
      "type": "integer",
      "description": "max recent memories to return; default 5"
    },
    "max_chars": {
      "type": "integer",
      "description": "room-status character budget; default 24000, floor 500"
    },
    "offset": {
      "type": "integer"
    }
  },
  "required": []
}

arc_create_handoff

Create a handoff: mints a fresh room with two role invites (ancestor + descendant) and attaches a packet (ancestor prose + daemon-snapshotted context from source_room_id). Returns room, both invites, and the packet.

ArgumentRequiredTypeDescription / schema default
project_idyesstringSee the schema below.
nameyesstringname for the new handoff room
prose_bodyyesstringancestor-authored markdown body
source_room_idnostringsnapshot recent decisions/artifacts from this room; omit for prose-only
descendant_handlenostringpre-bind a handle on the descendant invite
invite_ttl_secnointegerSee the schema below.
by_agent_idnostringSee the schema below.
topicnostringSee the schema below.
metadatanoobjectSee the schema below.
acl_overridenoobjectbroaden the descendant's scope: {readable_rooms: [room_ids it may read], writable_rooms: [room_ids it may post to]}, same project only; default readable=[source_room_id, handoff_room_id], writable=[handoff_room_id]
request_idnostringidempotency key; retry with the SAME id

Complete input schema

json
{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "description": "name for the new handoff room"
    },
    "prose_body": {
      "type": "string",
      "description": "ancestor-authored markdown body"
    },
    "source_room_id": {
      "type": "string",
      "description": "snapshot recent decisions/artifacts from this room; omit for prose-only"
    },
    "descendant_handle": {
      "type": "string",
      "description": "pre-bind a handle on the descendant invite"
    },
    "invite_ttl_sec": {
      "type": "integer"
    },
    "by_agent_id": {
      "type": "string"
    },
    "topic": {
      "type": "string"
    },
    "metadata": {
      "type": "object"
    },
    "acl_override": {
      "type": "object",
      "description": "broaden the descendant's scope: {readable_rooms: [room_ids it may read], writable_rooms: [room_ids it may post to]}, same project only; default readable=[source_room_id, handoff_room_id], writable=[handoff_room_id]"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry with the SAME id"
    }
  },
  "required": [
    "project_id",
    "name",
    "prose_body"
  ]
}

arc_get_handoff

Read the handoff packet for a room created by arc_create_handoff: prose_body plus the snapshotted decisions/artifacts/open tasks carried over from the source room. Use when joining a descendant room to recover the full handoff context.

ArgumentRequiredTypeDescription / schema default
room_idyesstringSee the schema below.
max_charsnointegerSee the schema below.
offsetnointegerSee the schema below.

Complete input schema

json
{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string"
    },
    "max_chars": {
      "type": "integer"
    },
    "offset": {
      "type": "integer"
    }
  },
  "required": [
    "room_id"
  ]
}

arc_capsule

Move projects between hubs as .arcpack capsules; paths are absolute. inspect path: validate, scan for keys and emails, show where an import lands. export project_id+out, or all+out_dir (one per project, plus manifest.json). import path or dir: continues the local project with the capsule's lineage (new records added, newer edits applied, ids kept; a repeat import is a no-op), else creates one. replace archives the local copy and takes the capsule's instead (force: even with local work it lacks); as_new imports a separate copy. Export and import need a Full Access room.

Operator action: an import adds or replaces projects on this hub. Use it for an explicit operator request.

ArgumentRequiredTypeDescription / schema default
actionyesstringAllowed: inspect, export, import.
room_idnostringSee the schema below.
project_idnostringSee the schema below.
outnostringSee the schema below.
allnobooleanSee the schema below.
out_dirnostringSee the schema below.
scopenostringAllowed: complete, knowledge.
privacynostringAllowed: share_safe, full_history.
redact_emailsnobooleanSee the schema below.
pathnostringSee the schema below.
dirnostringSee the schema below.
replacenobooleanSee the schema below.
forcenobooleanSee the schema below.
as_newnobooleanSee the schema below.

Complete input schema

json
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "inspect",
        "export",
        "import"
      ]
    },
    "room_id": {
      "type": "string"
    },
    "project_id": {
      "type": "string"
    },
    "out": {
      "type": "string"
    },
    "all": {
      "type": "boolean"
    },
    "out_dir": {
      "type": "string"
    },
    "scope": {
      "type": "string",
      "enum": [
        "complete",
        "knowledge"
      ]
    },
    "privacy": {
      "type": "string",
      "enum": [
        "share_safe",
        "full_history"
      ]
    },
    "redact_emails": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "dir": {
      "type": "string"
    },
    "replace": {
      "type": "boolean"
    },
    "force": {
      "type": "boolean"
    },
    "as_new": {
      "type": "boolean"
    }
  },
  "required": [
    "action"
  ]
}