Skip to main content
Glama

Restore deleted memories

amber_restore_memory
Idempotent

Restore deleted memories from the trash to make them searchable and visible again. Use after searching or listing deleted memories to recover accidentally removed content.

Instructions

Un-delete memories from the trash, making them searchable and visible in amber_list_memories again. Use after amber_search_deleted_memories or amber_list_deleted_memories to recover accidentally deleted content. Do NOT use for new content -- use amber_store_memory instead.

Provide memory_id (single) or memory_ids (batch, max 100). At least one is required. Idempotent: already-active memories are skipped. Side effects: moves memories from trash to active. VERIFY WHAT CAME BACK: the reply carries restored -- the full content of every memory this call actually un-trashed. READ IT and confirm it is the one the user meant, because an id proves nothing. EVERY ID you send is accounted for: restored_count plus already_active_ids plus not_found_ids. ALWAYS check restored_count against how many IDs you sent -- a batch is NOT all-or-nothing. If the IDs are already active you get restored_count: 0 with an explanatory message (a no-op, NOT an error); code: not_found is returned only when no memory exists with those IDs -- so a no-op is distinguishable from wrong IDs. Requires an active subscription. Not rate-limited.

Errors: invalid_params (no id supplied, or both singular and plural given); a wrong TYPE answers invalid_input from the schema layer. Restoring something that was never deleted is not an error either; it comes back in already_active_ids.

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_restore_memory"
  }
}

Input Schema

NameRequiredDescriptionDefault
memory_idNoUUID of a single memory to restore. Omit if using `memory_ids` for batch.
memory_idsNoArray of memory UUIDs to restore in one call (max 100). Omit if using `memory_id` for single.

Output Schema

