Skip to main content
Glama

Memory checkpoint

memory_checkpoint

Persist a structured handoff checkpoint for another agent or harness. Creates the mission when absent, using project_id and mission_id to record status, decisions, files, and next steps for resumption.

Instructions

Persist a structured handoff checkpoint for another harness or agent. Creates the mission when absent. Use the same project_id and mission_id the task used for delegate, consensus and swarm_run.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
goalNoMission goal.
mergeNoappend adds new list items; replace overwrites provided lists.append
testsNo
statusNoMission status. Omit to keep the current status.
summaryNoShort factual summary of progress.
artifactsNo
decisionsNoDecisions taken.
files_readNo
invariantsNoConstraints that must remain true.
mission_idYesMission identifier inside the project.
next_tasksNo
project_idYesProject memory identifier. Not an authorization boundary.
lease_tokenNoToken from mission_claim. Required only while another holder has a live lease on this mission.
next_actionNoConcrete next step for whoever resumes.
active_tasksNo
blocked_tasksNo
files_changedNo
known_failuresNo
completed_tasksNo
acceptance_criteriaNoObjective acceptance criteria.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv4.1.0
    • addedInput schema / properties / lease_token
      Added value: +{
      +  "description": "Token from mission_claim. Required only while another holder has a live lease on this mission.",
      +  "maxLength": 128,
      +  "type": "string"
      +}
    • changedInput schema / properties / mission_id / pattern
      Previous value: -"^[a-zA-Z0-9][a-zA-Z0-9._-]{0,119}$"New value: +"^[a-zA-Z0-9](?:[a-zA-Z0-9._-]{0,118}[a-zA-Z0-9_-])?$"
    • changedInput schema / properties / mission_id / x-pattern-reason
      Previous value: -"must use 1-120 letters, digits, dots, underscores or hyphens and start with a letter or digit"New value: +"must use 1-120 letters, digits, dots, underscores or hyphens, start with a letter or digit and not end with a dot"
    • changedInput schema / properties / project_id / pattern
      Previous value: -"^[a-zA-Z0-9][a-zA-Z0-9._-]{0,119}$"New value: +"^[a-zA-Z0-9](?:[a-zA-Z0-9._-]{0,118}[a-zA-Z0-9_-])?$"
    • changedInput schema / properties / project_id / x-pattern-reason
      Previous value: -"must use 1-120 letters, digits, dots, underscores or hyphens and start with a letter or digit"New value: +"must use 1-120 letters, digits, dots, underscores or hyphens, start with a letter or digit and not end with a dot"
  2. Changed30 schema fields changedv3.0.0
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / acceptance_criteria
      Added value: +{
      +  "description": "Objective acceptance criteria.",
      +  "items": {
      +    "maxLength": 2000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 200,
      +  "type": "array"
      +}
    • addedInput schema / properties / active_tasks
      Added value: +{
      +  "items": {
      +    "maxLength": 2000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 200,
      +  "type": "array"
      +}
    • addedInput schema / properties / artifacts
      Added value: +{
      +  "items": {
      +    "maxLength": 2000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 200,
      +  "type": "array"
      +}
    • addedInput schema / properties / blocked_tasks
      Added value: +{
      +  "items": {
      +    "maxLength": 2000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 200,
      +  "type": "array"
      +}
    • addedInput schema / properties / completed_tasks
      Added value: +{
      +  "items": {
      +    "maxLength": 2000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 200,
      +  "type": "array"
      +}
    • addedInput schema / properties / decisions
      Added value: +{
      +  "description": "Decisions taken.",
      +  "items": {
      +    "maxLength": 2000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 200,
      +  "type": "array"
      +}
    • addedInput schema / properties / files_changed
      Added value: +{
      +  "items": {
      +    "maxLength": 2000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 200,
      +  "type": "array"
      +}
    • addedInput schema / properties / files_read
      Added value: +{
      +  "items": {
      +    "maxLength": 2000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 200,
      +  "type": "array"
      +}
    • addedInput schema / properties / goal
      Added value: +{
      +  "description": "Mission goal.",
      +  "maxLength": 8000,
      +  "type": "string"
      +}
    • addedInput schema / properties / invariants
      Added value: +{
      +  "description": "Constraints that must remain true.",
      +  "items": {
      +    "maxLength": 2000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 200,
      +  "type": "array"
      +}
    • addedInput schema / properties / known_failures
      Added value: +{
      +  "items": {
      +    "maxLength": 2000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 200,
      +  "type": "array"
      +}
    • addedInput schema / properties / merge
      Added value: +{
      +  "default": "append",
      +  "description": "append adds new list items; replace overwrites provided lists.",
      +  "enum": [
      +    "append",
      +    "replace"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / mission_id / description
      Added value: +"Mission identifier inside the project."
    • addedInput schema / properties / mission_id / maxLength
      Added value: +120
    • addedInput schema / properties / mission_id / minLength
      Added value: +1
    • addedInput schema / properties / mission_id / pattern
      Added value: +"^[a-zA-Z0-9][a-zA-Z0-9._-]{0,119}$"
    • addedInput schema / properties / mission_id / x-pattern-reason
      Added value: +"must use 1-120 letters, digits, dots, underscores or hyphens and start with a letter or digit"
    • addedInput schema / properties / next_action / description
      Added value: +"Concrete next step for whoever resumes."
    • addedInput schema / properties / next_action / maxLength
      Added value: +4000
    • addedInput schema / properties / next_tasks
      Added value: +{
      +  "items": {
      +    "maxLength": 2000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 200,
      +  "type": "array"
      +}
    • addedInput schema / properties / project_id / description
      Added value: +"Project memory identifier. Not an authorization boundary."
    • addedInput schema / properties / project_id / maxLength
      Added value: +120
    • addedInput schema / properties / project_id / minLength
      Added value: +1
    • addedInput schema / properties / project_id / pattern
      Added value: +"^[a-zA-Z0-9][a-zA-Z0-9._-]{0,119}$"
    • addedInput schema / properties / project_id / x-pattern-reason
      Added value: +"must use 1-120 letters, digits, dots, underscores or hyphens and start with a letter or digit"
    • addedInput schema / properties / status / description
      Added value: +"Mission status. Omit to keep the current status."
    • addedInput schema / properties / status / enum
      Added value: +[
      +  "active",
      +  "partial",
      +  "blocked",
      +  "paused",
      +  "done",
      +  "completed",
      +  "failed",
      +  "cancelled"
      +]
    • addedInput schema / properties / summary
      Added value: +{
      +  "description": "Short factual summary of progress.",
      +  "maxLength": 8000,
      +  "type": "string"
      +}
    • addedInput schema / properties / tests
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "failed": {
      +      "items": {
      +        "maxLength": 2000,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "maxItems": 200,
      +      "type": "array"
      +    },
      +    "passed": {
      +      "items": {
      +        "maxLength": 2000,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "maxItems": 200,
      +      "type": "array"
      +    },
      +    "pending": {
      +      "items": {
      +        "maxLength": 2000,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "maxItems": 200,
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
  3. First observedv2.2.4

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (which already indicate this is not read-only), the description discloses the meaningful side effect that the mission is created when absent. This is useful behavioral context an agent would not get from the schema alone. It does not detail overwrite semantics or lease requirements, but those are covered in the schema and annotations do not contradict the description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two tight sentences with no filler. The primary purpose is front-loaded, and the ID reuse instruction earns its place by directly aiding correct invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 20-parameter tool with nested objects and no output schema, the description is adequate but leaves important context implicit. It explains the handoff purpose and ID provenance but does not address what happens on update, how checkpoints relate to sibling handoff/export tools, or what a successful call returns. The schema fills many gaps, but a tool this complex could use more orientation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds real semantic value for the two required parameters by instructing the agent to reuse the IDs from delegate, consensus, and swarm_run. However, with 20 parameters and only 55% schema description coverage, the description does not compensate for the many undocumented fields or summarize the checkpoint payload, leaving most parameter meaning to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair ('Persist a structured handoff checkpoint') and clearly scopes the target ('for another harness or agent'). The added note that it 'creates the mission when absent' distinguishes it from read-only status tools like mission_status and from mission_start, making the resource and intent unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear contextual guidance: use this tool when persisting a handoff checkpoint, and reuse the same project_id and mission_id from delegate, consensus, and swarm_run. It does not explicitly name sibling alternatives or state when not to use it, but the context is specific enough to guide correct selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.