Skip to main content
Glama

memory_search

Read-only

Search stored memories by semantic, exact, hybrid, time, tag, or content-hash lookup to recall past decisions, preferences, and context.

Instructions

Search memories with flexible modes and filters. Primary tool for finding stored information.

USE THIS WHEN:

  • User asks "what do you remember about X", "recall", "find memories"

  • Looking for past decisions, preferences, context from previous sessions

  • Need semantic, exact, or time-based search

  • User references "last time we discussed", "you should know"

HASH LOOKUP:

  • Provide content_hash instead of query to retrieve one memory by its exact identifier

  • Hash misses return no results; they do not fall back to semantic search

  • query and content_hash are mutually exclusive; store scoping applies to both

  • Only store, entity, limit, max_response_chars, and include_beliefs may accompany content_hash

MODES:

  • semantic (default): Finds conceptually similar content even if exact words differ

  • exact: Finds memories containing the exact query string

  • hybrid: Combines semantic similarity with quality scoring

TIME FILTERS (can combine with other filters):

  • time_expr: Natural language like "yesterday", "last week", "2 days ago", "last month"

  • after/before: Explicit ISO dates (YYYY-MM-DD)

QUALITY BOOST (for semantic/hybrid modes):

  • 0.0 = pure semantic ranking (default)

  • 0.3 = 30% quality weight, 70% semantic (recommended for important lookups)

  • 1.0 = pure quality ranking

TAG FILTER:

  • Filter results to only memories with specific tags

  • Useful for categorical searches ("find all 'reference' memories about databases")

DEBUG:

  • include_debug=true adds timing, embedding info, filter details

SUMMARIZATION (opt-in):

  • summarize=true returns a query-aware LLM summary with validated source hashes

  • Requires a query and the existing HARVEST_LLM_PROVIDERS/GROQ_API_KEY configuration

  • Bounds model input at whole-memory boundaries; original memories remain stored

  • Returns raw results with a warning if summarization or source validation fails

Examples: {"query": "python async patterns"} {"content_hash": "aa6caea3d060e736c8b412e6b34a1354148ec04527a4bf547cfd4185140573d0"} {"query": "API endpoint", "mode": "exact"} {"time_expr": "last week", "limit": 20} {"query": "database config", "time_expr": "yesterday"} {"query": "architecture decisions", "tags": ["important"], "quality_boost": 0.3} {"after": "2024-01-01", "before": "2024-06-30", "limit": 50} {"query": "error handling", "include_debug": true} {"query": "replication consistency issue", "summarize": true}

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": "memory_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNoSearch modesemantic
tagsNoFilter to memories with any of these tags
afterNoReturn memories created after this date (ISO format: YYYY-MM-DD)
as_ofNoPoint-in-time query (issue #1724): return what was known at this moment. Accepts an ISO date/datetime (e.g. '2026-09-15', '2026-09-15T10:00:00Z'), 'YYYY' (the whole year, evaluated at its last second), or 'YYYY-MM' (evaluated at that month's last second). Results include memories with created_at <= as_of that had not been superseded by as_of. Status flags with include_superseded=true are evaluated at as_of as well.
limitNoMaximum results to return
queryNoText search query (required for semantic/exact modes unless content_hash is supplied, optional for time-only searches)
storeNoTarget store partition (default: 'default'). Use 'docs' for documents, 'all' for cross-store search.
beforeNoReturn memories created before this date (ISO format: YYYY-MM-DD)
entityNoFilter by linked entity name. Returns only memories linked to this entity via entity extraction. Requires a populated entity graph: run memory_quality {"action": "maintain", "dry_run": false} first (the dry_run default of true stores nothing). Unavailable on the Cloudflare backend.
rerankNoOpt-in second-stage ONNX rerank of the top MCP_RERANK_CANDIDATES results. Requires MCP_RERANK_ENABLED on the server; off by default and a no-op when the server flag is unset.
agent_idNoFilter to memories authored by this agent (matches metadata.agent_id or the agent:<id> tag). Opt-in; omit to search all agents.
fallbackNoEnable cascading fallback when semantic results are sparse. When true and fewer than 3 results are found with scores below 0.4, automatically attempts BM25 keyword match and tag intersection. Each result includes match_method field. Default: false.
summarizeNoReturn a query-aware LLM summary of the retrieved memories with source hashes and preserved metadata instead of their full contents. Requires operator permission via MCP_SEARCH_SUMMARIZE_ENABLED=true (off by default), a query, and a configured LLM provider. Falls back to raw results with a warning on failure.
tag_matchNoMatch ANY tag (OR, default) or ALL tags (AND)any
time_exprNoNatural language time filter (e.g., 'last week', 'yesterday', '3 days ago')
content_hashNoRetrieve one memory by its exact content hash instead of searching text. Only store, entity, limit, max_response_chars, and include_beliefs may accompany content_hash; query and other search arguments are rejected.
include_debugNoInclude debug information in response
quality_boostNoQuality weight for reranking (0.0-1.0)
include_beliefsNoInclude derived beliefs alongside memories. Beliefs are confidence-scored knowledge derived from observations. Each belief result includes result_type='belief' and confidence score.
ranking_weightsNoCustom weights for ranked mode (keys: semantic, time_decay, access_frequency, quality). Values are normalized to sum=1.0.
include_supersededNoInclude memories that have been superseded by newer contradicting memories. Default: false (superseded memories are hidden). When true, each result carries a status field ('current' or 'superseded') plus superseded_by and superseded_at when superseded.
max_response_charsNoMaximum response size in characters. Truncates at memory boundaries to prevent context overflow. Recommended: 30000-50000. Default: unlimited.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.0.1

TDQS

A4.4/5.0
Behavior4/5

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

Annotations only declare readOnlyHint, and the description adds real behavioral context: hash lookups return nothing rather than falling back, summarization needs operator flags and degrades to raw results with a warning, and memory input is bounded at whole-memory boundaries. It leaves several schema-level behaviors (fallback cascading, rerank gating, as_of point-in-time, superseded status) to the schema rather than summarizing them.

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?

Header-segmented and front-loaded, with the most important scoping rule stated in the first two sentences. It is long for a description, and the summarize/mode sections restate schema detail, but the examples block earns its space for a 22-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 22-parameter tool with no output schema, the description covers the high-risk paths (mode choice, hash lookup, summarization gating, debug). Gaps remain: the return shape is not described beyond summarize include-beliefs and debug notes, and newer parameters (fallback, rerank, as_of, include_superseded, agent_id, ranking_weights) appear nowhere in the description.

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%, but the description still adds meaning beyond it: it explains semantic vs exact vs hybrid outcome differences, how quality_boost weights trade off against similarity, that time filters combine with other filters, and the exact parameter constraints when content_hash is used.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Search memories') and adds a positioning claim ('Primary tool for finding stored information') that separates it from list/explore style siblings. It does not explicitly name any sibling tool, so the differentiation is implied rather than stated.

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?

A dedicated 'USE THIS WHEN' block gives concrete user phrasings and scenarios, and the HASH LOOKUP section spells out the when-not (query vs content_hash are mutually exclusive, hash misses do not fall back to semantic). Mode and time-filter sections give explicit selection criteria, including the recommended quality_boost value.

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