Skip to content

Commit 1340f34

Browse files
dhrubo-osdhrubo-os
committed
addressed comments
Signed-off-by: Dhrubo Saha <[email protected]>
1 parent f4d4bbf commit 1340f34

File tree

8 files changed

+207
-81
lines changed

8 files changed

+207
-81
lines changed

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

Lines changed: 11 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,7 @@ Use this API to add an agentic memory to a [memory container]({{site.url}}{{site
1717

1818
- **data** -- Stores extra messages, structured, non-conversational data such as agent state, checkpoints, or reference information.
1919

20-
- **infer=true** -- Use large language model (LLM) to extract key information or knowledge from the messages.
21-
22-
- **infer=false** -- Only store raw messages and data in working memory.
20+
- **infer** -- User can use infer to choose to extract key information from raw messages or not. If infer=true, Use large language model (LLM) to extract key information or knowledge from the messages. The extracted information will be stored as long-term memory. If infer=false, Only store raw messages and data in working memory.
2321

2422
Once an agentic memory is created, you'll provide its `memory_id` to other APIs.
2523

@@ -33,16 +31,16 @@ POST /_plugins/_ml/memory_containers/{memory_container_id}/memories
3331

3432
The following table lists the available request body fields.
3533

36-
Field | Data type | Required/Optional | Description
37-
:--- | :--- | :--- | :---
38-
`messages` | List | Conditional | A list of messages for conversational payload. Each message requires `content` and may include a `role` (commonly, `user` or `assistant`) when `infer` is set to `true`. Required for `payload_type` of `conversational`.
39-
`structured_data` | Map<String, Object> | Conditional | Structured data content for data memory. Required for `memory_type` of `data`.
40-
`binary_data` | String | Optional | Binary data content encoded as base64 string for binary payloads.
41-
`payload_type` | String | Required | The type of payload: `conversational` or `data`.
42-
`namespace` | List<String> | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). If `session_id` not exists in `namespace` will create a new session and use the new session's id.
43-
`metadata` | Map<String, String> | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields).
44-
`tags` | List<String> | Optional | Tags for categorizing and organizing memories.
45-
`infer` | Boolean | Optional | Controls whether use LLM to extract key information from messages. Default is `false`. When `true`, the LLM extracts key information from the original text and stores it as the memory.
34+
Field | Data type | Required/Optional | Description
35+
:--- |:---------------------| :--- | :---
36+
`messages` | List | Conditional | A list of messages for conversational payload. Each message requires `content`. Required for `payload_type` of `conversational`.
37+
`structured_data` | Map<String, Object> | Conditional | Structured data content for data memory. Required for `payload_type` of `data`.
38+
`binary_data` | String | Optional | Binary data content encoded as base64 string for binary payloads.
39+
`payload_type` | String | Required | The type of payload: `conversational` or `data`.
40+
`namespace` | List<String> | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). If `session_id` not exists in `namespace` will create a new session and use the new session's id.
41+
`metadata` | Map<String, Object> | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields).
42+
`tags` | List<String, String> | Optional | Tags for categorizing and organizing memories.
43+
`infer` | Boolean | Optional | Controls whether use LLM to extract key information from messages. Default is `false`. When `true`, the LLM extracts key information from the original text and stores it as the memory.
4644

4745
## Example requests
4846

@@ -107,8 +105,6 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories
107105
}
108106
```
109107

110-
### Trace data memory
111-
112108
Store agent trace data in working memory:
113109

114110
```json

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

Lines changed: 40 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -139,10 +139,10 @@ POST /_plugins/_ml/memory_containers/_create
139139
The following table lists the available request body fields.
140140

