Skip to content

Commit 9e54b68

Browse files
nathaliellenaakolchfa-awsnatebower
authored and
sumobrian
committed
Add Agentic Memory APIs (opensearch-project#10714)
* Add agentic memory APIs Signed-off-by: Nathalie Jonathan <[email protected]> * Add agentic memory APIs Signed-off-by: Nathalie Jonathan <[email protected]> * Address comments Signed-off-by: Nathalie Jonathan <[email protected]> * Add more info Signed-off-by: Nathalie Jonathan <[email protected]> * Doc review Signed-off-by: Fanit Kolchina <[email protected]> * Address comments Signed-off-by: Nathalie Jonathan <[email protected]> * Apply suggestions from code review Signed-off-by: kolchfa-aws <[email protected]> * Update _ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md Signed-off-by: kolchfa-aws <[email protected]> * Update _ml-commons-plugin/api/agentic-memory-apis/get-memory.md Signed-off-by: kolchfa-aws <[email protected]> * Apply suggestions from code review Signed-off-by: Nathan Bower <[email protected]> --------- Signed-off-by: Nathalie Jonathan <[email protected]> Signed-off-by: Fanit Kolchina <[email protected]> Signed-off-by: kolchfa-aws <[email protected]> Signed-off-by: Nathan Bower <[email protected]> Co-authored-by: Fanit Kolchina <[email protected]> Co-authored-by: kolchfa-aws <[email protected]> Co-authored-by: Nathan Bower <[email protected]>
1 parent 34c268c commit 9e54b68

File tree

10 files changed

+648
-1
lines changed

10 files changed

+648
-1
lines changed

‎_ml-commons-plugin/api/agentic-memory-apis/add-memory.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
layout: default
3+
title: Add agentic memory
4+
parent: Agentic Memory APIs
5+
grand_parent: ML Commons APIs
6+
nav_order: 40
7+
---
8+
9+
# Add Agentic Memory API
10+
**Introduced 3.2**
11+
{: .label .label-purple }
12+
13+
This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/).
14+
{: .warning}
15+
16+
Use this API to add an agentic memory to a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container). You can create a memory in one of the following modes (controlled by the `infer` parameter):
17+
18+
- Fact memory -- A processed representation of the message. The large language model (LLM) associated with the memory container extracts and stores key factual information or knowledge from the original text.
19+
20+
- Raw message memory -- The unprocessed message content.
21+
22+
Once an agentic memory is created, you'll provide its `memory_id` to other APIs.
23+
24+
## Endpoint
25+
26+
```json
27+
POST /_plugins/_ml/memory_containers/{memory_container_id}/memories
28+
```
29+
30+
## Request body fields
31+
32+
The following table lists the available request body fields.
33+
34+
Field | Data type | Required/Optional | Description
35+
:--- | :--- | :--- | :---
36+
`messages` | List | Required | A list of messages.
37+
`session_id` | String | Optional | The session ID associated with the memory.
38+
`agent_id` | String | Optional | The agent ID associated with the memory.
39+
`infer` | Boolean | Optional | Controls whether the LLM infers context from messages. Default is `true`. When `true`, the LLM extracts factual information from the original text and stores it as the memory. When `false`, the memory contains the unprocessed message and you must explicitly specify the `role` in each message.
40+
`tags` | Object | Optional | Custom metadata for the agentic memory.
41+
42+
## Example request
43+
44+
```json
45+
POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories
46+
{
47+
"messages": [
48+
{"role": "assistant", "content": "Machine learning is a subset of artificial intelligence"}
49+
],
50+
"session_id": "sess_789",
51+
"agent_id": "agent_123",
52+
"tags": {
53+
"topic": "personal info"
54+
}
55+
}
56+
```
57+
{% include copy-curl.html %}
58+
59+
## Example response
60+
61+
```json
62+
{
63+
"results": [
64+
{
65+
"id": "T9jtmpgBOh0h20Y91WtZ",
66+
"text": "Machine learning is a subset of artificial intelligence",
67+
"event": "ADD"
68+
}
69+
],
70+
"session_id": "sess_789"
71+
}
72+
```
73+
74+
## Response body fields
75+
76+
The following table lists all response body fields.
77+
78+
| Field | Data type | Description |
79+
| :-------------- | :-------- | :------------------------------------------------------------------------------------------------ |
80+
| `results` | List | A list of memory entries returned by the request. |
81+
| `results.id` | String | The unique identifier for the memory entry. |
82+
| `results.text` | String | If `infer` is `false`, contains the stored text from the message. If `infer` is `true`, contains the extracted fact from the message. |
83+
| `results.event` | String | The type of event for the memory entry. For the Add Agentic Memory API, the event type is always `ADD`, indicating that the memory was added. |
84+
| `session_id` | String | The session ID associated with the memory. |

