Skip to main content
Glama

Search deleted memories (trash)

amber_search_deleted_memories
Read-onlyIdempotent

Search trash for soft-deleted memories when a user asks about something they've since deleted. Returns relevance-ranked results, with optional filters for deletion age and topics.

Instructions

Search within the trash for soft-deleted memories. Useful when the user asks about something they've since deleted. Results are ordered by relevance (higher score = better match; scores are relative within a single query). Optional max_age_days restricts to recently deleted items. Optional topics filters by topic (semantic matching). For ranking quality it takes the SAME optional steering params as amber_search_memories -- subjects, query_variants, keywords -- so trash ranking matches active search. Content is truncated to 1000 chars -- use amber_get_memory for full content. Use amber_restore_memory to bring a result back. Rate-limited (search bucket: 5000 capacity, refills ~1 per 17 seconds).

Errors: invalid_input (a parameter has the wrong type, or a date could not be parsed).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>",
      "subjects": "<subjects>"
    },
    "name": "amber_search_deleted_memories"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesNatural-language question or description of what to find. Use full sentences, not keywords.
topicsNoOptional topic filter. Pass category names like 'food', 'work', 'beliefs'. Matched semantically.
keywordsNoOptional EXACT lexical terms for the keyword (full-text) side of hybrid search -- the distinctive words the answer would contain. OMIT the subject's name (that is what `subjects` is for).
subjectsYesREQUIRED, exactly as in amber_search_memories -- same parameter, same ranking role, same contract. Who is this query about? e.g. ["patrick vane"], or ["self"]/["me"] for the USER. Pass [] (or ["anyone"]) when the query has no personal focus -- that is a deliberate answer, not an omission. BOOSTS the matching person's trashed facts; never hard-filters, so a wrong guess cannot hide a memory.
n_resultsNoMaximum results (default 10, max 100).
near_dateNoOptional ISO 8601 datetime to rank results by TEMPORAL PROXIMITY to (memories whose event_start/event_end sits closest rank higher), exactly like amber_search_memories. Pure boost; dateless memories are left in their existing relative order, though anchoring renormalises the whole set so their absolute scores move slightly (measured: about 10% lower).
max_age_daysNoOnly consider memories deleted within the last N days.
near_date_endNoOptional ISO 8601 datetime. With `near_date`, proximity is measured to the window [near_date, near_date_end]. REJECTED with invalid_input if `near_date` is not also given; must be on or after near_date.
query_variantsNoOptional alternative phrasings of the SAME query that YOU generate -- each is embedded and searched and the results fused, exactly like amber_search_memories.
metadata_filterNoOptional EXACT-match metadata filter. 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".

Output Schema

NameRequiredDescriptionDefault
resultsYesMatching memories from the trash, best first. Bring one back with `amber_restore_memory`. Empty is not an error.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 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 / keywords
      Added value: +{
      +  "description": "Optional EXACT lexical terms for the keyword (full-text) side of hybrid search -- the distinctive words the answer would contain. OMIT the subject's name (that is what `subjects` is for).",
      +  "items": {
      +    "maxLength": 100,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 10,
      +  "type": "array"
      +}
    • addedInput schema / properties / max_age_days / maximum
      Added value: +9007199254740991
    • changedInput schema / properties / metadata_filter / description
      Previous value: -"Optional metadata filter."New value: +"Optional EXACT-match metadata filter. 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\"."
    • addedInput schema / properties / metadata_filter / propertyNames
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / near_date
      Added value: +{
      +  "description": "Optional ISO 8601 datetime to rank results by TEMPORAL PROXIMITY to (memories whose event_start/event_end sits closest rank higher), exactly like amber_search_memories. Pure boost; dateless memories are left in their existing relative order, though anchoring renormalises the whole set so their absolute scores move slightly (measured: about 10% lower).",
      +  "type": "string"
      +}
    • addedInput schema / properties / near_date_end
      Added value: +{
      +  "description": "Optional ISO 8601 datetime. With `near_date`, proximity is measured to the window [near_date, near_date_end]. REJECTED with invalid_input if `near_date` is not also given; must be on or after near_date.",
      +  "type": "string"
      +}
    • addedInput schema / properties / query / maxLength
      Added value: +5000
    • addedInput schema / properties / query_variants
      Added value: +{
      +  "description": "Optional alternative phrasings of the SAME query that YOU generate -- each is embedded and searched and the results fused, exactly like amber_search_memories.",
      +  "items": {
      +    "maxLength": 1000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 20,
      +  "type": "array"
      +}
    • addedInput schema / properties / subjects
      Added value: +{
      +  "description": "REQUIRED, exactly as in amber_search_memories -- same parameter, same ranking role, same contract. Who is this query about? e.g. [\"patrick vane\"], or [\"self\"]/[\"me\"] for the USER. Pass [] (or [\"anyone\"]) when the query has no personal focus -- that is a deliberate answer, not an omission. BOOSTS the matching person's trashed facts; never hard-filters, so a wrong guess cannot hide a memory.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "maxItems": 20,
      +  "type": "array"
      +}
    • addedInput schema / properties / topics / maxItems
      Added value: +5
    • changedInput schema / required
      Previous value: -[
      -  "query"
      -]New value: +[
      +  "query",
      +  "subjects"
      +]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "results": {
      +      "description": "Matching memories from the trash, best first. Bring one back with `amber_restore_memory`. Empty is not an error.",
      +      "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"
      +          },
      +          "score": {
      +            "description": "Relevance score. Higher = better match. Only meaningful for ranking results within the same query, not comparable across queries.",
      +            "type": "number"
      +          },
      +          "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. Tells you whose fact each result is."
      +          },
      +          "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"
      +          },
      +          "truncated": {
      +            "description": "Present and true when `content` was shortened for this result. Call `amber_get_memory` with this `memory_id` for the full text.",
      +            "type": "boolean"
      +          }
      +        },
      +        "required": [
      +          "memory_id",
      +          "content"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "results"
      +  ],
      +  "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 already declare readOnlyHint/idempotentHint, and the description adds substantial behavior beyond them: relevance ordering with scores only comparable within one query, 1000-char content truncation, and a concrete rate-limit budget (5000 capacity, ~1 refill per 17s). It also documents the invalid_input error class, which the annotations cannot express.

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, then usage trigger, then ranking/filter semantics, then operational limits and errors — a sensible order. It is dense and slightly long, but nearly every clause carries information an agent needs; only the repeated 'exactly like amber_search_memories' framing is mildly redundant.

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 10-parameter search tool with a nested metadata_filter object, the description covers the gaps the schema leaves open: ranking interpretation, truncation, rate limits, error surface, and the restore path. Since an output schema exists, return-value structure need not be restated, so nothing material is missing.

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 100%, so the baseline is 3, but the description adds cross-tool meaning the schema cannot: subjects/query_variants/keywords are the SAME steering contract as amber_search_memories, and topics is semantic rather than exact. It also flags max_age_days as a recency restriction, clarifying the interplay of filters versus ranking boosts.

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 and resource: 'Search within the trash for soft-deleted memories.' This cleanly separates it from amber_search_memories (active memories) and amber_list_deleted_memories (enumeration without query). An agent can pick the right tool from the first sentence alone.

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?

Gives an explicit trigger ('when the user asks about something they've since deleted') and names the follow-up alternatives with conditions: amber_get_memory for full content past the 1000-char truncation, amber_restore_memory to bring a result back. It also explains that steering params mirror amber_search_memories, so the agent knows behavior transfers across tools.

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