141141
Field | Data type | Required/Optional | Description
142-
:--- | :--- | :--- | :---
143-
`name` | String | Required | The name of the memory container.
144-
`description` | String | Optional | The description of the memory container.
145-
`configuration` | Object | Required | The memory container configuration. See [the `configuration` object](#the-configuration-object).
142+
:--- | :--- |:------------------| :---
143+
`name` | String | Required | The name of the memory container.
144+
`description` | String | Optional | The description of the memory container.
145+
`configuration` | Object | Optional | The memory container configuration. See [the `configuration` object](#the-configuration-object).
146146

147147
### The configuration object
148148

@@ -156,9 +156,44 @@ Field | Data type | Required/Optional | Description
156156
`llm_id` | String | Optional | The LLM model ID for processing and inference.
157157
`index_prefix` | String | Optional | Custom prefix for the memory indices. If not specified, a default prefix is used: if `use_system_index` is `true`, use `default` as index prefix; if `use_system_index` is `false`, use 8 bit random UUID as index prefix.
158158
`use_system_index` | Boolean | Optional | Whether to use system indices. Default is `true`.
159+
`disable_history` | Boolean | Optional | if disabled no history will be persisted. Default is `false`, so history will be persisted by default.
160+
`disable_session` | Boolean | Optional | if disabled no session will be persisted. Default is `true`, so session will not be persisted by default.
161+
`max_infer_size` | int | Optional | `max_infer_size` Controls the topK number of similar existing memories retrieved during memory consolidation to make ADD/UPDATE/DELETE decisions.
162+
`index_settings` | Map<String, Map<String, Object> | Optional | Customer can also provide the index settings. See [the `index settings` array](#the-index-settings).
159163
`strategies` | Array | Optional | Array of memory processing strategies. See [the `strategies` array](#the-strategies-array).
160164
`parameters` | Object | Optional | Global parameters for the memory container. See [the `parameters` object](#the-parameters-object).
161165

166+
### The index settings
167+
168+
Example of index settings
169+
170+
"index_settings": {
171+
"session_index" : {
172+
"index": {
173+
"number_of_shards": "2",
174+
"number_of_replicas": "2"
175+
}
176+
},
177+
"short_term_memory_index" : {
178+
"index": {
179+
"number_of_shards": "2",
180+
"number_of_replicas": "2"
181+
}
182+
},
183+
"long_term_memory_index" : {
184+
"index": {
185+
"number_of_shards": "2",
186+
"number_of_replicas": "2"
187+
}
188+
},
189+
"long_term_memory_history_index" : {
190+
"index": {
191+
"number_of_shards": "2",
192+
"number_of_replicas": "2"
193+
}
194+
}
195+
}
196+
162197
### The strategies array
163198

164199
Each strategy in the `strategies` array supports the following fields.
@@ -168,6 +203,7 @@ Field | Data type | Required/Optional | Description
168203
`type` | String | Required | The strategy type: `SEMANTIC`, `USER_PREFERENCE`, or `SUMMARY`.
169204
`namespace` | Array | Required | Array of namespace dimensions for organizing memories (e.g., `["user_id"]`, `["agent_id", "session_id"]`).
170205
`configuration` | Map<String, Object> | Optional | Strategy-specific configuration. See [the strategy `configuration` object](#the-strategy-configuration-object).
206+
`enabled` | boolean | Optional | To enable the Strategy in the memory container. Default is True.
171207

172208
### The strategy configuration object
173209

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

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,3 +76,79 @@ DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMx
7676
| `_id` | String | The ID of the deleted memory. |
7777
| `_version` | Integer | The version number after deletion. |
7878
| `_shards` | Object | Information about the shards involved in the operation. |
79+
80+
## Delete memory by query
81+
82+
You can also delete multiple memories using a query to match specific criteria.
83+
84+
### Path and HTTP methods
85+
86+
```json
87+
POST /_plugins/_ml/memory_containers/<memory_container_id>/memories/<type>/_delete_by_query
88+
```
89+
90+
### Path parameters
91+
92+
| Field | Data type | Required/Optional | Description |
93+
|:----------------------| :--- | :--- | :--- |
94+
| `memory_container_id` | String | Required | The ID of the memory container. |
95+
| `type` | String | Required | The type of memory: "sessions", "working", "long-term", or "history". |
96+
97+
### Request body
98+
99+
The request body should contain a query to match the memories you want to delete.
100+
101+
### Example request
102+
103+
```json
104+
POST /_plugins/_ml/memory_containers/{{container_id_user1}}/memories/working/_delete_by_query
105+
{
106+
"query": {
107+
"match": {
108+
"owner_id": "admin"
109+
}
110+
}
111+
}
112+
```
113+
{% include copy-curl.html %}
114+
115+
### Example response
116+
117+
```json
118+
{
119+
"took": 159,
120+
"timed_out": false,
121+
"total": 6,
122+
"updated": 0,
123+
"created": 0,
124+
"deleted": 6,
125+
"batches": 1,
126+
"version_conflicts": 0,
127+
"noops": 0,
128+
"retries": {
129+
"bulk": 0,
130+
"search": 0
131+
},
132+
"throttled_millis": 0,
133+
"requests_per_second": -1.0,
134+
"throttled_until_millis": 0,
135+
"failures": []
136+
}
137+
```
138+
139+
### Response fields
140+
141+
| Field | Data type | Description |
142+
| :--- | :--- | :--- |
143+
| `took` | Integer | The time in milliseconds it took to execute the request. |
144+
| `timed_out` | Boolean | Whether the request timed out. |
145+
| `total` | Integer | The total number of documents processed. |
146+
| `deleted` | Integer | The number of documents deleted. |
147+
| `batches` | Integer | The number of batches processed. |
148+
| `version_conflicts` | Integer | The number of version conflicts encountered. |
149+
| `noops` | Integer | The number of no-operation updates. |
150+
| `retries` | Object | Information about bulk and search retries. |
151+
| `throttled_millis` | Integer | The time in milliseconds the request was throttled. |
152+
| `requests_per_second` | Float | The number of requests processed per second. |
153+
| `throttled_until_millis` | Integer | The time in milliseconds until throttling is lifted. |
154+
| `failures` | Array | Any failures that occurred during the operation. |

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

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,6 @@ nav_order: 30
1010
**Introduced 3.2**
1111
{: .label .label-purple }
1212

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-
1613
Use this API to delete a memory container by its ID.
1714

1815
## Endpoint

‎_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,11 @@ GET /_plugins/_ml/memory_containers/<memory_container_id>/memories/<type>/<id>
2020

2121
## Path parameters
2222

23-
| Parameter | Data type | Description |
24-
| :--- | :--- | :--- |
25-
| `memory_container_id` | String | The ID of the memory container. Required. |
26-
| `type` | String | The type of memory: "sessions", "working", "long-term", or "history". Required. |
27-
| `id` | String | The ID of the memory to retrieve. Required. |
23+
| Parameter | Data type | Required/Optional | Description |
24+
| :--- | :--- | :--- | :--- |
25+
| `memory_container_id` | String | Required | The ID of the memory container. |
26+
| `type` | String | Required | The type of memory: "sessions", "working", "long-term", or "history". |
27+
| `id` | String | Required | The ID of the memory to retrieve. |
2828

2929
## Example requests
3030

‎_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md‎

Lines changed: 23 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -20,38 +20,43 @@ PUT /_plugins/_ml/memory_containers/<memory_container_id>/memories/<type>/<id>
2020

2121
## Path parameters
2222

23-
| Parameter | Data type | Description |
24-
| :--- | :--- | :--- |
25-
| `memory_container_id` | String | The ID of the memory container. Required. |
26-
| `type` | String | The type of memory: "sessions", "working", or "long-term". Required. Note: History memory cannot be updated. |
27-
| `id` | String | The ID of the memory to update. Required. |
23+
| Parameter | Data type | Required/Optional | Description |
24+
| :--- | :--- | :--- | :--- |
25+
| `memory_container_id` | String | Required | The ID of the memory container. |
26+
| `type` | String | Required | The type of memory: "sessions", "working", or "long-term". Note: History memory cannot be updated. |
27+
| `id` | String | Required | The ID of the memory to update. |
2828

2929
## Request fields
3030

3131
The request fields vary depending on the memory type being updated:
3232

3333
### For session memory
3434

35-
| Field | Data type | Description |
36-
| :--- | :--- | :--- |
37-
| `additional_info` | Object | Additional metadata to associate with the session. Optional. |
35+
| Field | Data type | Description |
36+
|:-----------|:----------------------| :--- |
37+
| `summary` | String | The summary of the session.
38+
| `metadata` | Map<String, Object> | Additional metadata for the memory (e.g., `status`, `branch`, custom fields).
39+
| `agents` | Map<String, Object> | Additional information about agents.
40+
| `additional_info` | Map<String, String> | Additional information about memory
41+
42+
3843

3944
### For working memory
4045

41-
| Field | Data type | Description |
42-
| :--- | :--- | :--- |
46+
| Field | Data type | Description |
47+
| :--- | :--- |:-----------------------------------------------------------------|
4348
| `messages` | Array | Updated conversation messages (for conversation type). Optional. |
44-
| `structured_data` | Object | Updated structured data content (for data type). Optional. |
45-
| `tags` | Object | Updated tags for categorization. Optional. |
46-
| `additional_info` | Object | Additional metadata. Optional. |
49+
| `structured_data` | Object | Updated structured data content (for data type). Optional. |
50+
| `binary_data` | Object | Updated binary data content (for data type). Optional. |
51+
| `tags` | Object | Updated tags for categorization. Optional. |
52+
| `metadata` | Map<String, Object> | Additional metadata for the memory (e.g., `status`, `branch`, custom fields).
4753

4854
### For long-term memory
4955

50-
| Field | Data type | Description |
51-
| :--- | :--- | :--- |
52-
| `memory` | String | The updated memory content. Optional. |
53-
| `tags` | Object | Updated tags for categorization. Optional. |
54-
| `additional_info` | Object | Additional metadata. Optional. |
56+
| Field | Data type | Description |
57+
| :--- | :--- |:-----------------------------------------------------------------------------------------------------------|
58+
| `memory` | String | The updated memory content. Optional. Updating memory field will automatically update the memory embedding |
59+
| `tags` | Object | Updated tags for categorization. Optional. |
5560

5661
## Example requests
5762

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

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ nav_order: 15
1010
**Introduced 3.3**
1111
{: .label .label-purple }
1212

13-
Use this API to update an existing memory container's properties such as name and description.
13+
Use this API to update an existing memory container's properties such as name, description, configuration, and access permissions.
1414

1515
## Path and HTTP methods
1616

@@ -20,23 +20,70 @@ PUT /_plugins/_ml/memory_containers/<memory_container_id>
2020

2121
## Path parameters
2222

23-
| Parameter | Data type | Description |
24-
| :--- | :--- | :--- |
25-
| `memory_container_id` | String | The ID of the memory container to update. Required. |
23+
| Parameter | Data type | Required/Optional | Description |
24+
| :--- | :--- | :--- | :--- |
25+
| `memory_container_id` | String | Required | The ID of the memory container to update. |
2626

2727
## Request fields
2828

2929
| Field | Data type | Required/Optional | Description |
3030
| :--- | :--- | :--- | :--- |
3131
| `name` | String | Optional | The updated name of the memory container. |
3232
| `description` | String | Optional | The updated description of the memory container. |
33+
| `configuration` | Object | Optional | Configuration object containing strategies and embedding settings. |
34+
35+
### Configuration object fields
36+
37+
| Field | Data type | Required/Optional | Description |
38+
| :--- | :--- | :--- | :--- |
39+
| `llm_id` | String | Optional | The large language model ID to use to extract facts. |
40+
| `strategies` | Array | Optional | Array of strategy objects for memory processing. |
41+
| `embedding_model_id` | String | Optional | The embedding model ID. Can only be updated if no long-term memory index exists. |
42+
| `embedding_model_type` | String | Optional | The embedding model type. Can only be updated if no long-term memory index exists. |
43+
| `embedding_dimension` | Integer | Optional | The embedding dimension. Can only be updated if no long-term memory index exists. |
44+
45+
## Update behavior
46+
47+
### Strategy updates
48+
- **Update existing strategy**: Include the strategy `id` to update that specific strategy.
49+
- **Create new strategy**: Specify a strategy without an `id` to create a new strategy.
50+
51+
### Backend roles updates
52+
- Adding new `backend_roles` grants new users read or write access with those roles.
53+
- The `backend_roles` field is updated by overwriting, so include original roles if you want to keep them.
54+
55+
### Namespace updates
56+
- The `namespace` field inside strategies is updated by overwriting.
57+
- Include the original namespace if you want to keep it.
58+
59+
### Embedding model restrictions
60+
- The `embedding_model_id`, `embedding_model_type`, and `embedding_dimension` fields can only be updated if no long-term memory index has been created for this memory container.
61+
- Once a long-term memory index with the specified `index_prefix` is created, these embedding fields cannot be updated.
62+
3363

3464
## Example request
3565

3666
```json
3767
PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU
3868
{
39-
"name": "opensearch-agents-memory"
69+
"name": "opensearch-agents-memory",
70+
"description": "Updated memory container for OpenSearch agents",
71+
"backend_roles": ["admin", "ml_user"],
72+
"configuration": {
73+
"strategies": [
74+
{
75+
"id": "existing_strategy_id",
76+
"type": "summarization",
77+
"namespace": "updated_namespace"
78+
},
79+
{
80+
"type": "keyword_extraction"
81+
}
82+
],
83+
"embedding_model_id": "new_embedding_model",
84+
"embedding_model_type": "dense",
85+
"embedding_dimension": 768
86+
}
4087
}
4188
```
4289
{% include copy-curl.html %}

0 commit comments

Comments
 (0)