Skip to main content
Glama

Search memories

search_memories
Read-only

Use this before responding to each new user message, to retrieve context relevant to the message and ongoing conversation, even when the user does not explicitly ask you to remember. Form a concise semantic query using the people, projects, preferences, goals, decisions, or events implied by the message; for follow-ups, include enough recent conversational context to make the query meaningful. Search all tiers (omit tiers and importance) unless there is a reason to narrow. If a MemoryRouter recall block was already supplied for this message, that search already ran; search again only for more detail. Read only: searches the user's OAuth-selected vault. Tier guide: tier 3 holds the highest-level consolidated reflections (identity, principles, what matters most), tier 2 holds reflections of specific meaningful events, tier 1 holds raw verbatim memories. Match filters to the question. Broad 'most important things we have done' questions: tiers [3], importance 8 or higher, large limit such as 250. Big-picture overviews like 'what do you know about this area or period': tiers [3] with no importance filter. Specific lookups like 'find the decision about X': omit tiers to search all tiers blended and leave importance unset; a high importance filter hides the specific detail you are looking for. Specific meaningful events without raw noise: tiers [2] or [2, 3]. Exact verbatim detail: if the detail is not already in context, drill down by lineage: search tiers [3] to find the relevant thread, then use inspect_memory on the result to see the tier 2 reflections it consolidated, then inspect those to reach the raw memories underneath. Direct tiers [1] search works when you know exact wording to match. Mixing tiers is legitimate; adjust the importance threshold to the question rather than always setting it high. Only reflections (tiers 2 and 3) carry importance ratings. For time-window questions like 'what happened last week' or 'lately' use date_search_memories instead.

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>"
    },
    "name": "search_memories"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of relevant memories to return. Use a large limit such as 250 for broad 'most important things' questions over tiers [3].
queryYesA concise semantic query built from the people, projects, preferences, goals, decisions, or events implied by the user message, plus enough recent conversational context for follow-ups.
tiersNoRestrict results to these memory tiers. 3 highest-level consolidated reflections (identity, principles, what matters most), 2 reflections of specific meaningful events, 1 raw verbatim memories. Use [3] for broad 'most important' or big-picture questions, [2] or [2, 3] for specific meaningful events, [1] for exact verbatim detail when you know the wording to match; otherwise drill down from [3] with inspect_memory. Omit to search all tiers blended, the right default for specific lookups. Mixing tiers is fine. Only tiers 2 and 3 carry importance ratings.
importanceNoMinimum importance threshold, 1 to 10. Only reflections (tiers 2 and 3) carry ratings, so raw memories are excluded whenever this is set. Use 8 or higher with tiers [3] for broad 'most important' questions. Leave unset for general or specific searches; a high threshold hides relevant material.

Output Schema

