Reference

search

Search authorized memory when the relevant wording or record is not known in advance.

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 https://xmemo.dev/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

Strict project-scoped lookup

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.

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