---
title: "Retrieve Memories"
method: POST
path: "/v1/Stores/{storeId}/Profiles/{profileId}/Recall"
tags: ["Retrieval"]
---

# Retrieve Memories

`POST /v1/Stores/{storeId}/Profiles/{profileId}/Recall`

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.

## Headers

- `Accept-Encoding` string
- `Content-Encoding` 'gzip' | 'deflate' | 'br' | 'compress'

## Request body

- MemoryRetrievalRequest — Request payload for retrieving profile memories with advanced filtering and semantic search.
  - `conversationId` string — A unique identifier for the conversation using Twilio Type ID (TTID) format.
  - `query` string — Hybrid search query for finding relevant memories. Omit to use query expansion to generate query from previous 10 communications in conversation.
  - `beginDate` string, date-time — Start date for filtering memories (inclusive).
  - `endDate` string, date-time — End date for filtering memories (exclusive).
  - `communicationsLimit` integer — Maximum number of conversational session memories to return. If omitted or set to 0, no session memories will be fetched.
  - `observationsLimit` integer — Maximum number of observation memories to return. If omitted, defaults to 20. If set to 0, no observation memories will be fetched.
  - `summariesLimit` integer — Maximum number of summary memories to return. If omitted, defaults to 5. If set to 0, no summary memories will be fetched.
  - `relevanceThreshold` number, 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.

## Response `200`

Memory retrieval results returned successfully.

- MemoryRetrievalResponse — Response containing retrieved profile memories organized by type.
  - `observations` RecallObservationInfo[], required — Array of observation memories.
    - `content` string, required — The main content of the observation.
    - `occurredAt` string, date-time, required — The timestamp when the observation originally occurred.
    - `source` string, required — The source system that generated this observation. Allows letters, numbers, spaces, and URL-safe symbols. Excludes URL-unsafe characters like quotes, angle brackets, and control characters.
    - `conversationIds` ConversationID[] — Array of conversation IDs associated with this observation.
    - `id` string, required — A unique identifier for the observation using Twilio Type ID (TTID) format.
    - `createdAt` string, date-time, required — The timestamp when the observation was created.
    - `updatedAt` string, date-time, required — The timestamp when the observation was last updated.
    - `score` number, double — The relevance score of the observation in relation to the query. Higher values indicate greater relevance. This field is omitted when results are returned in most-recent order. This may occur when no query is provided and one cannot be inferred from the conversation context, or when the system defaults to chronological retrieval to ensure high availability.
  - `summaries` RecallSummaryInfo[], required — Array of summary memories derived from observations at the end of conversations.
    - `source` string — The source system that generated the summary. Allows letters, numbers, spaces, and URL-safe symbols. Excludes URL-unsafe characters like quotes, angle brackets, and control characters.
    - `content` string, required — The main content of the summary.
    - `occurredAt` string, date-time, required — The timestamp when the summary was originally created.
    - `conversationId` string, required — A unique identifier for the conversation using Twilio Type ID (TTID) format.
    - `id` string, required — A unique identifier for the summary using Twilio Type ID (TTID) format.
    - `createdAt` string, date-time, required — The timestamp when the summary was created.
    - `updatedAt` string, date-time, required — The timestamp when the summary was last updated.
    - `score` number, double — The relevance score of the summary in relation to the query. Higher values indicate greater relevance. This field is omitted when results are returned in most-recent order. This may occur when no query is provided and one cannot be inferred from the conversation context, or when the system defaults to chronological retrieval to ensure high availability.
  - `communications` Communication[], required — Array of recent communication context.
    - `id` string, required — Unique communication identifier.
    - `channelId` string — Channel-specific ID (optional).
    - `content` CommunicationContent, required — Content of a communication.
      - `text` string — Primary text content (optional).
    - `createdAt` string, date-time — When communication was created.
    - `updatedAt` string, date-time — When communication was last updated.
    - `author` Participant, required
      - `id` string, required — Participant identifier.
      - `name` string, required — Participant display name
      - `type` 'HUMAN_AGENT' | 'CUSTOMER' | 'AI_AGENT' | 'AGENT' | 'UNKNOWN' — Type of Participant in the Conversation
      - `profileId` string — The canonical profile ID.
      - `address` string, required — Address of the Participant (e.g., phone number, email address)
      - `channel` 'VOICE' | 'SMS' | 'RCS' | 'EMAIL' | 'WHATSAPP' | 'CHAT' | 'API' | 'SYSTEM', required — The channel on which the message originated
    - `recipients` object[], required — Communication recipients
      - `id` string, required — Participant identifier.
      - `name` string, required — Participant display name
      - `type` 'HUMAN_AGENT' | 'CUSTOMER' | 'AI_AGENT' | 'AGENT' | 'UNKNOWN' — Type of Participant in the Conversation
      - `profileId` string — The canonical profile ID.
      - `address` string, required — Address of the Participant (e.g., phone number, email address)
      - `channel` 'VOICE' | 'SMS' | 'RCS' | 'EMAIL' | 'WHATSAPP' | 'CHAT' | 'API' | 'SYSTEM', required — The channel on which the message originated
      - `deliveryStatus` 'INITIATED' | 'IN_PROGRESS' | 'DELIVERED' | 'COMPLETED' | 'FAILED' — Delivery status of the Communication to this recipient
  - `meta` object, required — Metadata about the retrieval operation.
    - `queryTime` integer, required — Query execution time in milliseconds.

## Other responses

- `308` — This resource has moved.
- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `429` — This error indicates that you have sent too many requests to the API. You should retry according to the `Retry-After` response header.
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/twilio/apis/memory-v1.md) · [All operations](https://skmtc.net/twilio/apis/memory-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/twilio/memory-v1/versions/1cfcc8fb9f19/schema)