Link Search Menu Expand Document Documentation Menu

You're viewing version 2.16 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Get a memory

Introduced 2.12

Use this API to retrieve a conversational memory for conversational search.

To retrieve memory information, you can:

To retrieve message information for a memory, you can:

When the Security plugin is enabled, all memories exist in a private security mode. Only the user who created a memory can interact with that memory and its messages.

Get a memory by ID

You can retrieve memory information by using the memory_id. The response includes all messages within the memory.

Path and HTTP methods

GET /_plugins/_ml/memory/<memory_id>

Path parameters

The following table lists the available path parameters.

Parameter Data type Description
memory_id String The ID of the memory to retrieve.

Example request

GET /_plugins/_ml/memory/N8AE1osB0jLkkocYjz7D

Example response

{
  "memory_id": "gW8Aa40BfUsSoeNTvOKI",
  "create_time": "2024-02-02T18:07:06.887061463Z",
  "updated_time": "2024-02-02T19:01:32.121444968Z",
  "name": "Conversation for a RAG pipeline",
  "user": "admin"
}

Get all memories

Use this command to get all memories.

Path and HTTP methods

GET /_plugins/_ml/memory

Query parameters

Use the following query parameters to customize your results. All query parameters are optional.

Parameter Data type Description
max_results Integer The maximum number of results to return. If there are fewer memories than the number set in max_results, the response returns only the number of memories that exist. Default is 10.
next_token Integer The index of the first memory in the sorted list of memories to return. Memories are ordered by create_time. For example, if memories A, B, and C exist, next_token=1 returns memories B and C. Default is 0 (return all memories).

Paginating results

The next_token parameter provides the ordered position of the first memory within the sorted list of memories to return in the results. When a memory is added between subsequent GET Memory calls, one of the listed memories will be duplicated in the results. For example, suppose the current ordered list of memories is BCDEF, where B is the memory created most recently. When you call the Get Memory API with next_token=0 and max_results=3, the API returns BCD. Suppose you then create another memory A. The memory list now appears as ABCDEF. The next time you call the Get Memory API with next_token=3 and max_results=3, you’ll receive DEF in the results. Notice that D will be returned in the first and second batches of results. The following diagram illustrates the duplication.

Request List of memories (returned memories are enclosed in brackets) Results returned in the response
Get Memory (next_token = 0, max_results = 3) [BCD]EF BCD
Create Memory ABCDEF -
Get Memory (next_token = 3, max_results = 3) -> ABC[DEF] DEF  

Example request: Get all memories

GET /_plugins/_ml/memory/

Example request: Paginating results

GET /_plugins/_ml/memory?max_results=2&next_token=1

Example response

{
  "memories": [
    {
      "memory_id": "gW8Aa40BfUsSoeNTvOKI",
      "create_time": "2024-02-02T18:07:06.887061463Z",
      "updated_time": "2024-02-02T19:01:32.121444968Z",
      "name": "Conversation for a RAG pipeline",
      "user": "admin"
    }
  ]
}

Response fields

The following table lists the available response fields.

Field Data type Description
memory_id String The memory ID.
create_time String The time at which the memory was created.
updated_time String The time at which the memory was last updated.
name String The memory name.
user String The username of the user who created the memory.
350 characters left

Have a question? .

Want to contribute? or .