Retrieval

Retrieve Memories

Changed on Oct 6, 2026

Tailored memory retrieval for agentic workloads. Supports hybrid semantic search, date ranges, and configurable result limits for different memory types. This endpoint is optimized for conversational AI and memory retrieval use cases. If a query is not specified then one is inferred from the conversation context. If neither a query nor a conversationId is provided, results are returned in most-recent order without relevance scores.

post/v1/Stores/{storeId}/Profiles/{profileId}/Recall

Request

Base URL
https://memory.twilio.com
URL
https://memory.twilio.com/v1/Stores/{storeId}/Profiles/{profileId}/Recall
Auth
HTTP basic

Headers

Accept-Encodingstring

Example:gzip, deflate, br

Compression algorithms supported by the client (e.g., gzip, deflate, br)

Content-Encoding'gzip' | 'deflate' | 'br' | 'compress'

Example:gzip

Compression algorithm used for the request body (e.g., gzip, deflate, br)

Request body

conversationIdstring

A unique identifier for the conversation using Twilio Type ID (TTID) format.

querystring

Hybrid search query for finding relevant memories. Omit to use query expansion to generate query from previous 10 communications in conversation.

beginDatestring date-time

Start date for filtering memories (inclusive).

endDatestring date-time

End date for filtering memories (exclusive).

communicationsLimitinteger

Maximum number of conversational session memories to return. If omitted or set to 0, no session memories will be fetched.

observationsLimitinteger

Maximum number of observation memories to return. If omitted, defaults to 20. If set to 0, no observation memories will be fetched.

summariesLimitinteger

Maximum number of summary memories to return. If omitted, defaults to 5. If set to 0, no summary memories will be fetched.

relevanceThresholdnumber double

Minimum relevance score threshold for observations and summaries to be returned. Only memories with a relevance score greater than or equal to this threshold will be included in the response. This threshold only applies when results are ranked by relevance. When results are returned in most-recent order, this field has no effect.

Example request

{
  "conversationId": "conv_conversation_00000000000000000000000000",
  "query": "customer satisfaction feedback",
  "beginDate": "2025-01-01T00:00:00Z",
  "endDate": "2025-01-31T23:59:59Z",
  "communicationsLimit": 10,
  "observationsLimit": 20,
  "summariesLimit": 5,
  "relevanceThreshold": 0.5
}

Response

Memory retrieval results returned successfully.

Example response

{
  "observations": [
    {
      "content": "Customer expressed satisfaction with recent product update during support call.",
      "occurredAt": "2025-01-15T10:15:30Z",
      "source": "conversational-intelligence",
      "conversationIds": [
        "conv_conversation_00000000000000000000000000"
      ],
      "id": "mem_observation_00000000000000000000000000",
      "createdAt": "2025-01-15T10:30:45Z",
      "updatedAt": "2025-01-15T10:30:45Z",
      "score": 0.82
    }
  ],
  "summaries": [
    {
      "source": "conversations",
      "content": "Customer discussed billing concerns and was satisfied with the resolution provided during this conversation.",
      "occurredAt": "2025-01-15T10:15:30Z",
      "conversationId": "conv_conversation_00000000000000000000000000",
      "id": "mem_summary_00000000000000000000000000",
      "createdAt": "2025-01-15T10:30:45Z",
      "updatedAt": "2025-01-15T10:30:45Z",
      "score": 0.78
    }
  ],
  "communications": [
    {
      "id": "conv_communication_00000000000000000000000000",
      "channelId": "SM00000000000000000000000000000000",
      "content": {
        "text": "Hello, I need help with my account"
      },
      "createdAt": "2025-01-15T10:15:30Z",
      "updatedAt": "2025-01-15T10:20:30Z",
      "author": {
        "id": "conv_participant_00000000000000000000000000",
        "profileId": "mem_profile_00000000000000000000000000",
        "address": "+12025551234"
      },
      "recipients": [
        {
          "id": "conv_participant_00000000000000000000000000",
          "profileId": "mem_profile_00000000000000000000000000",
          "address": "+12025551234"
        }
      ]
    }
  ],
  "meta": {
    "queryTime": 156
  }
}

Changes

Oct 6, 2026v18f92a002d9f1 Revision changes
- info
  the // response's property pattern was changed from ^[a-zA-Z0-9 _.-]+$ to ^[a-zA-Z0-9 _./-]+$ for the status
- info
  the // response's property pattern was changed from ^[a-zA-Z0-9 _.-]+$ to ^[a-zA-Z0-9 _./-]+$ for the status
Aug 11, 2026v1b0ed05460bbf Revision changes
- breaking
  the response property's max was increased from 99999.00 to 999999.00 for the response status
- breaking
  the response property's max was increased from 99999.00 to 999999.00 for the response status
- breaking
  the response property's max was increased from 99999.00 to 999999.00 for the response status
- breaking
  the response property's max was increased from 99999.00 to 999999.00 for the response status
- breaking
  the response property's max was increased from 99999.00 to 999999.00 for the response status
- breaking
  the response property's max was increased from 99999.00 to 999999.00 for the response status
- breaking
  the response property's max was increased from 99999.00 to 999999.00 for the response status

Operation history