Skip to content

Commit d45e504

Browse files
dhrubo-osdhrubo-os
committed
Add comprehensive agentic memory API documentation for OpenSearch 3.3
- Add long-term memory APIs: search, update, delete - Add memory history APIs: search, delete - Add general memory APIs: get, update, delete, search by type - Update add-memory API to include data type memory and structured data - Update index with complete API structure - Support for conversation memory, data memory, and trace data - Include namespace-based organization and tagging system - Remove experimental warning as agentic memory is GA in 3.3
1 parent 3076c3a commit d45e504

11 files changed

+972
-40
lines changed

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

Lines changed: 102 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,14 @@ nav_order: 40
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}
1513

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):
14+
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 memories in two types:
15+
16+
- **Conversation memory** -- Stores conversational messages between users and assistants. Can be processed (when `infer` is `true`) to extract facts or stored as raw messages.
17+
18+
- **Data memory** -- Stores structured, non-conversational data such as agent state, checkpoints, or reference information.
19+
20+
Memory processing modes (controlled by the `infer` parameter):
1721

1822
- 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.
1923

@@ -33,41 +37,113 @@ The following table lists the available request body fields.
3337

3438
Field | Data type | Required/Optional | Description
3539
:--- | :--- | :--- | :---
36-
`messages` | List | Required | A list of messages. Each message requires `content` and may include a `role` (commonly, `user` or `assistant`) when `infer` is set to `true`.
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+
`messages` | List | Conditional | A list of messages for conversation memory. Each message requires `content` and may include a `role` (commonly, `user` or `assistant`) when `infer` is set to `true`. Required for `memory_type` of `conversation`.
41+
`structured_data` | Object | Conditional | Structured data content for data memory. Required for `memory_type` of `data`.
42+
`memory_type` | String | Required | The type of memory: `conversation` or `data`.
43+
`namespace` | Object | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`).
44+
`session_id` | String | Optional | The session ID associated with the memory. Deprecated in favor of using `namespace.session_id`.
45+
`agent_id` | String | Optional | The agent ID associated with the memory. Deprecated in favor of using `namespace.agent_id`.
46+
`infer` | Boolean | Optional | Controls whether the LLM infers context from messages. Default is `true` for conversation memory, `false` for data memory. 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.
4047
`tags` | Object | Optional | Custom metadata for the agentic memory.
4148

42-
## Example request
49+
## Example requests
50+
51+
### Conversation memory
4352

4453
```json
4554
POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories
4655
{
47-
"messages": [
48-
{"role": "user", "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"
56+
"messages": [
57+
{
58+
"role": "user",
59+
"content": "I'm Bob, I really like swimming."
60+
},
61+
{
62+
"role": "assistant",
63+
"content": "Cool, nice. Hope you enjoy your life."
5464
}
65+
],
66+
"namespace": {
67+
"user_id": "bob"
68+
},
69+
"tags": {
70+
"topic": "personal info"
71+
},
72+
"infer": true,
73+
"memory_type": "conversation"
74+
}
75+
```
76+
77+
### Data memory
78+
79+
```json
80+
POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories
81+
{
82+
"structured_data": {
83+
"time_range": {
84+
"start": "2025-09-11",
85+
"end": "2025-09-15"
86+
}
87+
},
88+
"namespace": {
89+
"agent_id": "testAgent1"
90+
},
91+
"tags": {
92+
"topic": "agent_state"
93+
},
94+
"infer": false,
95+
"memory_type": "data"
96+
}
97+
```
98+
99+
### Trace data memory
100+
101+
```json
102+
POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories
103+
{
104+
"structured_data": {
105+
"tool_invocations": [
106+
{
107+
"tool_name": "ListIndexTool",
108+
"tool_input": {
109+
"filter": "*,-.plugins*"
110+
},
111+
"tool_output": "green open security-auditlog-2025.09.17..."
112+
}
113+
]
114+
},
115+
"namespace": {
116+
"user_id": "bob",
117+
"agent_id": "testAgent1",
118+
"session_id": "123"
119+
},
120+
"tags": {
121+
"topic": "personal info",
122+
"parent_memory_id": "o4-WWJkBFT7urc7Ed9hM",
123+
"data_type": "trace"
124+
},
125+
"infer": false,
126+
"memory_type": "conversation"
55127
}
56128
```
57129
{% include copy-curl.html %}
58130

59-
## Example response
131+
## Example responses
132+
133+
### Conversation memory response
134+
135+
```json
136+
{
137+
"session_id": "XSEuiJkBeh2gPPwzjYVh",
138+
"working_memory_id": "XyEuiJkBeh2gPPwzjYWM"
139+
}
140+
```
141+
142+
### Data memory response
60143

61144
```json
62145
{
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"
146+
"working_memory_id": "Z8xeTpkBvwXRq366l0iA"
71147
}
72148
```
73149

@@ -77,8 +153,5 @@ The following table lists all response body fields.
77153

78154
| Field | Data type | Description |
79155
| :-------------- | :-------- | :------------------------------------------------------------------------------------------------ |
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. |
156+
| `session_id` | String | The session ID associated with the memory (returned for conversation memory when a session is created or used). |
157+
| `working_memory_id` | String | The unique identifier for the created working memory entry. |

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

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
layout: default
3+
title: Delete long-term memory
4+
parent: Agentic Memory APIs
5+
grand_parent: ML Commons APIs
6+
nav_order: 33
7+
---
8+
9+
# Delete long-term memory
10+
**Introduced 3.2**
11+
{: .label .label-purple }
12+
13+
Use this API to delete a specific long-term memory from a memory container.
14+
15+
## Path and HTTP methods
16+
17+
```json
18+
DELETE /_plugins/_ml/memory_containers/<memory_container_id>/memories/long-term/<memory_id>
19+
```
20+
21+
## Path parameters
22+
23+
| Parameter | Data type | Description |
24+
| :--- | :--- | :--- |
25+
| `memory_container_id` | String | The ID of the memory container. Required. |
26+
| `memory_id` | String | The ID of the long-term memory to delete. Required. |
27+
28+
## Example request
29+
30+
```json
31+
DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz
32+
```
33+
{% include copy-curl.html %}
34+
35+
## Example response
36+
37+
```json
38+
{
39+
"result": "deleted",
40+
"_id": "DcxjTpkBvwXRq366C1Zz",
41+
"_version": 2,
42+
"_shards": {
43+
"total": 2,
44+
"successful": 1,
45+
"failed": 0
46+
}
47+
}
48+
```
49+
50+
## Response fields
51+
52+
| Field | Data type | Description |
53+
| :--- | :--- | :--- |
54+
| `result` | String | The result of the delete operation. |
55+
| `_id` | String | The ID of the deleted memory. |
56+
| `_version` | Integer | The version number after deletion. |
57+
| `_shards` | Object | Information about the shards involved in the operation. |

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
layout: default
3+
title: Delete memory by type and ID
4+
parent: Agentic Memory APIs
5+
grand_parent: ML Commons APIs
6+
nav_order: 53
7+
---
8+
9+
# Delete memory by type and ID
10+
**Introduced 3.2**
11+
{: .label .label-purple }
12+
13+
Use this API to delete a specific memory by its type and ID. This unified API supports deleting session, working, long-term, and history memory data.
14+
15+
## Path and HTTP methods
16+
17+
```json
18+
DELETE /_plugins/_ml/memory_containers/<memory_container_id>/memories/<type>/<id>
19+
```
20+
21+
## Path parameters
22+
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: "session", "working", "long-term", or "history". Required. |
27+
| `id` | String | The ID of the memory to delete. Required. |
28+
29+
## Example request
30+
31+
```json
32+
DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM
33+
```
34+
{% include copy-curl.html %}
35+
36+
## Example response
37+
38+
```json
39+
{
40+
"result": "deleted",
41+
"_id": "XyEuiJkBeh2gPPwzjYWM",
42+
"_version": 2,
43+
"_shards": {
44+
"total": 2,
45+
"successful": 1,
46+
"failed": 0
47+
}
48+
}
49+
```
50+
51+
## Response fields
52+
53+
| Field | Data type | Description |
54+
| :--- | :--- | :--- |
55+
| `result` | String | The result of the delete operation. |
56+
| `_id` | String | The ID of the deleted memory. |
57+
| `_version` | Integer | The version number after deletion. |
58+
| `_shards` | Object | Information about the shards involved in the operation. |

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

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
layout: default
3+
title: Delete memory history
4+
parent: Agentic Memory APIs
5+
grand_parent: ML Commons APIs
6+
nav_order: 42
7+
---
8+
9+
# Delete memory history
10+
**Introduced 3.2**
11+
{: .label .label-purple }
12+
13+
Use this API to delete specific memory history events from a memory container.
14+
15+
## Path and HTTP methods
16+
17+
```json
18+
DELETE /_plugins/_ml/memory_containers/<memory_container_id>/memories/history/<history_id>
19+
```
20+
21+
## Path parameters
22+
23+
| Parameter | Data type | Description |
24+
| :--- | :--- | :--- |
25+
| `memory_container_id` | String | The ID of the memory container. Required. |
26+
| `history_id` | String | The ID of the history event to delete. Required. |
27+
28+
## Example request
29+
30+
```json
31+
DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTpkBvwXRq366hmAU
32+
```
33+
{% include copy-curl.html %}
34+
35+
## Example response
36+
37+
```json
38+
{
39+
"result": "deleted",
40+
"_id": "eMxnTpkBvwXRq366hmAU",
41+
"_version": 2,
42+
"_shards": {
43+
"total": 2,
44+
"successful": 1,
45+
"failed": 0
46+
}
47+
}
48+
```
49+
50+
## Response fields
51+
52+
| Field | Data type | Description |
53+
| :--- | :--- | :--- |
54+
| `result` | String | The result of the delete operation. |
55+
| `_id` | String | The ID of the deleted history event. |
56+
| `_version` | Integer | The version number after deletion. |
57+
| `_shards` | Object | Information about the shards involved in the operation. |

0 commit comments

Comments
 (0)