133 lines
4.5 KiB
Markdown
133 lines
4.5 KiB
Markdown
---
|
|
layout: default
|
|
title: Get memory
|
|
parent: Memory APIs
|
|
grand_parent: ML Commons APIs
|
|
nav_order: 20
|
|
---
|
|
|
|
# Get a memory
|
|
**Introduced 2.12**
|
|
{: .label .label-purple }
|
|
|
|
Use this API to retrieve a conversational memory for [conversational search]({{site.url}}{{site.baseurl}}/search-plugins/conversational-search/).
|
|
|
|
To retrieve memory information, you can:
|
|
|
|
- [Get a memory by ID](#get-a-memory-by-id).
|
|
- [Get all memories](#get-all-memories).
|
|
|
|
To retrieve message information for a memory, you can:
|
|
|
|
- [Get all messages within a memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/get-message#get-all-messages-within-a-memory).
|
|
- [Search for messages within a memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/search-message/).
|
|
|
|
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.
|
|
{: .important}
|
|
|
|
## 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
|
|
|
|
```json
|
|
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
|
|
|
|
```json
|
|
GET /_plugins/_ml/memory/N8AE1osB0jLkkocYjz7D
|
|
```
|
|
{% include copy-curl.html %}
|
|
|
|
#### Example response
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
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
|
|
|
|
```json
|
|
GET /_plugins/_ml/memory/
|
|
```
|
|
{% include copy-curl.html %}
|
|
|
|
#### Example request: Paginating results
|
|
|
|
```json
|
|
GET /_plugins/_ml/memory?max_results=2&next_token=1
|
|
```
|
|
|
|
#### Example response
|
|
|
|
```json
|
|
{
|
|
"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. | |