NameRequiredDescriptionDefault
statusYesAlways `restored`, including when nothing changed because every id was already active.
restoredYesThe memories this call actually brought back, in full. CHECK THESE: a count cannot tell you which memory was recovered, and that is the whole question after a wrong delete. Empty when nothing was restored -- never absent, so there is one shape to handle.
not_found_idsNoIDs that matched NO memory. Present only when some did not resolve. Most often these are from a store that has not finished writing yet (amber_store_memory is async) rather than wrong IDs -- check amber_get_store_task_status and retry.
restored_countYesHow many memories this call actually restored. Compare against the number of IDs you sent: any shortfall is itemised in already_active_ids / not_found_ids.
already_active_idsNoIDs that exist but were ALREADY active, so this call was a no-op for them. Present only when some were.

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"
    • removedInput schema / additionalProperties
      Removed value: -false
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "already_active_ids": {
      +      "description": "IDs that exist but were ALREADY active, so this call was a no-op for them. Present only when some were.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "not_found_ids": {
      +      "description": "IDs that matched NO memory. Present only when some did not resolve. Most often these are from a store that has not finished writing yet (amber_store_memory is async) rather than wrong IDs -- check amber_get_store_task_status and retry.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "restored": {
      +      "description": "The memories this call actually brought back, in full. CHECK THESE: a count cannot tell you which memory was recovered, and that is the whole question after a wrong delete. Empty when nothing was restored -- never absent, so there is one shape to handle.",
      +      "items": {
      +        "additionalProperties": {},
      +        "properties": {
      +          "content": {
      +            "description": "The fact itself, exactly as stored.",
      +            "type": "string"
      +          },
      +          "created_at": {
      +            "description": "ISO 8601 time the memory was stored. Not when the event happened: that is event_start.",
      +            "type": "string"
      +          },
      +          "deleted_at": {
      +            "description": "ISO 8601 time the memory was moved to the trash. Absent or empty for a live memory; present means amber_restore_memory can bring it back.",
      +            "type": "string"
      +          },
      +          "event_end": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ],
      +            "description": "ISO 8601 datetime the fact's event ended, or null."
      +          },
      +          "event_start": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ],
      +            "description": "ISO 8601 datetime the fact's event began, or null when the fact has no event date."
      +          },
      +          "memory_id": {
      +            "description": "The memory's id. Pass it to amber_get_memory, amber_update_memory, amber_delete_memory or amber_restore_memory.",
      +            "type": "string"
      +          },
      +          "metadata": {
      +            "additionalProperties": {},
      +            "description": "The caller's own exact-match filter values, as stored (a flat object). Absent or empty when none were set.",
      +            "propertyNames": {
      +              "type": "string"
      +            },
      +            "type": "object"
      +          },
      +          "subject": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ],
      +            "description": "Who this memory is about -- a named subject like \"patrick\" or \"patrick's father\", or null if not yet determined."
      +          },
      +          "subjects": {
      +            "description": "The same people as an ARRAY, which is the shape every tool ACCEPTS -- pass it straight back as `subjects` on a search. `subject` is the comma-joined rendering of the same value and matches nothing if passed as an argument; absent here means the memory has no attribution.",
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "topics": {
      +            "description": "The topic names this memory is filed under (at most 3 for a new store).",
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          }
      +        },
      +        "required": [
      +          "memory_id",
      +          "content"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "restored_count": {
      +      "description": "How many memories this call actually restored. Compare against the number of IDs you sent: any shortfall is itemised in already_active_ids / not_found_ids.",
      +      "type": "number"
      +    },
      +    "status": {
      +      "const": "restored",
      +      "description": "Always `restored`, including when nothing changed because every id was already active.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "status",
      +    "restored_count",
      +    "restored"
      +  ],
      +  "type": "object"
      +}
  2. Changed2 schema fields changedv1.1.4
    • changedInput schema / properties / memory_id / description
      Previous value: -"A single memory ID (UUID) to restore from trash. Use this for individual restores. Mutually optional with memory_ids — provide at least one."New value: +"UUID of a single memory to restore. Omit if using `memory_ids` for batch."
    • changedInput schema / properties / memory_ids / description
      Previous value: -"Array of memory IDs (UUIDs) to restore from trash in a single batch (max 100). Use this for bulk restores. Mutually optional with memory_id — provide at least one."New value: +"Array of memory UUIDs to restore in one call (max 100). Omit if using `memory_id` for single."
  3. Changed2 schema fields changedv1.1.1
    • changedInput schema / properties / memory_id / description
      Previous value: -"The memory ID to restore from trash (single)."New value: +"A single memory ID (UUID) to restore from trash. Use this for individual restores. Mutually optional with memory_ids — provide at least one."
    • changedInput schema / properties / memory_ids / description
      Previous value: -"Array of memory IDs to restore (batch, max 100)."New value: +"Array of memory IDs (UUIDs) to restore from trash in a single batch (max 100). Use this for bulk restores. Mutually optional with memory_id — provide at least one."
  4. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses the side effect (moves memories from trash to active), subscription requirement, absence of rate limiting, no-op vs not_found distinction, and non-atomic batch behavior. The idempotentHint is expanded into concrete mechanics (already-active entries return in already_active_ids) rather than merely restated.

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?

Front-loaded with purpose and when-to-use, then parameter mode, then return-value verification, then errors — a logical order with no filler sentences. It is long and heavy on emphatic capitalization, which is slightly excessive for the amount of distinct information conveyed.

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?

Even with an output schema present, the description explains how to reconcile the counts (restored + already_active_ids + not_found_ids) and warns that batches are not all-or-nothing — exactly the reasoning an agent needs before trusting a restore result. Error taxonomy and the no-op-not-an-error case are both covered.

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

Parameters4/5

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

Schema coverage is 100%, so baseline would be 3, but the description adds a real constraint the schema does not express: the schema declares zero required properties, while the description states 'At least one is required' and that supplying both singular and plural triggers invalid_params.

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?

States a specific verb and resource ('Un-delete memories from the trash') plus the resulting state change ('making them searchable and visible in amber_list_memories again'), which immediately distinguishes it from amber_search_deleted_memories and amber_list_deleted_memories.

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?

Explicitly names the triggering workflow ('Use after amber_search_deleted_memories or amber_list_deleted_memories to recover accidentally deleted content') and gives an explicit exclusion with the correct alternative ('Do NOT use for new content -- use amber_store_memory instead').

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