Narrow a search that returns too much
Add the scope and path filters before raising the limit; a wider limit on an unscoped query returns more noise, not more signal.
search_memory({
query: "token identity fallback",
limit: 5
})Public MCP tool
search_memory
Purpose
Search authorized XMemo memories with strict targeted-match semantics, so weak matches are not silently treated as the answer.
When to use
- The caller knows the relevant project, team, path, or memory type and needs a targeted lookup.
- A weak semantic match would be misleading or unsafe to present as a result.
- You need explicit scope/team filters, retrieval explanations, or a larger controlled result set.
When NOT to use
- Do not use it for a quick unscoped, forgiving lookup; use recall.
- Do not use it to build a multi-memory prompt context pack; use recall_context.
- Do not use it to mutate or remove a memory.
- The REST API accepts a wider field set than the public MCP tool; see /docs/api/memory for scope, bucket, team and provenance filters.
Required scope
- memory:read is required; scope and team_id filters cannot expand the caller's authorization boundary.
Parameters
| Name | Type | Description |
|---|---|---|
query | string · required | Exact topic or wording to match. |
limit | integer · default: 5 | Result count. |
path_filter | string · default: % | Claude plugin profile only: logical-path ILIKE filter. Not accepted on the generic public profile. |
memory_type | string · default: % | Claude plugin profile only: memory type filter. Not accepted on the generic public profile. |
prefer_working | boolean · default: false | Claude plugin profile only: place active working state before vector results. |
Return schema
A ranked text response with opaque references, locations, content, and optional explanation/agent-boundary metadata. The result is still limited to authorized memories.
Examples
search_memory({
query: "token identity fallback",
limit: 5
})Errors
- 401/403: the request lacks memory:read or cannot access the selected scope/team.
- Validation failure: query, limit, path pattern, or memory type is invalid.
- No-match response: no strong result satisfies the target and authorized filters; callers should not substitute recall semantics silently.
Related tools
- recall — Use forgiving best-effort retrieval when strict matching is unnecessary.
- recall_context — Use bounded multi-memory retrieval for prompt context.
- forget — Remove an exact record only after reviewing its returned reference.
Source: MCP tool surface