Skip to main content
Glama

Start a full export of all memories

amber_export_memories
Read-only

Export all memories to one downloadable JSON file for backups or migration. This async tool returns a task_id to poll until the download_url is ready.

Instructions

Start exporting your memories to a downloadable JSON file. Returns a task_id IMMEDIATELY -- the file is built in the background. Poll amber_get_export_status with that id until status is complete, then give the user the download_url it returns.

By DEFAULT exports ACTIVE memories only; pass include_deleted=true to also include trashed (soft-deleted) memories. IF THE USER ASKED FOR A BACKUP, PASS include_deleted=true. Amber's deletes are reversible, so an active-only archive is missing everything they could still restore -- on a real account that was 121 records against 6,334. The unattended route at /backups always includes the trash for that reason; active-only is the right choice for "let me look at my data", not for a backup. Each record carries content, subjects, topics, metadata (internal prefixes stripped), event dates, and timestamps (deleted records also carry deleted_at).

Use this when the user wants a backup, wants to migrate data, or asks "can I download my data?". Unlike amber_list_memories (which paginates one page at a time), this exports ALL memories into one file; unlike amber_search_memories (which finds specific content), this is a complete dump.

WHY IT IS ASYNC: an export of a large account cannot be produced inside one request, so it is built in slices in the background. There is no size limit and no truncation. A small account is usually ready on the first poll; a large one takes several. For an UNATTENDED schedule (a weekly cron with no assistant running), point the user at https://ambermem.com/backups instead -- same mechanism over plain HTTP.

Does not modify any data -- read-only. Requires an active subscription. Not rate-limited.

Errors: queue_failed (the export could not be queued; nothing was started, so retrying is safe and creates no orphan task).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "amber_export_memories"
  }
}

Input Schema

NameRequiredDescriptionDefault
include_deletedNoAlso include trashed (soft-deleted) memories. Default false -- active memories only.

Output Schema

NameRequiredDescriptionDefault
statusYesAlways `pending`: the export was queued. There is no download link yet, so do not tell the user it is ready. Poll `amber_get_export_status`.
messageYesA human-readable summary of what was started and what to poll.
task_idYesPass this to `amber_get_export_status`. Do NOT tell the user the export is ready yet -- nothing has been written at this point.
exported_atYesThe timestamp stamped into the file itself, fixed when the task started.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.1.6
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / properties / include_deleted
      Added value: +{
      +  "description": "Also include trashed (soft-deleted) memories. Default false -- active memories only.",
      +  "type": "boolean"
      +}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "exported_at": {
      +      "description": "The timestamp stamped into the file itself, fixed when the task started.",
      +      "type": "string"
      +    },
      +    "message": {
      +      "description": "A human-readable summary of what was started and what to poll.",
      +      "type": "string"
      +    },
      +    "status": {
      +      "const": "pending",
      +      "description": "Always `pending`: the export was queued. There is no download link yet, so do not tell the user it is ready. Poll `amber_get_export_status`.",
      +      "type": "string"
      +    },
      +    "task_id": {
      +      "description": "Pass this to `amber_get_export_status`. Do NOT tell the user the export is ready yet -- nothing has been written at this point.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "task_id",
      +    "status",
      +    "exported_at",
      +    "message"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only declare a safe read; the description adds the async contract (task_id returned before the file exists, poll amber_get_export_status), the no-truncation guarantee, subscription requirement, absence of rate limiting, record contents, and the queue_failed semantics with safe-retry guidance. That is substantial context the annotations cannot convey.

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

Conciseness4/5

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

Paragraphs are grouped by concern (mechanics, the include_deleted decision, alternatives, async rationale, constraints) with the most important mechanics front-loaded. It runs long and the backup/include_deleted point is restated two or three times, plus "read-only" repeats the annotation, but nothing is genuinely off-topic.

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

Completeness5/5

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

Despite an output schema existing, the description still supplies the orchestration loop (task_id → poll → download_url) and the one documented failure mode, which is what an agent actually needs to complete the workflow. Nothing material is missing for a single-optional-parameter async export.

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

Parameters5/5

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

Schema coverage is already 100%, yet the description adds real decision meaning for include_deleted: why backups must set it true, the reversibility rationale, and a concrete 121-vs-6,334 record example. It tells the agent how to choose the value, not just what it does.

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?

"Start exporting your memories to a downloadable JSON file" gives a specific verb and resource, and the description explicitly separates it from amber_list_memories (paginated) and amber_search_memories (targeted lookup). An agent can pick it out of a 29-tool sibling set without opening a schema.

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

Usage Guidelines5/5

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

It names the triggering intents (backup, migration, "can I download my data?"), names the alternatives and the condition that rules them out, and adds the unattended-cron route via /backups. Both when-to-use and when-not-to-use are covered.

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