ReferenceMCP toolsrecall

Tool Reference

recall

Retrieve relevant durable context when an agent needs a focused answer. Recall searches all of your memories by default; on the full MCP tool surface, pass bucket to search only one bucket.

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 /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

NameTypeDescription
querystring · requiredNatural-language question or topic to recall.
limitinteger · default: 5Small 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