Skip to main content
Glama

List deleted memories (trash)

amber_list_deleted_memories
Read-onlyIdempotent

Browse trashed memories in reverse deletion order with cursor pagination, then restore items or search the trash by meaning. Read-only and does not permanently delete anything.

Instructions

Browse the trash in reverse chronological order of deletion (most recently deleted first). Supports cursor pagination via after_id. has_more tells you whether another page exists. Use amber_restore_memory to bring an item back, or amber_search_deleted_memories for meaning-based search within the trash.

Each result includes full content (not truncated), metadata, topics, creation timestamp, and deletion timestamp. Pass metadata_filter for an EXHAUSTIVE exact-match filter over the trash (same as amber_list_memories). Read-only -- does not modify or permanently delete any memories. Not rate-limited. Requires an active subscription.

Returns memories array, next_cursor (null if no more pages), and has_more boolean.

Errors: invalid_input (a bad cursor, limit, or filter type).

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

Input Schema

NameRequiredDescriptionDefault
limitNoNumber of deleted memories per page (default 20, min 1, max 100). Use smaller values (5-10) for quick checks, larger values (50-100) for bulk review. Omit to use the default of 20.
after_idNoPagination cursor (memory ID string). Pass the `next_cursor` value from a previous response to fetch the next page. Omit on the first call to start from the most recently deleted memory. Do not fabricate cursor values.
metadata_filterNoOptional EXACT-match metadata filter, e.g. { "qa_batch": "2026-07-21" }. Values must be SCALARS (string/number/boolean/null) -- operator objects like {"$ne": ...} and nested objects are NOT supported (rejected with invalid_input). Matching is TYPE-STRICT as well as exact: metadata stored as the number 5 is matched by 5, NOT by "5". A null VALUE matches only memories that explicitly stored a null under that key -- a memory missing the key entirely does NOT match, exactly as a wrong value would not. If a value reached you stringified (from JSON, a config file, a spreadsheet export), convert it back first -- a type mismatch returns an empty result set that looks exactly like "no such data". Filters at the database level and returns EVERY matching trashed memory across pages (same exhaustive semantics as amber_list_memories).

Output Schema

NameRequiredDescriptionDefault
has_moreYesWhether another page exists. Prefer this over guessing from the page size.
memoriesYesThis page of memories currently in the trash, newest first. Restore one with `amber_restore_memory`.
next_cursorYesPass this back as `after_id` for the next page (the parameter is `after_id`; this said `cursor` until 2026-09-19, which is not a parameter this tool has). Null on the last page. Opaque: do not build or edit one.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 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
    • addedInput schema / properties / metadata_filter
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Optional EXACT-match metadata filter, e.g. { \"qa_batch\": \"2026-07-21\" }. Values must be SCALARS (string/number/boolean/null) -- operator objects like {\"$ne\": ...} and nested objects are NOT supported (rejected with invalid_input). Matching is TYPE-STRICT as well as exact: metadata stored as the number 5 is matched by 5, NOT by \"5\". A null VALUE matches only memories that explicitly stored a null under that key -- a memory missing the key entirely does NOT match, exactly as a wrong value would not. If a value reached you stringified (from JSON, a config file, a spreadsheet export), convert it back first -- a type mismatch returns an empty result set that looks exactly like \"no such data\". Filters at the database level and returns EVERY matching trashed memory across pages (same exhaustive semantics as amber_list_memories).",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "has_more": {
      +      "description": "Whether another page exists. Prefer this over guessing from the page size.",
      +      "type": "boolean"
      +    },
      +    "memories": {
      +      "description": "This page of memories currently in the trash, newest first. Restore one with `amber_restore_memory`.",
      +      "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"
      +    },
      +    "next_cursor": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "description": "Pass this back as `after_id` for the next page (the parameter is `after_id`; this said `cursor` until 2026-09-19, which is not a parameter this tool has). Null on the last page. Opaque: do not build or edit one."
      +    }
      +  },
      +  "required": [
      +    "memories",
      +    "next_cursor",
      +    "has_more"
      +  ],
      +  "type": "object"
      +}
  2. Changed2 schema fields changedv1.1.2
    • changedInput schema / properties / after_id / description
      Previous value: -"Pagination cursor. Pass the `next_cursor` value from a previous response to get the next page. Omit to start from the most recently deleted memory."New value: +"Pagination cursor (memory ID string). Pass the `next_cursor` value from a previous response to fetch the next page. Omit on the first call to start from the most recently deleted memory. Do not fabricate cursor values."
    • changedInput schema / properties / limit / description
      Previous value: -"Number of deleted memories per page (default 20, max 100). Use smaller values (5-10) for quick checks, larger values (50-100) for bulk review."New value: +"Number of deleted memories per page (default 20, min 1, max 100). Use smaller values (5-10) for quick checks, larger values (50-100) for bulk review. Omit to use the default of 20."
  3. Changed2 schema fields changedv1.1.1
    • changedInput schema / properties / after_id / description
      Previous value: -"Cursor from the `next_cursor` field of a previous page."New value: +"Pagination cursor. Pass the `next_cursor` value from a previous response to get the next page. Omit to start from the most recently deleted memory."
    • changedInput schema / properties / limit / description
      Previous value: -"Page size (default 20, max 100)."New value: +"Number of deleted memories per page (default 20, max 100). Use smaller values (5-10) for quick checks, larger values (50-100) for bulk review."
  4. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real context beyond them: subscription requirement, no rate limiting, full untruncated content in results, exhaustive database-level filtering semantics, and the specific `invalid_input` error condition. The only gap is it doesn't contrast behavior with hard-delete (amber_delete_memory) beyond asserting it never permanently deletes.

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?

Well front-loaded — purpose and pagination first, alternatives second, semantics third. Slightly padded by restating return fields (`memories`, `next_cursor`, `has_more`) that an output schema already documents, and by re-explaining metadata_filter caveats already present in the schema.

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 3-parameter read tool with an output schema, the description covers scope, ordering, pagination, filtering semantics, auth requirement, and error modes. Nothing an agent needs to call it correctly is missing.

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 a 3 is the baseline, but the description adds cross-tool meaning: the metadata_filter behaves the same exhaustively as in amber_list_memories, and after_id/has_more pagination contract is spelled out. Marginal added value over the already-detailed schema, hence 4 rather than 5.

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?

Opens with a specific verb+resource+scope: 'Browse the trash in reverse chronological order of deletion (most recently deleted first).' It is immediately distinguishable from amber_list_memories (live memories) and amber_search_deleted_memories (meaning-based search within trash), both of which are named.

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 routes the agent: use amber_restore_memory to bring an item back, use amber_search_deleted_memories for meaning-based search. It also states the prerequisite (active subscription) and that it is not rate-limited, leaving little to infer about when to pick this tool.

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