Search Memories
searchRetrieve relevant project memories by query or filters, with optional task-aware retrieval planning that returns observations for context.
Instructions
Read-only. Search or list curated memories: query is optional for standard search, while project/type/branch and visibility flags filter results. Optional task_intent/role/risk/token_budget/include_superseded compiles a GH-934 RetrievalPlan, applies its search/rerank/fallback policy, and returns retrieval_plan audit metadata. Returns a compact JSON object with results, source='memory', pagination, and next_step for get_observations(ids, source); limit defaults to 20 and offset to 0. Use current_state when an exact stable state_key is known, timeline for chronological observation context, and search_raw for literal chat recall. explain and multi_hop each require a non-blank query, and explain cannot be combined with multi_hop=true. Invalid combinations or curated-search database failures return a tool error; an automatic raw-archive fallback failure preserves the curated results and adds raw_hits_error to the successful response.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| risk | No | Risk class for task-aware retrieval planning: low, medium, or high (default medium). High risk disables raw fallback and only requests router-approved rerank. | |
| role | No | Agent role for task-aware retrieval planning: coder, reviewer, planner, or researcher (default coder). Only used when task-aware routing is requested. | |
| type | No | Observation type filter | |
| limit | No | Max results to return (default 20) | |
| query | No | Search query (semantic search) | |
| branch | No | Git branch filter (e.g. 'main', 'feat/auth'). Only returns memories from this branch. Old data without branch info is always included. | |
| offset | No | Result offset for pagination | |
| explain | No | Include retrieval scoring and visibility explanation for standard search (default false). Not supported with multi_hop=true. | |
| project | No | Project name filter | |
| multi_hop | No | Enable multi-hop search (default false). When true, performs entity graph expansion: finds entities in first-hop results, then searches for memories mentioning those entities. Use for questions that span multiple topics/people, e.g. 'What do Melanie\'s kids like?' or 'What events has Caroline participated in?' | |
| task_intent | No | Optional task-aware retrieval intent. Accepted values: resume_work/resume-work, explain_decision/explain-decision, debug_failure/debug-failure, apply_preference/apply-preference, review_change/review-change, explore_history/explore-history. When set, MCP search compiles a GH-934 RetrievalPlan and applies its execution policy. | |
| token_budget | No | Total token budget recorded in the task-aware RetrievalPlan (default 4000). Must be greater than zero. | |
| include_stale | No | Include stale or archived memories (default false) | |
| include_superseded | No | Allow superseded history in the task-aware RetrievalPlan. This does not replace include_stale; use include_stale=true when the search result set should include inactive rows. | |
| include_suppressed | No | Include policy-suppressed memories (default false) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| explain | Yes | ||
| results | Yes | ||
| has_more | No | ||
| raw_hits | No | ||
| multi_hop | No | ||
| next_step | Yes | ||
| pagination | Yes | ||
| next_offset | No | ||
| raw_hits_note | No | ||
| raw_hits_error | No | ||
| retrieval_plan | No |