# recall

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

- Canonical: https://docs.xmemo.dev/docs/tools/recall
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 0f08e4c24f060d77b83bbadbfe1ffa6bd1404b06af31d63ed9354c94ff494498
- Edition-Digest: d07e2b97c43e0581c89a4c821e2c9343e8ecf790f3f5e4e9a0681e27148dcfc9
- Source-Revision: sha256:22f4bea2f1dccd2d5601395a4ac7009d7b5c4c85d61f1e0d580af211437edef6

## Tool Reference: `recall`

### Purpose

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

### Parameters

- `query` (string, required): Natural-language question or topic to recall.
- `limit` (integer, optional, default: 5): Small result count; keep it bounded for a quick lookup.

### Returns

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.

### 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.

### Examples

#### Quick best-effort recall



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

### Related Tools

- [search_memory](/docs/tools/search): Use strict targeted matching with project/team filters.
- [recall_context](/docs/tools/recall-context): Use a bounded multi-memory context pack.
- [remember](/docs/tools/remember): Persist an explicitly durable fact or decision.

## 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.

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