Skip to main content
Glama

Delete memories (soft-delete)

amber_delete_memory
DestructiveIdempotent

Soft-delete one or more memories to the trash so they can be restored later. Use it to remove specific memories by ID, not for account-level cleanup.

Instructions

Soft-delete one or more memories to the trash. Reversible via amber_restore_memory. Do NOT use this for account-level cleanup -- use amber_delete_account instead.

Provide memory_id (single) or memory_ids (batch, max 100). At least one is required. Idempotent: already-deleted memories are skipped. EVERY ID you send is accounted for: deleted_count plus already_deleted_ids (existed, already trashed) plus not_found_ids (no such row). ALWAYS check deleted_count against how many IDs you sent -- a batch is NOT all-or-nothing, and a shortfall usually means those memories are still being written (amber_store_memory is async), so check amber_get_store_task_status and retry rather than assuming they are gone. If the IDs are already in the trash you get deleted_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. VERIFY WHAT YOU DELETED: the reply carries deleted -- the full content of every memory this call actually trashed. READ IT and confirm it is what the user meant, because an id proves nothing: if you deleted the wrong memory this is the moment to notice, and amber_restore_memory puts it straight back. Tell the user what was deleted rather than only how many. Requires an active subscription. Not rate-limited.

Errors: invalid_params (no id supplied, or both singular and plural given). A wrong TYPE -- a number where a string belongs -- is caught a layer earlier and answers invalid_input. Deleting an id that does not exist is NOT an error: deleted reports what was actually trashed, so compare its length against how many ids you sent.

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

Input Schema

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

Output Schema

NameRequiredDescriptionDefault
statusYesAlways `deleted`. The memories moved to the TRASH and stay restorable for 30 days; nothing is destroyed by this call.
deletedYesThe memories this call actually trashed, in full. CHECK THESE: a count cannot tell you whether the right memory went, and this is the last moment the content is easy to see. Empty when nothing was deleted -- never absent, so there is one shape to handle.
deleted_countYesHow many memories this call actually moved to the trash. Compare against the number of IDs you sent: any shortfall is itemised in already_deleted_ids / not_found_ids.
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.
already_deleted_idsNoIDs that exist but were ALREADY in the trash, 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_deleted_ids": {
      +      "description": "IDs that exist but were ALREADY in the trash, so this call was a no-op for them. Present only when some were.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "deleted": {
      +      "description": "The memories this call actually trashed, in full. CHECK THESE: a count cannot tell you whether the right memory went, and this is the last moment the content is easy to see. Empty when nothing was deleted -- 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"
      +    },
      +    "deleted_count": {
      +      "description": "How many memories this call actually moved to the trash. Compare against the number of IDs you sent: any shortfall is itemised in already_deleted_ids / not_found_ids.",
      +      "type": "number"
      +    },
      +    "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"
      +    },
      +    "status": {
      +      "const": "deleted",
      +      "description": "Always `deleted`. The memories moved to the TRASH and stay restorable for 30 days; nothing is destroyed by this call.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "status",
      +    "deleted_count",
      +    "deleted"
      +  ],
      +  "type": "object"
      +}
  2. Changed2 schema fields changedv1.1.4
    • changedInput schema / properties / memory_id / description
      Previous value: -"A single memory ID (UUID) to move to trash. Use this for individual deletions. Mutually optional with memory_ids — provide at least one."New value: +"UUID of a single memory to trash. Omit if using `memory_ids` for batch."
    • changedInput schema / properties / memory_ids / description
      Previous value: -"Array of memory IDs (UUIDs) to move to trash in a single batch (max 100). Use this for bulk deletions. Mutually optional with memory_id — provide at least one."New value: +"Array of memory UUIDs to trash 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 move to trash (single)."New value: +"A single memory ID (UUID) to move to trash. Use this for individual deletions. Mutually optional with memory_ids — provide at least one."
    • changedInput schema / properties / memory_ids / description
      Previous value: -"Array of memory IDs to move to trash (batch, max 100)."New value: +"Array of memory IDs (UUIDs) to move to trash in a single batch (max 100). Use this for bulk deletions. Mutually optional with memory_id — provide at least one."
  4. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare destructive=true and idempotentHint=true, and the description adds real value beyond that: reversibility, skip-already-deleted semantics, the no-op vs not_found distinction, the async-write race that causes batch shortfalls, subscription requirement, and no rate limit. Minor deduction because the error/verification material is stated twice in slightly different words, diluting rather than contradicting the disclosure.

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

Conciseness3/5

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

Core purpose and the sibling exclusion are front-loaded, but the text is dense and repetitive: the deleted_count-vs-sent check appears in the main body and again in the errors section, and the no-op vs not_found explanation is restated. Several clauses could be tightened without losing information.

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?

For a destructive batch mutation this covers everything an agent needs: required argument cardinality, idempotency, partial-success accounting, error codes, the async-write caveat, and post-delete verification against the returned content. Output schema exists but the description still adds interpretive guidance on how to use those fields rather than merely repeating them.

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% and the schema already documents each parameter, so the baseline is 3. The description earns above baseline by stating constraints the schema does not encode: at least one id is required (required array is empty) and supplying both singular and plural yields invalid_params. It does not restate the max-100 limit, but that is already in 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?

States a specific verb and resource ("Soft-delete one or more memories to the trash") and immediately names the two siblings it must be distinguished from: amber_restore_memory for reversal and amber_delete_account as the wrong tool for account-level cleanup. An agent can route to it without opening any 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?

Explicit when-not guidance ("Do NOT use this for account-level cleanup -- use amber_delete_account instead") plus the alternative for undoing the action. It also prescribes the correct downstream flow after a shortfall (check amber_get_store_task_status and retry), covering the ambiguity an agent would otherwise guess at.

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