‎_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
layout: default
3+
title: Create memory container
4+
parent: Agentic Memory APIs
5+
grand_parent: ML Commons APIs
6+
nav_order: 10
7+
---
8+
9+
# Create Memory Container API
10+
**Introduced 3.2**
11+
{: .label .label-purple }
12+
13+
This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/).
14+
{: .warning}
15+
16+
Use this API to create a memory container to hold agentic memories. The container can have two model types associated with it:
17+
18+
- A text embedding model for vectorizing the message so it can be searched. Use a text embedding model for dense vector embeddings or a sparse encoding model for sparse vector formats. If no embedding model is specified, messages are stored but cannot be used for vector-based searches.
19+
- A large language model (LLM) for reasoning over the message to produce factual or processed content. If no LLM is specified, messages are stored directly, without applying inference.
20+
21+
Once a memory container is created, you'll provide its `memory_container_id` to other APIs.
22+
23+
## Prerequisites
24+
25+
If you want to use one of the model types to process memories, register the models in OpenSearch.
26+
27+
### Embedding model
28+
29+
Register either a local or externally hosted embedding model. OpenSearch supports text embedding and sparse encoding models.
30+
31+
For more information about using models locally, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/using-ml-models/). For a list of supported models, see [OpenSearch-provided pretrained models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/pretrained-models/#supported-pretrained-models).
32+
33+
34+
For more information about using externally hosted models, see [Connecting to externally hosted models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/index/). For example, to register an externally hosted Amazon Titan Embeddings model, send the following request:
35+
36+
```json
37+
POST /_plugins/_ml/models/_register
38+
{
39+
"name": "Bedrock embedding model",
40+
"function_name": "remote",
41+
"description": "test model",
42+
"connector": {
43+
"name": "Amazon Bedrock Connector: embedding",
44+
"description": "The connector to bedrock Titan embedding model",
45+
"version": 1,
46+
"protocol": "aws_sigv4",
47+
"parameters": {
48+
"region": "us-east-1",
49+
"service_name": "bedrock",
50+
"model": "amazon.titan-embed-text-v2:0",
51+
"dimensions": 1024,
52+
"normalize": true,
53+
"embeddingTypes": [
54+
"float"
55+
]
56+
},
57+
"credential": {
58+
"access_key": "...",
59+
"secret_key": "...",
60+
"session_token": "..."
61+
},
62+
"actions": [
63+
{
64+
"action_type": "predict",
65+
"method": "POST",
66+
"url": "https://bedrock-runtime.${parameters.region}.amazonaws.com/model/${parameters.model}/invoke",
67+
"headers": {
68+
"content-type": "application/json",
69+
"x-amz-content-sha256": "required"
70+
},
71+
"request_body": """{ "inputText": "${parameters.inputText}", "dimensions": ${parameters.dimensions}, "normalize": ${parameters.normalize}, "embeddingTypes": ${parameters.embeddingTypes} }""",
72+
"pre_process_function": "connector.pre_process.bedrock.embedding",
73+
"post_process_function": "connector.post_process.bedrock.embedding"
74+
}
75+
]
76+
}
77+
}
78+
```
79+
{% include copy-curl.html %}
80+
81+
### LLM
82+
83+
OpenSearch supports the Anthropic Claude model for LLM capabilities. To register a Claude model, send the following request:
84+
85+
```json
86+
POST /_plugins/_ml/models/_register
87+
{
88+
"name": "Bedrock infer model",
89+
"function_name": "remote",
90+
"description": "test model",
91+
"connector": {
92+
"name": "Amazon Bedrock Connector: embedding",
93+
"description": "The connector to bedrock Claude 3.7 sonnet model",
94+
"version": 1,
95+
"protocol": "aws_sigv4",
96+
"parameters": {
97+
"region": "us-east-1",
98+
"service_name": "bedrock",
99+
"max_tokens": 8000,
100+
"temperature": 1,
101+
"anthropic_version": "bedrock-2023-05-31",
102+
"model": "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
103+
},
104+
"credential": {
105+
"access_key": "...",
106+
"secret_key": "...",
107+
"session_token": "..."
108+
},
109+
"actions": [
110+
{
111+
"action_type": "predict",
112+
"method": "POST",
113+
"headers": {
114+
"content-type": "application/json"
115+
},
116+
"url": "https://bedrock-runtime.${parameters.region}.amazonaws.com/model/${parameters.model}/invoke",
117+
"request_body": """{ "system": "${parameters.system_prompt}", "anthropic_version": "${parameters.anthropic_version}", "max_tokens": ${parameters.max_tokens}, "temperature": ${parameters.temperature}, "messages": ${parameters.messages} }"""
118+
}
119+
]
120+
}
121+
}
122+
```
123+
{% include copy-curl.html %}
124+
125+
The `system_prompt` parameter is required for Claude models.
126+
{: .note}
127+
128+
For more information about using externally hosted models, see [Connecting to externally hosted models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/index/).
129+
130+
## Endpoint
131+
132+
```json
133+
POST /_plugins/_ml/memory_containers/_create
134+
```
135+
136+
## Request body fields
137+
138+
The following table lists the available request body fields.
139+
140+
Field | Data type | Required/Optional | Description
141+
:--- | :--- | :--- | :---
142+
`name` | String | Required | The name of the memory container.
143+
`description` | String | Optional | The description of the memory container.
144+
`memory_storage_config` | Object | Optional | The memory storage configuration. See [the `memory_storage_config` object](#the-memory_storage_config-object).
145+
146+
### The memory_storage_config object
147+
148+
The `memory_storage_config` object supports the following fields.
149+
150+
Field | Data type | Required/Optional | Description
151+
:--- | :--- | :--- | :---
152+
`dimension` | Integer | Optional | The dimension of the embedding model. Required if `embedding_model_type` is `TEXT_EMBEDDING`.
153+
`embedding_model_id` | String | Optional | The embedding model ID.
154+
`embedding_model_type` | String | Optional | The embedding model type. Supported types are `TEXT_EMBEDDING` and `SPARSE_ENCODING`.
155+
`llm_model_id` | String | Optional | The LLM ID.
156+
`max_infer_size` | Integer | Optional | The maximum number of messages the LLM processes for inference in a single request. Valid values are 1--9, inclusive. Default is 5.
157+
`memory_index_name` | String | Optional | The name of the index in which to save messages, embeddings, and inferred facts. If not specified, a default index is automatically generated.
158+
159+
## Example request
160+
161+
```json
162+
POST /_plugins/_ml/memory_containers/_create
163+
{
164+
"name": "Sparse memory container",
165+
"description": "Store sparse conversations with semantic search",
166+
"memory_storage_config": {
167+
"llm_model_id": "bbphdJgB9L0Qb_M6ipnn",
168+
"embedding_model_type": "SPARSE_ENCODING",
169+
"embedding_model_id": "RodoX5gBfObQ5OgTHf1X"
170+
}
171+
}
172+
```
173+
{% include copy-curl.html %}
174+
175+
## Example response
176+
177+
The response contains the `memory_container_id` that you can use to retrieve or delete the container:
178+
179+
```json
180+
{
181+
"memory_container_id": "SdjmmpgBOh0h20Y9kWuN",
182+
"status": "created"
183+
}
184+
```

‎_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
layout: default
3+
title: Delete memory container
4+
parent: Agentic Memory APIs
5+
grand_parent: ML Commons APIs
6+
nav_order: 30
7+
---
8+
9+
# Delete Memory Container API
10+
**Introduced 3.2**
11+
{: .label .label-purple }
12+
13+
This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/).
14+
{: .warning}
15+
16+
Use this API to delete a memory container by its ID.
17+
18+
## Endpoint
19+
20+
```json
21+
DELETE /_plugins/_ml/memory_containers/{memory_container_id}
22+
```
23+
24+
## Example request
25+
26+
```json
27+
DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN
28+
```
29+
{% include copy-curl.html %}
30+
31+
## Example response
32+
33+
```json
34+
{
35+
"_index": ".plugins-ml-memory-container",
36+
"_id": "SdjmmpgBOh0h20Y9kWuN",
37+
"_version": 3,
38+
"result": "deleted",
39+
"forced_refresh": true,
40+
"_shards": {
41+
"total": 2,
42+
"successful": 2,
43+
"failed": 0
44+
},
45+
"_seq_no": 6,
46+
"_primary_term": 1
47+
}
48+
```

‎_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
layout: default
3+
title: Delete agentic memory
4+
parent: Agentic Memory APIs
5+
grand_parent: ML Commons APIs
6+
nav_order: 80
7+
---
8+
9+
# Delete Agentic Memory API
10+
**Introduced 3.2**
11+
{: .label .label-purple }
12+
13+
This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/).
14+
{: .warning}
15+
16+
Use this API to delete an agentic memory by its ID.
17+
18+
## Endpoint
19+
20+
```json
21+
DELETE /_plugins/_ml/memory_containers/{memory_container_id}/memories/{memory_id}
22+
```
23+
24+
## Example request
25+
26+
```json
27+
DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/T9jtmpgBOh0h20Y91WtZ
28+
```
29+
{% include copy-curl.html %}
30+
31+
## Example response
32+
33+
```json
34+
{
35+
"_index": "ml-static-memory-sdjmmpgboh0h20y9kwun-admin",
36+
"_id": "S9jnmpgBOh0h20Y9qWu7",
37+
"_version": 3,
38+
"result": "deleted",
39+
"_shards": {
40+
"total": 2,
41+
"successful": 2,
42+
"failed": 0
43+
},
44+
"_seq_no": 3,
45+
"_primary_term": 1
46+
}
47+
```

0 commit comments

Comments
 (0)