> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memanto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Recall

> Run semantic search across an agent's stored memories using natural language.

## Overview

Run semantic search across stored memories. This retrieves contextually relevant memories for the active agent based on semantic similarity to the query. Filters are sent as **JSON in the request body** only (no query-string parameters).

## Authentication

API clients do not send an API key or `Authorization` header.

<ParamField header="X-Session-Token" type="string" required>
  Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

## Path Parameters

<ParamField path="agent_id" type="string" required>
  The unique identifier of the agent.
</ParamField>

## Body

<ParamField body="query" type="string" required>
  Natural-language search text matched against the agent's memories (max 1000 characters).
</ParamField>

<ParamField body="limit" type="integer">
  Maximum number of results to return. Range `1`–`100`. If omitted, the server default applies (`RECALL_LIMIT`).
</ParamField>

<ParamField body="min_similarity" type="number">
  Minimum similarity score in the range `0.0`–`1.0` to filter out less relevant memories.
</ParamField>

<ParamField body="type" type="array">
  Optional list of memory type filters (e.g. `["fact", "preference"]`).
</ParamField>

## ITS Scoring System

<Snippet file="its-scoring.mdx" />

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall" \
    -H "X-Session-Token: your_session_token" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "user preferences",
      "limit": 10,
      "min_similarity": 0.2,
      "type": ["preference"]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - OK theme={null}
  {
    "agent_id": "my-agent",
    "session_id": "sess_cf824a95d305",
    "query": "user preferences",
    "memories": [
      {
        "id": "3e681f12-a28c-4d1d-9632-b8dadf1f9d0c",
        "title": "User Preference Note",
        "content": "Prefers email communication",
        "text": "[PREFERENCE] User Preference Note\n\nPrefers email communication",
        "type": "preference",
        "confidence": 0.98,
        "status": "active",
        "tags": [],
        "created_at": "2026-03-26T09:00:00.000000",
        "updated_at": "2026-03-26T09:00:00.000000",
        "actor_id": "my-agent",
        "source": "agent",
        "source_ref": null,
        "agent_id": "my-agent",
        "score": 0.086334,
        "provenance": "explicit_statement"
      }
    ],
    "count": 1
  }
  ```

  ```json 401 - Unauthorized (Missing Token) theme={null}
  {
    "detail": "Missing session token. Use X-Session-Token header."
  }
  ```

  ```json 401 - Unauthorized (Expired Token) theme={null}
  {
    "detail": {
      "error": "SessionExpired",
      "message": "Session has expired",
      "details": {}
    }
  }
  ```

  ```json 422 - Validation Error theme={null}
  {
    "detail": [
      {
        "type": "missing",
        "loc": ["body", "query"],
        "msg": "Field required",
        "input": {}
      }
    ]
  }
  ```

  ```json 413 - Payload Too Large (Query Too Long) theme={null}
  {
    "detail": {
      "error": "query_too_long",
      "message": "Query exceeds maximum length of 1000 characters",
      "actual_length": 1500,
      "max_length": 1000
    }
  }
  ```

  ```json 400 - Bad Request (Limit Too Large) theme={null}
  {
    "detail": {
      "error": "k_too_large",
      "message": "k exceeds maximum of 100",
      "actual_k": 200,
      "max_k": 100
    }
  }
  ```

  ```json 500 - Server Error theme={null}
  {
    "detail": {
      "error": "InternalServerError",
      "message": "An unexpected error occurred",
      "details": {
        "original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
      }
    }
  }
  ```
</ResponseExample>

## Next Steps

* [Generate AI Answer](/api-reference/ai/generate-ai-answer) to have an LLM synthesize the returned memories into a response
* [Recall Recent](/api-reference/search/recall-recent) to fetch the most recently stored memories
* [Recall As Of](/api-reference/search/recall-as-of) for point-in-time queries
* [Recall Changed Since](/api-reference/search/recall-changed-since) for differential retrieval