NameRequiredDescriptionDefault
countYes
queryYes
memoriesYes
consolidation_availableNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedOutput schema / properties / memories / items / properties / id / description
      Added value: +"Public memory UUID when indexed; absent for pending-buffer or legacy rows. Only present IDs can be inspected or deleted."
    • changedOutput schema / properties / memories / items / required
      Previous value: -[
      -  "id",
      -  "content",
      -  "source",
      -  "timestamp",
      -  "score",
      -  "tier"
      -]New value: +[
      +  "content",
      +  "source",
      +  "timestamp",
      +  "score",
      +  "tier"
      +]
  2. Changed1 schema field changed
    • changedInput schema / properties / query / description
      Previous value: -"A concise natural-language description of the past context to recall."New value: +"A concise semantic query built from the people, projects, preferences, goals, decisions, or events implied by the user message, plus enough recent conversational context for follow-ups."
  3. Changed3 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of relevant memories to return. Use a large limit such as 100 for broad 'most important things' questions over tiers [3]."New value: +"Maximum number of relevant memories to return. Use a large limit such as 250 for broad 'most important things' questions over tiers [3]."
    • changedInput schema / properties / limit / maximum
      Previous value: -100New value: +250
    • changedInput schema / properties / tiers / description
      Previous value: -"Restrict results to these memory tiers. 3 highest-level consolidated reflections (identity, principles, what matters most), 2 reflections of specific meaningful events, 1 raw verbatim memories. Use [3] for broad 'most important' or big-picture questions, [2] or [2, 3] for specific meaningful events, [1] for exact verbatim detail. Omit to search all tiers blended, the right default for specific lookups. Mixing tiers is fine. Only tiers 2 and 3 carry importance ratings."New value: +"Restrict results to these memory tiers. 3 highest-level consolidated reflections (identity, principles, what matters most), 2 reflections of specific meaningful events, 1 raw verbatim memories. Use [3] for broad 'most important' or big-picture questions, [2] or [2, 3] for specific meaningful events, [1] for exact verbatim detail when you know the wording to match; otherwise drill down from [3] with inspect_memory. Omit to search all tiers blended, the right default for specific lookups. Mixing tiers is fine. Only tiers 2 and 3 carry importance ratings."
  4. Changed4 schema fields changed
    • changedInput schema / properties / importance / description
      Previous value: -"Only return memories rated at least this important (1 to 10). Only reflections carry ratings, so this filters to tier 2 and 3 content."New value: +"Minimum importance threshold, 1 to 10. Only reflections (tiers 2 and 3) carry ratings, so raw memories are excluded whenever this is set. Use 8 or higher with tiers [3] for broad 'most important' questions. Leave unset for general or specific searches; a high threshold hides relevant material."
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of relevant memories to return."New value: +"Maximum number of relevant memories to return. Use a large limit such as 100 for broad 'most important things' questions over tiers [3]."
    • changedInput schema / properties / limit / maximum
      Previous value: -20New value: +100
    • changedInput schema / properties / tiers / description
      Previous value: -"Restrict results to these memory tiers. 1 raw memories, 2 reflections, 3 high-level reflections. Omit to search all tiers blended."New value: +"Restrict results to these memory tiers. 3 highest-level consolidated reflections (identity, principles, what matters most), 2 reflections of specific meaningful events, 1 raw verbatim memories. Use [3] for broad 'most important' or big-picture questions, [2] or [2, 3] for specific meaningful events, [1] for exact verbatim detail. Omit to search all tiers blended, the right default for specific lookups. Mixing tiers is fine. Only tiers 2 and 3 carry importance ratings."
  5. Changed6 schema fields changed
    • addedInput schema / properties / importance
      Added value: +{
      +  "description": "Only return memories rated at least this important (1 to 10). Only reflections carry ratings, so this filters to tier 2 and 3 content.",
      +  "maximum": 10,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / tiers
      Added value: +{
      +  "description": "Restrict results to these memory tiers. 1 raw memories, 2 reflections, 3 high-level reflections. Omit to search all tiers blended.",
      +  "items": {
      +    "enum": [
      +      1,
      +      2,
      +      3
      +    ],
      +    "type": "integer"
      +  },
      +  "minItems": 1,
      +  "type": "array",
      +  "uniqueItems": true
      +}
    • addedOutput schema / properties / consolidation_available
      Added value: +{
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / memories / items / properties / importance
      Added value: +{
      +  "type": "integer"
      +}
    • addedOutput schema / properties / memories / items / properties / tier
      Added value: +{
      +  "type": "integer"
      +}
    • changedOutput schema / properties / memories / items / required
      Previous value: -[
      -  "id",
      -  "content",
      -  "source",
      -  "timestamp",
      -  "score"
      -]New value: +[
      +  "id",
      +  "content",
      +  "source",
      +  "timestamp",
      +  "score",
      +  "tier"
      +]
  6. First observed

TDQS

A4.7/5.0
Behavior5/5

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

The annotations already establish a safe read-only operation, but the description adds substantial behavioral context: it searches the user's OAuth-selected vault, uses semantic queries, and explains tier/importance behavior. It also discloses lineage drill-down mechanics and when a recall block means the search already ran.

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?

The description is front-loaded with the core usage rule, but it is a single dense paragraph with repeated tier explanations and many semicolon-linked rules. It is content-rich but harder to scan than it should be for a routing-heavy search tool.

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?

Given the output schema and annotations, the description covers the key usage, behavioral, and routing context an agent needs. It explains tier semantics, importance behavior, query construction, alternatives, and drill-down strategy without needing to describe return values.

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 the schema already documents all four parameters thoroughly. The description adds practical decision heuristics beyond the schema, such as when to omit tiers and importance, how to form queries, and when a high importance threshold hides detail, though much of the tier guide is repeated from 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?

The description states a specific verb and resource: semantic search over memories to retrieve context for a user message. It clearly distinguishes itself from date_search_memories and inspect_memory by describing time-window searches and lineage drill-downs as separate alternatives.

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 gives explicit when-to-use guidance: before each new user message, even when the user does not ask to remember. It also names when not to search again after a MemoryRouter recall block and routes time-window questions to date_search_memories.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources