Reference

recall

Retrieve relevant durable context when an agent needs a focused answer from an approved memory scope.

Tell an empty result from a failure

An empty result is a valid no-match answer. A missing or insufficient credential fails with 401 or 403 instead.

recall({ query: "a topic that was never saved", limit: 3 })
// -> empty result set, HTTP 200

Public MCP tool

recall

Purpose

Perform a lightweight, forgiving best-effort lookup and return the few most relevant saved memories before answering.

When to use

You need a quick, unscoped answer and weak-but-useful relevance is acceptable.
The caller wants a small ranked set of memories rather than a prompt-sized context pack.
A task-start check needs recent working context without a strict project/team filter.

When NOT to use

Do not use it when a weak match must not be presented as the answer; use search_memory for strict matching.
Do not use it to assemble several bounded memories for prompt injection; use recall_context.
Do not use it to write, update, or delete 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; returned memories still remain bounded by the authenticated owner/team scope.

Parameters

Name	Type	Description
`query`	string · required	Natural-language question or topic to recall.
`limit`	integer · default: 5	Small result count; keep it bounded for a quick lookup.

Return schema

A ranked text response containing each memory reference, location, content, and available attribution boundary. Empty results are a valid no-match response, not an authorization signal.

Examples

Quick best-effort recall

recall({
  query: "current MCP authentication decision",
  limit: 3
})

Errors

401/403: the request has no valid bearer token or lacks memory:read.
Validation failure: query, limit, or filter syntax is invalid.
Scope or team mismatch: the requested boundary is not visible to the authenticated owner.

search_memory — Use strict targeted matching with project/team filters.
recall_context — Use a bounded multi-memory context pack.
remember — Persist an explicitly durable fact or decision.

Source: MCP tool surface