memory_search
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
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Search mode | semantic |
| tags | No | Filter to memories with any of these tags | |
| after | No | Return memories created after this date (ISO format: YYYY-MM-DD) | |
| as_of | No | Point-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. | |
| limit | No | Maximum results to return | |
| query | No | Text search query (required for semantic/exact modes unless content_hash is supplied, optional for time-only searches) | |
| store | No | Target store partition (default: 'default'). Use 'docs' for documents, 'all' for cross-store search. | |
| before | No | Return memories created before this date (ISO format: YYYY-MM-DD) | |
| entity | No | Filter 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. | |
| rerank | No | Opt-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_id | No | Filter to memories authored by this agent (matches metadata.agent_id or the agent:<id> tag). Opt-in; omit to search all agents. | |
| fallback | No | Enable 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. | |
| summarize | No | Return 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_match | No | Match ANY tag (OR, default) or ALL tags (AND) | any |
| time_expr | No | Natural language time filter (e.g., 'last week', 'yesterday', '3 days ago') | |
| content_hash | No | Retrieve 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_debug | No | Include debug information in response | |
| quality_boost | No | Quality weight for reranking (0.0-1.0) | |
| include_beliefs | No | Include derived beliefs alongside memories. Beliefs are confidence-scored knowledge derived from observations. Each belief result includes result_type='belief' and confidence score. | |
| ranking_weights | No | Custom weights for ranked mode (keys: semantic, time_decay, access_frequency, quality). Values are normalized to sum=1.0. | |
| include_superseded | No | Include 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_chars | No | Maximum response size in characters. Truncates at memory boundaries to prevent context overflow. Recommended: 30000-50000. Default: unlimited. |