From b08069d5be20af52c11a08a6217da29b0e9e9682 Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Wed, 1 Oct 2025 16:32:07 -0700 Subject: [PATCH 01/27] 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 Signed-off-by: Dhrubo Saha --- .../api/agentic-memory-apis/add-memory.md | 131 +++++++++++---- .../delete-long-term-memory.md | 57 +++++++ .../delete-memory-by-type.md | 58 +++++++ .../delete-memory-history.md | 57 +++++++ .../agentic-memory-apis/get-memory-by-type.md | 92 ++++++++++ .../api/agentic-memory-apis/index.md | 40 +++-- .../search-long-term-memory.md | 137 +++++++++++++++ .../search-memories-by-type.md | 157 ++++++++++++++++++ .../search-memory-history.md | 117 +++++++++++++ .../update-long-term-memory.md | 75 +++++++++ .../update-memory-by-type.md | 91 ++++++++++ 11 files changed, 972 insertions(+), 40 deletions(-) create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/delete-memory-history.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 1e298dc4f18..76a9187ac8a 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -10,10 +10,14 @@ nav_order: 40 **Introduced 3.2** {: .label .label-purple } -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/). -{: .warning} -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): +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: + +- **Conversation memory** -- Stores conversational messages between users and assistants. Can be processed (when `infer` is `true`) to extract facts or stored as raw messages. + +- **Data memory** -- Stores structured, non-conversational data such as agent state, checkpoints, or reference information. + +Memory processing modes (controlled by the `infer` parameter): - 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. @@ -33,41 +37,113 @@ The following table lists the available request body fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`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`. -`session_id` | String | Optional | The session ID associated with the memory. -`agent_id` | String | Optional | The agent ID associated with the memory. -`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. +`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`. +`structured_data` | Object | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. +`memory_type` | String | Required | The type of memory: `conversation` or `data`. +`namespace` | Object | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). +`session_id` | String | Optional | The session ID associated with the memory. Deprecated in favor of using `namespace.session_id`. +`agent_id` | String | Optional | The agent ID associated with the memory. Deprecated in favor of using `namespace.agent_id`. +`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. `tags` | Object | Optional | Custom metadata for the agentic memory. -## Example request +## Example requests + +### Conversation memory ```json POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories { - "messages": [ - {"role": "user", "content": "Machine learning is a subset of artificial intelligence"} - ], - "session_id": "sess_789", - "agent_id": "agent_123", - "tags": { - "topic": "personal info" + "messages": [ + { + "role": "user", + "content": "I'm Bob, I really like swimming." + }, + { + "role": "assistant", + "content": "Cool, nice. Hope you enjoy your life." } + ], + "namespace": { + "user_id": "bob" + }, + "tags": { + "topic": "personal info" + }, + "infer": true, + "memory_type": "conversation" +} +``` + +### Data memory + +```json +POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories +{ + "structured_data": { + "time_range": { + "start": "2025-09-11", + "end": "2025-09-15" + } + }, + "namespace": { + "agent_id": "testAgent1" + }, + "tags": { + "topic": "agent_state" + }, + "infer": false, + "memory_type": "data" +} +``` + +### Trace data memory + +```json +POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories +{ + "structured_data": { + "tool_invocations": [ + { + "tool_name": "ListIndexTool", + "tool_input": { + "filter": "*,-.plugins*" + }, + "tool_output": "green open security-auditlog-2025.09.17..." + } + ] + }, + "namespace": { + "user_id": "bob", + "agent_id": "testAgent1", + "session_id": "123" + }, + "tags": { + "topic": "personal info", + "parent_memory_id": "o4-WWJkBFT7urc7Ed9hM", + "data_type": "trace" + }, + "infer": false, + "memory_type": "conversation" } ``` {% include copy-curl.html %} -## Example response +## Example responses + +### Conversation memory response + +```json +{ + "session_id": "XSEuiJkBeh2gPPwzjYVh", + "working_memory_id": "XyEuiJkBeh2gPPwzjYWM" +} +``` + +### Data memory response ```json { - "results": [ - { - "id": "T9jtmpgBOh0h20Y91WtZ", - "text": "Machine learning is a subset of artificial intelligence", - "event": "ADD" - } - ], - "session_id": "sess_789" + "working_memory_id": "Z8xeTpkBvwXRq366l0iA" } ``` @@ -77,8 +153,5 @@ The following table lists all response body fields. | Field | Data type | Description | | :-------------- | :-------- | :------------------------------------------------------------------------------------------------ | -| `results` | List | A list of memory entries returned by the request. | -| `results.id` | String | The unique identifier for the memory entry. | -| `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. | -| `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. | -| `session_id` | String | The session ID associated with the memory. | +| `session_id` | String | The session ID associated with the memory (returned for conversation memory when a session is created or used). | +| `working_memory_id` | String | The unique identifier for the created working memory entry. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md new file mode 100644 index 00000000000..c5c0f653ec6 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md @@ -0,0 +1,57 @@ +--- +layout: default +title: Delete long-term memory +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 33 +--- + +# Delete long-term memory +**Introduced 3.2** +{: .label .label-purple } + +Use this API to delete a specific long-term memory from a memory container. + +## Path and HTTP methods + +```json +DELETE /_plugins/_ml/memory_containers//memories/long-term/ +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `memory_id` | String | The ID of the long-term memory to delete. Required. | + +## Example request + +```json +DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "result": "deleted", + "_id": "DcxjTpkBvwXRq366C1Zz", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the delete operation. | +| `_id` | String | The ID of the deleted memory. | +| `_version` | Integer | The version number after deletion. | +| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md new file mode 100644 index 00000000000..0861d95b90c --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md @@ -0,0 +1,58 @@ +--- +layout: default +title: Delete memory by type and ID +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 53 +--- + +# Delete memory by type and ID +**Introduced 3.2** +{: .label .label-purple } + +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. + +## Path and HTTP methods + +```json +DELETE /_plugins/_ml/memory_containers//memories// +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `type` | String | The type of memory: "session", "working", "long-term", or "history". Required. | +| `id` | String | The ID of the memory to delete. Required. | + +## Example request + +```json +DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "result": "deleted", + "_id": "XyEuiJkBeh2gPPwzjYWM", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the delete operation. | +| `_id` | String | The ID of the deleted memory. | +| `_version` | Integer | The version number after deletion. | +| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-history.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-history.md new file mode 100644 index 00000000000..e912b4df488 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-history.md @@ -0,0 +1,57 @@ +--- +layout: default +title: Delete memory history +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 42 +--- + +# Delete memory history +**Introduced 3.2** +{: .label .label-purple } + +Use this API to delete specific memory history events from a memory container. + +## Path and HTTP methods + +```json +DELETE /_plugins/_ml/memory_containers//memories/history/ +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `history_id` | String | The ID of the history event to delete. Required. | + +## Example request + +```json +DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTpkBvwXRq366hmAU +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "result": "deleted", + "_id": "eMxnTpkBvwXRq366hmAU", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the delete operation. | +| `_id` | String | The ID of the deleted history event. | +| `_version` | Integer | The version number after deletion. | +| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md new file mode 100644 index 00000000000..5940b448af8 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md @@ -0,0 +1,92 @@ +--- +layout: default +title: Get memory by type and ID +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 51 +--- + +# Get memory by type and ID +**Introduced 3.2** +{: .label .label-purple } + +Use this API to retrieve a specific memory by its type and ID. This unified API supports four types of memory data: session, working, long-term, and history. + +## Path and HTTP methods + +```json +GET /_plugins/_ml/memory_containers//memories// +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `type` | String | The type of memory: "session", "working", "long-term", or "history". Required. | +| `id` | String | The ID of the memory to retrieve. Required. | + +## Example request + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "memory_container_id": "HudqiJkB1SltqOcZusVU", + "memory_type": "conversation", + "messages": [ + { + "role": "user", + "content_text": "I'm Bob, I really like swimming." + }, + { + "role": "assistant", + "content_text": "Cool, nice. Hope you enjoy your life." + } + ], + "namespace": { + "user_id": "bob", + "session_id": "S-dqiJkB1SltqOcZ1cYO" + }, + "infer": true, + "tags": { + "topic": "personal info" + }, + "created_time": 1758930326804, + "last_updated_time": 1758930326804 +} +``` + +## Response fields + +The response fields vary depending on the memory type: + +### Working memory response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. | +| `memory_type` | String | The type of memory: "conversation" or "data". | +| `messages` | Array | Array of conversation messages (for conversation type). | +| `structured_data` | Object | Structured data content (for data type). | +| `namespace` | Object | The namespace context for this memory. | +| `tags` | Object | Associated tags for categorization. | +| `infer` | Boolean | Whether inference was enabled for this memory. | +| `created_time` | Long | Timestamp when the memory was created. | +| `last_updated_time` | Long | Timestamp when the memory was last updated. | + +### Long-term memory response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `memory` | String | The extracted long-term memory fact. | +| `namespace` | Object | The namespace context for this memory. | +| `memory_type` | String | The type of memory strategy used. | +| `tags` | Object | Associated tags for categorization. | +| `created_time` | Long | Timestamp when the memory was created. | +| `last_updated_time` | Long | Timestamp when the memory was last updated. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/index.md b/_ml-commons-plugin/api/agentic-memory-apis/index.md index ff5a7f73a62..cd9f8c98d68 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/index.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/index.md @@ -13,20 +13,17 @@ redirect_from: **Introduced 3.2** {: .label .label-purple } -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/). -{: .warning} - Agentic Memory APIs provide persistent memory management for AI agents. This enables agents to learn, remember, and reason over structured information across conversations. -## Enabling Agentic Memory APIs +## Disabling Agentic Memory APIs -To enable Agentic Memory APIs, update the following cluster setting: +As Agentinc memory is GA in 3.3, this feature is enabled by default. To disable Agentic Memory APIs, update the following cluster setting: ```json PUT /_cluster/settings { "persistent": { - "plugins.ml_commons.agentic_memory_enabled": true + "plugins.ml_commons.agentic_memory_enabled": false } } ``` @@ -38,12 +35,33 @@ OpenSearch supports the following memory container APIs: - [Create memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container/) - [Get memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory-container/) +- [Update memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory-container/) - [Delete memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory-container/) +- [Search memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory-container/) OpenSearch supports the following memory APIs: -- [Add memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/add-memory/) -- [Get memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/) -- [Search memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory/) -- [Update memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory/) -- [Delete memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory/) \ No newline at end of file +## Working memory APIs + +- [Add working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/add-memory/) +- [Get working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/) +- [Search working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory/) +- [Delete working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory/) + +## Long-term memory APIs + +- [Search long-term memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory/) +- [Update long-term memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory/) +- [Delete long-term memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory/) + +## Memory history APIs + +- [Search memory history]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory-history/) +- [Delete memory history]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory-history/) + +## General memory APIs + +- [Get memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type/) +- [Update memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type/) +- [Delete memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type/) +- [Search memories by type]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type/) \ No newline at end of file diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md new file mode 100644 index 00000000000..1942e273039 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md @@ -0,0 +1,137 @@ +--- +layout: default +title: Search long-term memory +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 31 +--- + +# Search long-term memory +**Introduced 3.2** +{: .label .label-purple } + +Use this API to search for long-term memories within a memory container. Long-term memories are extracted facts from conversation messages that are stored for semantic retrieval. + +## Path and HTTP methods + +```json +GET /_plugins/_ml/memory_containers//memories/long-term/_search +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | + +## Request fields + +The request body supports standard OpenSearch query DSL. Common fields include: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `query` | Object | The search query using OpenSearch query DSL. Optional. | +| `sort` | Array | Sort criteria for the results. Optional. | +| `size` | Integer | Maximum number of results to return. Optional. | +| `from` | Integer | Starting index for pagination. Optional. | + +## Example request + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/_search +{ + "query": { + "bool": { + "must": [ + { + "term": { + "namespace.user_id": "bob" + } + } + ] + } + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "took": 5, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 2, + "relation": "eq" + }, + "max_score": null, + "hits": [ + { + "_index": "test1-long-term-memory", + "_id": "DcxjTpkBvwXRq366C1Zz", + "_score": null, + "_source": { + "created_time": 1757956737699, + "memory": "User's name is Bob", + "last_updated_time": 1757956737699, + "namespace_size": 1, + "namespace": { + "user_id": "bob" + }, + "memory_type": "SEMANTIC", + "tags": { + "topic": "personal info" + } + }, + "sort": [1757956737699] + }, + { + "_index": "test1-long-term-memory", + "_id": "DsxjTpkBvwXRq366C1Zz", + "_score": null, + "_source": { + "created_time": 1757956737699, + "memory": "Bob really likes swimming", + "last_updated_time": 1757956737699, + "namespace_size": 1, + "namespace": { + "user_id": "bob" + }, + "memory_type": "SEMANTIC", + "tags": { + "topic": "personal info" + } + }, + "sort": [1757956737699] + } + ] + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `memory` | String | The extracted long-term memory fact. | +| `namespace` | Object | The namespace context for this memory. | +| `memory_type` | String | The type of memory strategy used (e.g., "SEMANTIC"). | +| `tags` | Object | Associated tags for categorization. | +| `created_time` | Long | Timestamp when the memory was created. | +| `last_updated_time` | Long | Timestamp when the memory was last updated. | +| `namespace_size` | Integer | The size of the namespace. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md new file mode 100644 index 00000000000..6419abe9859 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md @@ -0,0 +1,157 @@ +--- +layout: default +title: Search memories by type +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 54 +--- + +# Search memories by type +**Introduced 3.2** +{: .label .label-purple } + +Use this API to search for memories of a specific type within a memory container. This unified API supports searching session, working, long-term, and history memory data. + +## Path and HTTP methods + +```json +GET /_plugins/_ml/memory_containers//memories//_search +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `type` | String | The type of memory: "session", "working", "long-term", or "history". Required. | + +## Request fields + +The request body supports standard OpenSearch query DSL. Common fields include: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `query` | Object | The search query using OpenSearch query DSL. Optional. | +| `sort` | Array | Sort criteria for the results. Optional. | +| `size` | Integer | Maximum number of results to return. Optional. | +| `from` | Integer | Starting index for pagination. Optional. | + +## Example requests + +### Search session memories + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/session/_search +{ + "query": { + "match_all": {} + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` + +### Search working memories with namespace filter + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_search +{ + "query": { + "bool": { + "must": [ + { + "term": { + "namespace.user_id": "bob" + } + } + ], + "must_not": [ + { + "exists": { + "field": "tags.parent_memory_id" + } + } + ] + } + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` + +### Search trace data by session + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_search +{ + "query": { + "term": { + "namespace.session_id": "123" + } + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "took": 5, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 1, + "relation": "eq" + }, + "max_score": null, + "hits": [ + { + "_index": "test1-session", + "_id": "CcxjTpkBvwXRq366A1aE", + "_score": null, + "_source": { + "memory_container_id": "HudqiJkB1SltqOcZusVU", + "namespace": { + "user_id": "bob" + }, + "created_time": "2025-09-15T17:18:55.881276939Z", + "last_updated_time": "2025-09-15T17:18:55.881276939Z" + }, + "sort": ["2025-09-15T17:18:55.881276939Z"] + } + ] + } +} +``` + +## Response fields + +The response fields vary depending on the memory type being searched. See the individual memory type documentation for specific field descriptions: + +- [Working memory fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/) +- [Long-term memory fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory/) +- [Memory history fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory-history/) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md new file mode 100644 index 00000000000..987aa2c4fc9 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md @@ -0,0 +1,117 @@ +--- +layout: default +title: Search memory history +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 41 +--- + +# Search memory history +**Introduced 3.2** +{: .label .label-purple } + +Use this API to search for memory history events within a memory container. Memory history tracks all add, update, and delete operations performed on long-term memories. + +## Path and HTTP methods + +```json +GET /_plugins/_ml/memory_containers//memories/history/_search +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | + +## Request fields + +The request body supports standard OpenSearch query DSL. Common fields include: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `query` | Object | The search query using OpenSearch query DSL. Optional. | +| `sort` | Array | Sort criteria for the results. Optional. | +| `size` | Integer | Maximum number of results to return. Optional. | +| `from` | Integer | Starting index for pagination. Optional. | + +## Example request + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/_search +{ + "query": { + "match_all": {} + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "took": 3, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 4, + "relation": "eq" + }, + "max_score": null, + "hits": [ + { + "_index": "test1-long-term-memory-history", + "_id": "eMxnTpkBvwXRq366hmAU", + "_score": null, + "_source": { + "created_time": "2025-09-15T17:23:51.302920078Z", + "memory_id": "DsxjTpkBvwXRq366C1Zz", + "action": "DELETE", + "after": { + "memory": "Bob really likes swimming" + } + }, + "sort": ["2025-09-15T17:23:51.302920078Z"] + }, + { + "_index": "test1-long-term-memory-history", + "_id": "ecxnTpkBvwXRq366hmAU", + "_score": null, + "_source": { + "created_time": "2025-09-15T17:23:51.303097838Z", + "memory_id": null, + "action": "ADD", + "after": { + "memory": "User doesn't like swimming currently" + } + }, + "sort": ["2025-09-15T17:23:51.303097838Z"] + } + ] + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `action` | String | The type of operation performed: "ADD", "UPDATE", or "DELETE". | +| `memory_id` | String | The ID of the affected memory (null for ADD operations). | +| `created_time` | String | ISO timestamp when the operation occurred. | +| `after` | Object | The memory content after the operation. | +| `before` | Object | The memory content before the operation (for UPDATE operations). | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md new file mode 100644 index 00000000000..fbe89790462 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md @@ -0,0 +1,75 @@ +--- +layout: default +title: Update long-term memory +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 32 +--- + +# Update long-term memory +**Introduced 3.2** +{: .label .label-purple } + +Use this API to update an existing long-term memory within a memory container. + +## Path and HTTP methods + +```json +PUT /_plugins/_ml/memory_containers//memories/long-term/ +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `memory_id` | String | The ID of the long-term memory to update. Required. | + +## Request fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `memory` | String | The updated memory content. Optional. | +| `tags` | Object | Updated tags for categorization. Optional. | +| `additional_info` | Object | Additional metadata to associate with the memory. Optional. | + +## Example request + +```json +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz +{ + "memory": "User's name is Bob Smith", + "tags": { + "topic": "personal info", + "updated": "true" + }, + "additional_info": { + "source": "user_correction" + } +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "result": "updated", + "_id": "DcxjTpkBvwXRq366C1Zz", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the update operation. | +| `_id` | String | The ID of the updated memory. | +| `_version` | Integer | The version number of the updated memory. | +| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md new file mode 100644 index 00000000000..14b09047011 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md @@ -0,0 +1,91 @@ +--- +layout: default +title: Update memory by type and ID +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 52 +--- + +# Update memory by type and ID +**Introduced 3.2** +{: .label .label-purple } + +Use this API to update a specific memory by its type and ID. This unified API supports updating session, working, and long-term memory data. History memory does not support updates. + +## Path and HTTP methods + +```json +PUT /_plugins/_ml/memory_containers//memories// +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `type` | String | The type of memory: "session", "working", or "long-term". Required. | +| `id` | String | The ID of the memory to update. Required. | + +## Request fields + +The request fields vary depending on the memory type being updated: + +### For session memory + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `additional_info` | Object | Additional metadata to associate with the session. Optional. | + +### For working memory + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `messages` | Array | Updated conversation messages (for conversation type). Optional. | +| `structured_data` | Object | Updated structured data content (for data type). Optional. | +| `tags` | Object | Updated tags for categorization. Optional. | +| `additional_info` | Object | Additional metadata. Optional. | + +### For long-term memory + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `memory` | String | The updated memory content. Optional. | +| `tags` | Object | Updated tags for categorization. Optional. | +| `additional_info` | Object | Additional metadata. Optional. | + +## Example request + +```json +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/session/N2CDipkB2Mtr6INFFcX8 +{ + "additional_info": { + "key1": "value1", + "last_activity": "2025-09-15T17:30:00Z" + } +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "result": "updated", + "_id": "N2CDipkB2Mtr6INFFcX8", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the update operation. | +| `_id` | String | The ID of the updated memory. | +| `_version` | Integer | The version number of the updated memory. | +| `_shards` | Object | Information about the shards involved in the operation. | From b0144d764526b1ec8b17015987c00accca399a4d Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Thu, 9 Oct 2025 18:15:28 -0700 Subject: [PATCH 02/27] Consolidate agentic memory APIs and update with real response examples - Remove redundant API files in favor of unified memory APIs - Delete legacy files: delete-long-term-memory.md, delete-memory-history.md, search-long-term-memory.md, search-memory-history.md, update-long-term-memory.md, search-memory.md, delete-memory.md, update-memory.md, get-memory.md - Enhance unified APIs with comprehensive examples for all memory types (sessions, working, long-term, history) - Add metadata field documentation to add-memory.md and get-memory-by-type.md - Update response examples and field documentation with actual API responses - Update index.md to reflect clean unified API structure - Fix memory type parameter names (sessions vs session) for consistency Signed-off-by: Dhrubo Saha --- .../api/agentic-memory-apis/add-memory.md | 20 +++ .../delete-long-term-memory.md | 57 ------- .../delete-memory-by-type.md | 26 +++- .../delete-memory-history.md | 57 ------- .../api/agentic-memory-apis/delete-memory.md | 47 ------ .../agentic-memory-apis/get-memory-by-type.md | 141 ++++++++++++++++-- .../api/agentic-memory-apis/get-memory.md | 57 ------- .../api/agentic-memory-apis/index.md | 21 +-- .../search-long-term-memory.md | 137 ----------------- .../search-memories-by-type.md | 56 ++++++- .../search-memory-history.md | 117 --------------- .../api/agentic-memory-apis/search-memory.md | 58 ------- .../update-long-term-memory.md | 75 ---------- .../update-memory-by-type.md | 33 +++- .../api/agentic-memory-apis/update-memory.md | 58 ------- 15 files changed, 252 insertions(+), 708 deletions(-) delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/delete-memory-history.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/delete-memory.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/get-memory.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-memory.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/update-memory.md diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 76a9187ac8a..1798a2896d5 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -41,6 +41,7 @@ Field | Data type | Required/Optional | Description `structured_data` | Object | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. `memory_type` | String | Required | The type of memory: `conversation` or `data`. `namespace` | Object | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). +`metadata` | Object | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). `session_id` | String | Optional | The session ID associated with the memory. Deprecated in favor of using `namespace.session_id`. `agent_id` | String | Optional | The agent ID associated with the memory. Deprecated in favor of using `namespace.agent_id`. `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. @@ -66,6 +67,13 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "namespace": { "user_id": "bob" }, + "metadata": { + "status": "checkpoint", + "branch": { + "branch_name": "high", + "root_event_id": "228nadfs879mtgk" + } + }, "tags": { "topic": "personal info" }, @@ -88,6 +96,10 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "namespace": { "agent_id": "testAgent1" }, + "metadata": { + "status": "checkpoint", + "anyobject": "abc" + }, "tags": { "topic": "agent_state" }, @@ -117,6 +129,14 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "agent_id": "testAgent1", "session_id": "123" }, + "metadata": { + "status": "checkpoint", + "branch": { + "branch_name": "high", + "root_event_id": "228nadfs879mtgk" + }, + "anyobject": "abc" + }, "tags": { "topic": "personal info", "parent_memory_id": "o4-WWJkBFT7urc7Ed9hM", diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md deleted file mode 100644 index c5c0f653ec6..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -layout: default -title: Delete long-term memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 33 ---- - -# Delete long-term memory -**Introduced 3.2** -{: .label .label-purple } - -Use this API to delete a specific long-term memory from a memory container. - -## Path and HTTP methods - -```json -DELETE /_plugins/_ml/memory_containers//memories/long-term/ -``` - -## Path parameters - -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | -| `memory_id` | String | The ID of the long-term memory to delete. Required. | - -## Example request - -```json -DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "result": "deleted", - "_id": "DcxjTpkBvwXRq366C1Zz", - "_version": 2, - "_shards": { - "total": 2, - "successful": 1, - "failed": 0 - } -} -``` - -## Response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `result` | String | The result of the delete operation. | -| `_id` | String | The ID of the deleted memory. | -| `_version` | Integer | The version number after deletion. | -| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md index 0861d95b90c..08fe2adc097 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md @@ -10,7 +10,7 @@ nav_order: 53 **Introduced 3.2** {: .label .label-purple } -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. +Use this API to delete a specific memory by its type and ID. This unified API supports deleting all memory types: session, working, long-term, and history memory data. ## Path and HTTP methods @@ -23,14 +23,34 @@ DELETE /_plugins/_ml/memory_containers//memories///memories/history/ -``` - -## Path parameters - -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | -| `history_id` | String | The ID of the history event to delete. Required. | - -## Example request - -```json -DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTpkBvwXRq366hmAU -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "result": "deleted", - "_id": "eMxnTpkBvwXRq366hmAU", - "_version": 2, - "_shards": { - "total": 2, - "successful": 1, - "failed": 0 - } -} -``` - -## Response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `result` | String | The result of the delete operation. | -| `_id` | String | The ID of the deleted history event. | -| `_version` | Integer | The version number after deletion. | -| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md deleted file mode 100644 index e7263b60e44..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -layout: default -title: Delete agentic memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 80 ---- - -# Delete Agentic Memory API -**Introduced 3.2** -{: .label .label-purple } - -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/). -{: .warning} - -Use this API to delete an agentic memory by its ID. - -## Endpoint - -```json -DELETE /_plugins/_ml/memory_containers/{memory_container_id}/memories/{memory_id} -``` - -## Example request - -```json -DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/T9jtmpgBOh0h20Y91WtZ -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "_index": "ml-static-memory-sdjmmpgboh0h20y9kwun-admin", - "_id": "S9jnmpgBOh0h20Y9qWu7", - "_version": 3, - "result": "deleted", - "_shards": { - "total": 2, - "successful": 2, - "failed": 0 - }, - "_seq_no": 3, - "_primary_term": 1 -} -``` \ No newline at end of file diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md index 5940b448af8..0a9b2ea0e4f 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md @@ -23,17 +23,39 @@ GET /_plugins/_ml/memory_containers//memories// | Parameter | Data type | Description | | :--- | :--- | :--- | | `memory_container_id` | String | The ID of the memory container. Required. | -| `type` | String | The type of memory: "session", "working", "long-term", or "history". Required. | +| `type` | String | The type of memory: "sessions", "working", "long-term", or "history". Required. | | `id` | String | The ID of the memory to retrieve. Required. | -## Example request +## Example requests + +### Get working memory ```json GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM ``` + +### Get long-term memory + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz +``` + +### Get session + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/CcxjTpkBvwXRq366A1aE +``` + +### Get memory history + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTpkBvwXRq366hmAU +``` {% include copy-curl.html %} -## Example response +## Example responses + +### Working memory response ```json { @@ -53,6 +75,13 @@ GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJ "user_id": "bob", "session_id": "S-dqiJkB1SltqOcZ1cYO" }, + "metadata": { + "status": "checkpoint", + "branch": { + "branch_name": "high", + "root_event_id": "228nadfs879mtgk" + } + }, "infer": true, "tags": { "topic": "personal info" @@ -62,31 +91,117 @@ GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJ } ``` +### Long-term memory response + +```json +{ + "memory": "Kubernetes RBAC permission issues detected with CloudWatch agents experiencing persistent permission denials", + "strategy_type": "SUMMARY", + "tags": { + "agent_type": "chat_agent", + "conversation": "true" + }, + "namespace": { + "agent_id": "soap-user" + }, + "namespace_size": 1, + "created_time": 1760052801773, + "last_updated_time": 1760052801773, + "memory_embedding": [0.018510794, 0.056366503, "..."], + "owner_id": "admin", + "strategy_id": "summary_96f04d97" +} +``` + +### Session response + +```json +{ + "memory_container_id": "HudqiJkB1SltqOcZusVU", + "namespace": { + "user_id": "bob" + }, + "created_time": "2025-09-15T17:18:55.881276939Z", + "last_updated_time": "2025-09-15T17:18:55.881276939Z" +} +``` + +### History response + +```json +{ + "owner_id": "admin", + "memory_container_id": "nrJBy5kByIxXWyhQjmqv", + "memory_id": "4bJMy5kByIxXWyhQvGr9", + "action": "ADD", + "after": { + "memory": "A comprehensive security investigation was performed across multiple data sources including 55 OpenSearch indices, 50 CloudTrail events, 22 VPC Flow logs, 38 WAF events, 74 CloudWatch log groups, active CloudWatch alarms, and OpenSearch cluster security configuration." + }, + "namespace": { + "agent_id": "soap-user" + }, + "namespace_size": 1, + "tags": { + "agent_type": "chat_agent", + "conversation": "true" + }, + "created_time": 1760052428089 +} +``` + ## Response fields The response fields vary depending on the memory type: ### Working memory response fields +| Field | Data type | Description | +|:----------------------| :--- |:--------------------------------------------------------| +| `memory_container_id` | String | The ID of the memory container. | +| `payload_type` | String | The type of payload: "conversation" or "data". | +| `messages` | Array | Array of conversation messages (for conversation type). | +| `namespace` | Object | The namespace context for this memory. | +| `metadata` | Object | Additional metadata associated with the memory. | +| `tags` | Object | Associated tags for categorization. | +| `infer` | Boolean | Whether inference was enabled for this memory. | +| `created_time` | Long | Timestamp when the memory was created. | +| `last_updated_time` | Long | Timestamp when the memory was last updated. | + +### Long-term memory response fields + | Field | Data type | Description | | :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. | -| `memory_type` | String | The type of memory: "conversation" or "data". | -| `messages` | Array | Array of conversation messages (for conversation type). | -| `structured_data` | Object | Structured data content (for data type). | +| `memory` | String | The extracted long-term memory fact. | +| `strategy_type` | String | The type of memory strategy used (e.g., "SEMANTIC", "SUMMARY", "USER_PREFERENCE"). | | `namespace` | Object | The namespace context for this memory. | +| `namespace_size` | Integer | The size of the namespace. | | `tags` | Object | Associated tags for categorization. | -| `infer` | Boolean | Whether inference was enabled for this memory. | | `created_time` | Long | Timestamp when the memory was created. | | `last_updated_time` | Long | Timestamp when the memory was last updated. | +| `memory_embedding` | Array | Vector embedding of the memory content (truncated in display). | +| `owner_id` | String | The owner of the memory. | +| `strategy_id` | String | The unique identifier for the strategy instance. | -### Long-term memory response fields +### Session response fields | Field | Data type | Description | | :--- | :--- | :--- | -| `memory` | String | The extracted long-term memory fact. | +| `memory_container_id` | String | The ID of the memory container. | +| `namespace` | Object | The namespace context for this session. | +| `created_time` | String | ISO timestamp when the session was created. | +| `last_updated_time` | String | ISO timestamp when the session was last updated. | + +### History response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `owner_id` | String | The owner of the memory. | +| `memory_container_id` | String | The ID of the memory container. | +| `memory_id` | String | The ID of the affected memory. | +| `action` | String | The type of operation: "ADD", "UPDATE", or "DELETE". | +| `after` | Object | The memory content after the operation. | +| `before` | Object | The memory content before the operation (for UPDATE operations). | | `namespace` | Object | The namespace context for this memory. | -| `memory_type` | String | The type of memory strategy used. | +| `namespace_size` | Integer | The size of the namespace. | | `tags` | Object | Associated tags for categorization. | -| `created_time` | Long | Timestamp when the memory was created. | -| `last_updated_time` | Long | Timestamp when the memory was last updated. | +| `created_time` | Long | Timestamp when the operation occurred. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md deleted file mode 100644 index 7030fc4b090..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -layout: default -title: Get agentic memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 60 ---- - -# Get Agentic Memory API -**Introduced 3.2** -{: .label .label-purple } - -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/). -{: .warning} - -Use this API to retrieve an agentic memory by its ID. - -## Endpoint - -```json -GET /_plugins/_ml/memory_containers/{memory_container_id}/memories/{memory_id} -``` - -## Example request - -```json -GET /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/T9jtmpgBOh0h20Y91WtZ -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "session_id": "sess_a99c5a19-cee3-44ce-b64d-6fbdc411c537", - "memory": "Machine learning is a subset of artificial intelligence", - "memory_type": "RAW_MESSAGE", - "user_id": "admin", - "role": "assistant", - "created_time": 1754945934681, - "last_updated_time": 1754945934681 -} -``` - -## Response body fields - -The following table lists all response body fields. - -| Field | Data type | Description | -| :------------------ | :-------- | :--------------------------------------------------------------------------------------- | -| `session_id` | String | The unique identifier for the session associated with this memory. | -| `memory` | String | If the memory was created with `infer: false`, contains the stored text from the message. If the memory was created with `infer: true`, contains the extracted fact from the message. | -| `memory_type` | String | The type of memory. `RAW_MESSAGE` indicates the unprocessed message text. `FACT` indicates a fact inferred by the large language model. | -| `user_id` | String | The ID of the user associated with this memory. | -| `role` | String | The role of the message author. Can be any string, such as `assistant` or `user`. | -| `created_time` | Integer | The Unix timestamp, in milliseconds, when the memory entry was created. | -| `last_updated_time` | Integer | The Unix timestamp, in milliseconds, when the memory entry was last updated. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/index.md b/_ml-commons-plugin/api/agentic-memory-apis/index.md index cd9f8c98d68..bb4ca70a7b9 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/index.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/index.md @@ -41,26 +41,9 @@ OpenSearch supports the following memory container APIs: OpenSearch supports the following memory APIs: -## Working memory APIs - -- [Add working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/add-memory/) -- [Get working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/) -- [Search working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory/) -- [Delete working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory/) - -## Long-term memory APIs - -- [Search long-term memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory/) -- [Update long-term memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory/) -- [Delete long-term memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory/) - -## Memory history APIs - -- [Search memory history]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory-history/) -- [Delete memory history]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory-history/) - -## General memory APIs +## Memory APIs (Unified) +- [Add memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/add-memory/) - [Get memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type/) - [Update memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type/) - [Delete memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type/) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md deleted file mode 100644 index 1942e273039..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -layout: default -title: Search long-term memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 31 ---- - -# Search long-term memory -**Introduced 3.2** -{: .label .label-purple } - -Use this API to search for long-term memories within a memory container. Long-term memories are extracted facts from conversation messages that are stored for semantic retrieval. - -## Path and HTTP methods - -```json -GET /_plugins/_ml/memory_containers//memories/long-term/_search -``` - -## Path parameters - -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | - -## Request fields - -The request body supports standard OpenSearch query DSL. Common fields include: - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `query` | Object | The search query using OpenSearch query DSL. Optional. | -| `sort` | Array | Sort criteria for the results. Optional. | -| `size` | Integer | Maximum number of results to return. Optional. | -| `from` | Integer | Starting index for pagination. Optional. | - -## Example request - -```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/_search -{ - "query": { - "bool": { - "must": [ - { - "term": { - "namespace.user_id": "bob" - } - } - ] - } - }, - "sort": [ - { - "created_time": { - "order": "desc" - } - } - ] -} -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "took": 5, - "timed_out": false, - "_shards": { - "total": 1, - "successful": 1, - "skipped": 0, - "failed": 0 - }, - "hits": { - "total": { - "value": 2, - "relation": "eq" - }, - "max_score": null, - "hits": [ - { - "_index": "test1-long-term-memory", - "_id": "DcxjTpkBvwXRq366C1Zz", - "_score": null, - "_source": { - "created_time": 1757956737699, - "memory": "User's name is Bob", - "last_updated_time": 1757956737699, - "namespace_size": 1, - "namespace": { - "user_id": "bob" - }, - "memory_type": "SEMANTIC", - "tags": { - "topic": "personal info" - } - }, - "sort": [1757956737699] - }, - { - "_index": "test1-long-term-memory", - "_id": "DsxjTpkBvwXRq366C1Zz", - "_score": null, - "_source": { - "created_time": 1757956737699, - "memory": "Bob really likes swimming", - "last_updated_time": 1757956737699, - "namespace_size": 1, - "namespace": { - "user_id": "bob" - }, - "memory_type": "SEMANTIC", - "tags": { - "topic": "personal info" - } - }, - "sort": [1757956737699] - } - ] - } -} -``` - -## Response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `memory` | String | The extracted long-term memory fact. | -| `namespace` | Object | The namespace context for this memory. | -| `memory_type` | String | The type of memory strategy used (e.g., "SEMANTIC"). | -| `tags` | Object | Associated tags for categorization. | -| `created_time` | Long | Timestamp when the memory was created. | -| `last_updated_time` | Long | Timestamp when the memory was last updated. | -| `namespace_size` | Integer | The size of the namespace. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md index 6419abe9859..8818efa8547 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md @@ -23,7 +23,7 @@ GET /_plugins/_ml/memory_containers//memories//_searc | Parameter | Data type | Description | | :--- | :--- | :--- | | `memory_container_id` | String | The ID of the memory container. Required. | -| `type` | String | The type of memory: "session", "working", "long-term", or "history". Required. | +| `type` | String | The type of memory: "sessions", "working", "long-term", or "history". Required. | ## Request fields @@ -38,10 +38,54 @@ The request body supports standard OpenSearch query DSL. Common fields include: ## Example requests -### Search session memories +### Search sessions ```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/session/_search +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/_search +{ + "query": { + "match_all": {} + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` + +### Search long-term memories + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/_search +{ + "query": { + "bool": { + "must": [ + { + "term": { + "namespace.user_id": "bob" + } + } + ] + } + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` + +### Search memory history + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/_search { "query": { "match_all": {} @@ -150,8 +194,6 @@ GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_searc ## Response fields -The response fields vary depending on the memory type being searched. See the individual memory type documentation for specific field descriptions: +The response fields vary depending on the memory type being searched. See the unified memory API documentation for specific field descriptions: -- [Working memory fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/) -- [Long-term memory fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory/) -- [Memory history fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory-history/) +- [Get memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type/) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md deleted file mode 100644 index 987aa2c4fc9..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -layout: default -title: Search memory history -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 41 ---- - -# Search memory history -**Introduced 3.2** -{: .label .label-purple } - -Use this API to search for memory history events within a memory container. Memory history tracks all add, update, and delete operations performed on long-term memories. - -## Path and HTTP methods - -```json -GET /_plugins/_ml/memory_containers//memories/history/_search -``` - -## Path parameters - -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | - -## Request fields - -The request body supports standard OpenSearch query DSL. Common fields include: - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `query` | Object | The search query using OpenSearch query DSL. Optional. | -| `sort` | Array | Sort criteria for the results. Optional. | -| `size` | Integer | Maximum number of results to return. Optional. | -| `from` | Integer | Starting index for pagination. Optional. | - -## Example request - -```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/_search -{ - "query": { - "match_all": {} - }, - "sort": [ - { - "created_time": { - "order": "desc" - } - } - ] -} -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "took": 3, - "timed_out": false, - "_shards": { - "total": 1, - "successful": 1, - "skipped": 0, - "failed": 0 - }, - "hits": { - "total": { - "value": 4, - "relation": "eq" - }, - "max_score": null, - "hits": [ - { - "_index": "test1-long-term-memory-history", - "_id": "eMxnTpkBvwXRq366hmAU", - "_score": null, - "_source": { - "created_time": "2025-09-15T17:23:51.302920078Z", - "memory_id": "DsxjTpkBvwXRq366C1Zz", - "action": "DELETE", - "after": { - "memory": "Bob really likes swimming" - } - }, - "sort": ["2025-09-15T17:23:51.302920078Z"] - }, - { - "_index": "test1-long-term-memory-history", - "_id": "ecxnTpkBvwXRq366hmAU", - "_score": null, - "_source": { - "created_time": "2025-09-15T17:23:51.303097838Z", - "memory_id": null, - "action": "ADD", - "after": { - "memory": "User doesn't like swimming currently" - } - }, - "sort": ["2025-09-15T17:23:51.303097838Z"] - } - ] - } -} -``` - -## Response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `action` | String | The type of operation performed: "ADD", "UPDATE", or "DELETE". | -| `memory_id` | String | The ID of the affected memory (null for ADD operations). | -| `created_time` | String | ISO timestamp when the operation occurred. | -| `after` | Object | The memory content after the operation. | -| `before` | Object | The memory content before the operation (for UPDATE operations). | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md deleted file mode 100644 index bee96e6f0ca..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -layout: default -title: Search agentic memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 70 ---- - -# Search Agentic Memory APIs -**Introduced 3.2** -{: .label .label-purple } - -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/). -{: .warning} - -Use these APIs to to search for an agentic memory in a memory container. These APIs use a query to search for matching memories. - -## Endpoints - -```json -GET /_plugins/_ml/memory_containers/{memory_container_id}/memories/_search -POST /_plugins/_ml/memory_containers/{memory_container_id}/memories/_search -``` - -## Example request - -```json -POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/_search -{ - "query": "machine learning concepts" -} -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "timed_out": false, - "hits": { - "total": 1, - "max_score": 0.69813377, - "hits": [ - { - "memory_id": "T9jtmpgBOh0h20Y91WtZ", - "memory": "Machine learning is a subset of artificial intelligence", - "_score": 0.69813377, - "session_id": "sess_a99c5a19-cee3-44ce-b64d-6fbdc411c537", - "user_id": "admin", - "memory_type": "RAW_MESSAGE", - "role": "assistant", - "created_time": 1754945934681, - "last_updated_time": 1754945934681 - } - ] - } -} -``` \ No newline at end of file diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md deleted file mode 100644 index fbe89790462..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -layout: default -title: Update long-term memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 32 ---- - -# Update long-term memory -**Introduced 3.2** -{: .label .label-purple } - -Use this API to update an existing long-term memory within a memory container. - -## Path and HTTP methods - -```json -PUT /_plugins/_ml/memory_containers//memories/long-term/ -``` - -## Path parameters - -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | -| `memory_id` | String | The ID of the long-term memory to update. Required. | - -## Request fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `memory` | String | The updated memory content. Optional. | -| `tags` | Object | Updated tags for categorization. Optional. | -| `additional_info` | Object | Additional metadata to associate with the memory. Optional. | - -## Example request - -```json -PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz -{ - "memory": "User's name is Bob Smith", - "tags": { - "topic": "personal info", - "updated": "true" - }, - "additional_info": { - "source": "user_correction" - } -} -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "result": "updated", - "_id": "DcxjTpkBvwXRq366C1Zz", - "_version": 2, - "_shards": { - "total": 2, - "successful": 1, - "failed": 0 - } -} -``` - -## Response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `result` | String | The result of the update operation. | -| `_id` | String | The ID of the updated memory. | -| `_version` | Integer | The version number of the updated memory. | -| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md index 14b09047011..5f3f56d9459 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md @@ -23,7 +23,7 @@ PUT /_plugins/_ml/memory_containers//memories// | Parameter | Data type | Description | | :--- | :--- | :--- | | `memory_container_id` | String | The ID of the memory container. Required. | -| `type` | String | The type of memory: "session", "working", or "long-term". Required. | +| `type` | String | The type of memory: "sessions", "working", or "long-term". Required. Note: History memory cannot be updated. | | `id` | String | The ID of the memory to update. Required. | ## Request fields @@ -53,10 +53,12 @@ The request fields vary depending on the memory type being updated: | `tags` | Object | Updated tags for categorization. Optional. | | `additional_info` | Object | Additional metadata. Optional. | -## Example request +## Example requests + +### Update session ```json -PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/session/N2CDipkB2Mtr6INFFcX8 +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/N2CDipkB2Mtr6INFFcX8 { "additional_info": { "key1": "value1", @@ -64,6 +66,31 @@ PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/session/N2CDip } } ``` + +### Update working memory + +```json +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM +{ + "tags": { + "topic": "updated_topic", + "priority": "high" + } +} +``` + +### Update long-term memory + +```json +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz +{ + "memory": "User's name is Bob Smith", + "tags": { + "topic": "personal info", + "updated": "true" + } +} +``` {% include copy-curl.html %} ## Example response diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md deleted file mode 100644 index b6b2bc44ce2..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -layout: default -title: Update agentic memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 50 ---- - -# Update Agentic Memory API -**Introduced 3.2** -{: .label .label-purple } - -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/). -{: .warning} - -Use this API to update an agentic memory. - -## Endpoint - -```json -PUT /_plugins/_ml/memory_containers/{memory_container_id}/memories/{memory_id} -``` - -## Request body fields - -The following table lists the available request body fields. - -Field | Data type | Required/Optional | Description -:--- | :--- | :--- | :--- -`text` | String | Required | The updated `text` content. - -## Example request - -```json -PUT /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/T9jtmpgBOh0h20Y91WtZ -{ - "text": "Updated content with new information about machine learning" -} -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "_index": "ml-static-memory-sdjmmpgboh0h20y9kwun-admin", - "_id": "S9jnmpgBOh0h20Y9qWu7", - "_version": 2, - "result": "updated", - "_shards": { - "total": 2, - "successful": 2, - "failed": 0 - }, - "_seq_no": 2, - "_primary_term": 1 -} -``` \ No newline at end of file From 10fb3ccbf1ba2df75cebf74406cb3c6bad530c3c Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Thu, 9 Oct 2025 20:24:41 -0700 Subject: [PATCH 03/27] Complete agentic memory API documentation with missing container APIs - Add missing update-memory-container.md and search-memory-container.md files - Update create-memory-container.md with advanced features from Postman collection: * Multiple strategy support (SEMANTIC, USER_PREFERENCE, SUMMARY) * Strategy configuration with llm_result_path * Index configuration (index_prefix, use_system_index) * Remove experimental warning (GA in 3.3) - Remove experimental feature reference from index.md - All APIs now match actual implementation from Postman collection Signed-off-by: Dhrubo Saha --- .../create-memory-container.md | 110 +++++++++++++++--- .../api/agentic-memory-apis/index.md | 2 - .../search-memory-container.md | 100 ++++++++++++++++ .../update-memory-container.md | 66 +++++++++++ 4 files changed, 258 insertions(+), 20 deletions(-) create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index 34437cf68cc..6747ee3c084 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -10,9 +10,6 @@ nav_order: 10 **Introduced 3.2** {: .label .label-purple } -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/). -{: .warning} - Use this API to create a memory container to hold agentic memories. The container can have two model types associated with it: - 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. @@ -143,33 +140,110 @@ Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- `name` | String | Required | The name of the memory container. `description` | String | Optional | The description of the memory container. -`memory_storage_config` | Object | Optional | The memory storage configuration. See [the `memory_storage_config` object](#the-memory_storage_config-object). +`configuration` | Object | Required | The memory container configuration. See [the `configuration` object](#the-configuration-object). -### The memory_storage_config object +### The configuration object -The `memory_storage_config` object supports the following fields. +The `configuration` object supports the following fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`dimension` | Integer | Optional | The dimension of the embedding model. Required if `embedding_model_type` is `TEXT_EMBEDDING`. -`embedding_model_id` | String | Optional | The embedding model ID. `embedding_model_type` | String | Optional | The embedding model type. Supported types are `TEXT_EMBEDDING` and `SPARSE_ENCODING`. -`llm_model_id` | String | Optional | The LLM ID. -`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. -`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. +`embedding_model_id` | String | Optional | The embedding model ID. +`embedding_dimension` | Integer | Optional | The dimension of the embedding model. Required if `embedding_model_type` is `TEXT_EMBEDDING`. +`llm_id` | String | Optional | The LLM model ID for processing and inference. +`index_prefix` | String | Optional | Custom prefix for the memory indices. If not specified, a default prefix is used. +`use_system_index` | Boolean | Optional | Whether to use system indices. Default is `true`. +`strategies` | Array | Optional | Array of memory processing strategies. See [the `strategies` array](#the-strategies-array). +`parameters` | Object | Optional | Global parameters for the memory container. See [the `parameters` object](#the-parameters-object). + +### The strategies array + +Each strategy in the `strategies` array supports the following fields. + +Field | Data type | Required/Optional | Description +:--- | :--- | :--- | :--- +`type` | String | Required | The strategy type: `SEMANTIC`, `USER_PREFERENCE`, or `SUMMARY`. +`namespace` | Array | Required | Array of namespace dimensions for organizing memories (e.g., `["user_id"]`, `["agent_id"]`). +`configuration` | Object | Optional | Strategy-specific configuration. See [the strategy `configuration` object](#the-strategy-configuration-object). + +### The strategy configuration object + +Field | Data type | Required/Optional | Description +:--- | :--- | :--- | :--- +`llm_result_path` | String | Optional | JSONPath to extract LLM results (e.g., `"$.output.message.content[0].text"`). + +### The parameters object + +Field | Data type | Required/Optional | Description +:--- | :--- | :--- | :--- +`llm_result_path` | String | Optional | Global JSONPath for extracting LLM results from responses. + +## Example requests + +### Basic memory container + +```json +POST /_plugins/_ml/memory_containers/_create +{ + "name": "agentic memory test", + "description": "Store conversations with semantic search and summarization", + "configuration": { + "embedding_model_type": "TEXT_EMBEDDING", + "embedding_model_id": "{{embedding_model_id}}", + "embedding_dimension": 1024, + "llm_id": "{{llm_id}}", + "strategies": [ + { + "type": "SEMANTIC", + "namespace": ["user_id"] + } + ] + } +} +``` -## Example request +### Advanced memory container with multiple strategies ```json POST /_plugins/_ml/memory_containers/_create { - "name": "Sparse memory container", - "description": "Store sparse conversations with semantic search", - "memory_storage_config": { - "llm_model_id": "bbphdJgB9L0Qb_M6ipnn", - "embedding_model_type": "SPARSE_ENCODING", - "embedding_model_id": "RodoX5gBfObQ5OgTHf1X" + "name": "agentic memory test", + "description": "Store conversations with semantic search and summarization", + "configuration": { + "embedding_model_type": "TEXT_EMBEDDING", + "embedding_model_id": "{{embedding_model_id}}", + "embedding_dimension": 1024, + "llm_id": "{{llm_id}}", + "index_prefix": "my_custom_prefix", + "use_system_index": false, + "strategies": [ + { + "type": "SEMANTIC", + "namespace": ["agent_id"], + "configuration": { + "llm_result_path": "$.output.message.content[0].text" + } + }, + { + "type": "USER_PREFERENCE", + "namespace": ["agent_id"], + "configuration": { + "llm_result_path": "$.output.message.content[0].text" + } + }, + { + "type": "SUMMARY", + "namespace": ["agent_id"], + "configuration": { + "llm_result_path": "$.output.message.content[0].text" + } + } + ], + "parameters": { + "llm_result_path": "$.output.message.content[0].text" } + } } ``` {% include copy-curl.html %} diff --git a/_ml-commons-plugin/api/agentic-memory-apis/index.md b/_ml-commons-plugin/api/agentic-memory-apis/index.md index bb4ca70a7b9..9695a62a7d8 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/index.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/index.md @@ -29,8 +29,6 @@ PUT /_cluster/settings ``` {% include copy-curl.html %} -For more information and other ways to enable experimental features, see [Experimental feature flags]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/experimental/). - OpenSearch supports the following memory container APIs: - [Create memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container/) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md new file mode 100644 index 00000000000..98eee0bb1b6 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md @@ -0,0 +1,100 @@ +--- +layout: default +title: Search memory containers +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 25 +--- + +# Search memory containers +**Introduced 3.2** +{: .label .label-purple } + +Use this API to search for memory containers using OpenSearch query DSL. + +## Path and HTTP methods + +```json +GET /_plugins/_ml/memory_containers/_search +POST /_plugins/_ml/memory_containers/_search +``` + +## Request fields + +The request body supports standard OpenSearch query DSL. Common fields include: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `query` | Object | The search query using OpenSearch query DSL. Optional. | +| `sort` | Array | Sort criteria for the results. Optional. | +| `size` | Integer | Maximum number of results to return. Optional. | +| `from` | Integer | Starting index for pagination. Optional. | + +## Example request + +```json +GET /_plugins/_ml/memory_containers/_search +{ + "query": { + "match_all": {} + } +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "took": 5, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 2, + "relation": "eq" + }, + "max_score": 1.0, + "hits": [ + { + "_index": ".plugins-ml-memory-meta", + "_id": "HudqiJkB1SltqOcZusVU", + "_score": 1.0, + "_source": { + "name": "agentic memory test", + "description": "Store conversations with semantic search and summarization", + "configuration": { + "embedding_model_type": "TEXT_EMBEDDING", + "embedding_model_id": "uXZAtJkBvHNmcp1JAROh", + "embedding_dimension": 1024, + "llm_id": "aFouy5kBrfmzAZ6R6wo-", + "strategies": [ + { + "type": "SEMANTIC", + "namespace": ["user_id"] + } + ] + }, + "created_time": 1757956737699, + "last_updated_time": 1757956737699 + } + } + ] + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `name` | String | The name of the memory container. | +| `description` | String | The description of the memory container. | +| `configuration` | Object | The memory container configuration including models and strategies. | +| `created_time` | Long | Timestamp when the container was created. | +| `last_updated_time` | Long | Timestamp when the container was last updated. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md new file mode 100644 index 00000000000..af4ea79820d --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md @@ -0,0 +1,66 @@ +--- +layout: default +title: Update memory container +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 15 +--- + +# Update memory container +**Introduced 3.2** +{: .label .label-purple } + +Use this API to update an existing memory container's properties such as name and description. + +## Path and HTTP methods + +```json +PUT /_plugins/_ml/memory_containers/ +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container to update. Required. | + +## Request fields + +| Field | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `name` | String | Optional | The updated name of the memory container. | +| `description` | String | Optional | The updated description of the memory container. | + +## Example request + +```json +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU +{ + "name": "opensearch-agents-memory" +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "result": "updated", + "_id": "HudqiJkB1SltqOcZusVU", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the update operation. | +| `_id` | String | The ID of the updated memory container. | +| `_version` | Integer | The version number of the updated memory container. | +| `_shards` | Object | Information about the shards involved in the operation. | From 5ec087052aeef888da8a34e8e2fd0cfa28b479fd Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Thu, 9 Oct 2025 20:34:13 -0700 Subject: [PATCH 04/27] Document default llm_result_path and LLM connector requirements - Add default llm_result_path value: $.output.message.content[0].text (Bedrock Converse format) - Document LLM connector requirement for system_prompt and user_prompt parameters - Reference ml-commons PR #4283 for standardized connector format - Clarify that default is optimized for Bedrock Converse API Signed-off-by: Dhrubo Saha --- .../api/agentic-memory-apis/create-memory-container.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index 6747ee3c084..f909c4c4d87 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -15,6 +15,8 @@ Use this API to create a memory container to hold agentic memories. The containe - 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. - 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. +**Note**: LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is configured for Bedrock Converse API format (`"$.output.message.content[0].text"`). + Once a memory container is created, you'll provide its `memory_container_id` to other APIs. ## Prerequisites @@ -171,13 +173,13 @@ Field | Data type | Required/Optional | Description Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`llm_result_path` | String | Optional | JSONPath to extract LLM results (e.g., `"$.output.message.content[0].text"`). +`llm_result_path` | String | Optional | JSONPath to extract LLM results. Default is `"$.output.message.content[0].text"` for Bedrock Converse API format. ### The parameters object Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`llm_result_path` | String | Optional | Global JSONPath for extracting LLM results from responses. +`llm_result_path` | String | Optional | Global JSONPath for extracting LLM results from responses. Default is `"$.output.message.content[0].text"` for Bedrock Converse API format. ## Example requests From eb75f4e3b7812e3285a2ceec8a573a412283f393 Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Fri, 10 Oct 2025 10:38:12 -0700 Subject: [PATCH 05/27] Address ylwu-amzn review comments - Update add-memory.md terminology: memory_type -> payload_type, conversational/data types - Add Required/Optional column format to parameter tables - Update version labels from 3.2 to 3.3 for new unified APIs - Add binary_data and tags fields with correct data types - Fix metadata field representation as string in response examples - Add detailed explanations for namespace session creation behavior - Update create-memory-container.md with system_prompt and llm_id strategy fields - Add detailed index_prefix default behavior explanation - Show multiple namespace field examples in strategy configuration Signed-off-by: Dhrubo Saha --- .../api/agentic-memory-apis/add-memory.md | 43 ++++++++++--------- .../create-memory-container.md | 12 ++++-- .../delete-memory-by-type.md | 12 +++--- .../agentic-memory-apis/get-memory-by-type.md | 7 +-- 4 files changed, 38 insertions(+), 36 deletions(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 1798a2896d5..4fdd8d9e185 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -11,17 +11,15 @@ nav_order: 40 {: .label .label-purple } -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: +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 provide memory payload in two types: -- **Conversation memory** -- Stores conversational messages between users and assistants. Can be processed (when `infer` is `true`) to extract facts or stored as raw messages. +- **conversational** -- Stores conversational messages between users and assistants. -- **Data memory** -- Stores structured, non-conversational data such as agent state, checkpoints, or reference information. +- **data** -- Stores extra messages, structured, non-conversational data such as agent state, checkpoints, or reference information. -Memory processing modes (controlled by the `infer` parameter): +- **infer=true** -- Use large language model (LLM) to extract key information or knowledge from the messages. -- 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. - -- Raw message memory -- The unprocessed message content. +- **infer=false** -- Only store raw messages and data in working memory. Once an agentic memory is created, you'll provide its `memory_id` to other APIs. @@ -37,19 +35,18 @@ The following table lists the available request body fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`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`. -`structured_data` | Object | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. -`memory_type` | String | Required | The type of memory: `conversation` or `data`. -`namespace` | Object | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). -`metadata` | Object | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). -`session_id` | String | Optional | The session ID associated with the memory. Deprecated in favor of using `namespace.session_id`. -`agent_id` | String | Optional | The agent ID associated with the memory. Deprecated in favor of using `namespace.agent_id`. -`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. -`tags` | Object | Optional | Custom metadata for the agentic memory. +`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`. +`structured_data` | Map | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. +`binary_data` | String | Optional | Binary data content encoded as base64 string for binary payloads. +`payload_type` | String | Required | The type of payload: `conversational` or `data`. +`namespace` | List | 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. +`metadata` | Map | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). +`tags` | List | Optional | Tags for categorizing and organizing memories. +`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. ## Example requests -### Conversation memory +### Conversational payload ```json POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories @@ -78,11 +75,13 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "topic": "personal info" }, "infer": true, - "memory_type": "conversation" + "payload_type": "conversational" } ``` -### Data memory +### Data payload + +Store agent state in working memory: ```json POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories @@ -104,12 +103,14 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "topic": "agent_state" }, "infer": false, - "memory_type": "data" + "payload_type": "data" } ``` ### Trace data memory +Store agent trace data in working memory: + ```json POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories { @@ -143,7 +144,7 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "data_type": "trace" }, "infer": false, - "memory_type": "conversation" + "payload_type": "conversational" } ``` {% include copy-curl.html %} diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index f909c4c4d87..ce919dd90df 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -154,7 +154,7 @@ Field | Data type | Required/Optional | Description `embedding_model_id` | String | Optional | The embedding model ID. `embedding_dimension` | Integer | Optional | The dimension of the embedding model. Required if `embedding_model_type` is `TEXT_EMBEDDING`. `llm_id` | String | Optional | The LLM model ID for processing and inference. -`index_prefix` | String | Optional | Custom prefix for the memory indices. If not specified, a default prefix is used. +`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. `use_system_index` | Boolean | Optional | Whether to use system indices. Default is `true`. `strategies` | Array | Optional | Array of memory processing strategies. See [the `strategies` array](#the-strategies-array). `parameters` | Object | Optional | Global parameters for the memory container. See [the `parameters` object](#the-parameters-object). @@ -166,14 +166,16 @@ Each strategy in the `strategies` array supports the following fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- `type` | String | Required | The strategy type: `SEMANTIC`, `USER_PREFERENCE`, or `SUMMARY`. -`namespace` | Array | Required | Array of namespace dimensions for organizing memories (e.g., `["user_id"]`, `["agent_id"]`). -`configuration` | Object | Optional | Strategy-specific configuration. See [the strategy `configuration` object](#the-strategy-configuration-object). +`namespace` | Array | Required | Array of namespace dimensions for organizing memories (e.g., `["user_id"]`, `["agent_id", "session_id"]`). +`configuration` | Map | Optional | Strategy-specific configuration. See [the strategy `configuration` object](#the-strategy-configuration-object). ### The strategy configuration object Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- `llm_result_path` | String | Optional | JSONPath to extract LLM results. Default is `"$.output.message.content[0].text"` for Bedrock Converse API format. +`system_prompt` | String | Optional | Custom system prompt to override the default strategy prompt. +`llm_id` | String | Optional | LLM model ID for this specific strategy, overrides the global LLM setting. ### The parameters object @@ -224,7 +226,9 @@ POST /_plugins/_ml/memory_containers/_create "type": "SEMANTIC", "namespace": ["agent_id"], "configuration": { - "llm_result_path": "$.output.message.content[0].text" + "llm_result_path": "$.output.message.content[0].text", + "system_prompt": "Extract semantic information from user conversations", + "llm_id": "{{custom_llm_id}}" } }, { diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md index 08fe2adc097..8fa06b9e6c7 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md @@ -7,7 +7,7 @@ nav_order: 53 --- # Delete memory by type and ID -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } Use this API to delete a specific memory by its type and ID. This unified API supports deleting all memory types: session, working, long-term, and history memory data. @@ -20,11 +20,11 @@ DELETE /_plugins/_ml/memory_containers//memories// Date: Fri, 10 Oct 2025 10:56:10 -0700 Subject: [PATCH 06/27] Add agentic memory cluster setting - Add plugins.ml_commons.agentic_memory_enabled setting to cluster-settings.md - Enables/disables agentic memory functionality for AI agents - Includes session, working, long-term memory, and memory history features Signed-off-by: Dhrubo Saha --- .../agentic-memory-apis/get-memory-by-type.md | 4 +- .../search-memories-by-type.md | 11 +---- .../search-memory-container.md | 11 +---- .../update-memory-by-type.md | 2 +- .../update-memory-container.md | 2 +- _ml-commons-plugin/cluster-settings.md | 45 +++++++++++++++++++ 6 files changed, 53 insertions(+), 22 deletions(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md index 1e598ccde5e..df474bc54d7 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md @@ -99,7 +99,7 @@ GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTp "conversation": "true" }, "namespace": { - "agent_id": "soap-user" + "agent_id": "chat-agent" }, "namespace_size": 1, "created_time": 1760052801773, @@ -135,7 +135,7 @@ GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTp "memory": "A comprehensive security investigation was performed across multiple data sources including 55 OpenSearch indices, 50 CloudTrail events, 22 VPC Flow logs, 38 WAF events, 74 CloudWatch log groups, active CloudWatch alarms, and OpenSearch cluster security configuration." }, "namespace": { - "agent_id": "soap-user" + "agent_id": "chat-agent" }, "namespace_size": 1, "tags": { diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md index 8818efa8547..84704d31cff 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md @@ -7,7 +7,7 @@ nav_order: 54 --- # Search memories by type -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } Use this API to search for memories of a specific type within a memory container. This unified API supports searching session, working, long-term, and history memory data. @@ -27,14 +27,7 @@ GET /_plugins/_ml/memory_containers//memories//_searc ## Request fields -The request body supports standard OpenSearch query DSL. Common fields include: - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `query` | Object | The search query using OpenSearch query DSL. Optional. | -| `sort` | Array | Sort criteria for the results. Optional. | -| `size` | Integer | Maximum number of results to return. Optional. | -| `from` | Integer | Starting index for pagination. Optional. | +The request body supports standard OpenSearch query DSL. ## Example requests diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md index 98eee0bb1b6..092808264fe 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md @@ -7,7 +7,7 @@ nav_order: 25 --- # Search memory containers -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } Use this API to search for memory containers using OpenSearch query DSL. @@ -21,14 +21,7 @@ POST /_plugins/_ml/memory_containers/_search ## Request fields -The request body supports standard OpenSearch query DSL. Common fields include: - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `query` | Object | The search query using OpenSearch query DSL. Optional. | -| `sort` | Array | Sort criteria for the results. Optional. | -| `size` | Integer | Maximum number of results to return. Optional. | -| `from` | Integer | Starting index for pagination. Optional. | +The request body supports standard OpenSearch query DSL. ## Example request diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md index 5f3f56d9459..10f182ff846 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md @@ -7,7 +7,7 @@ nav_order: 52 --- # Update memory by type and ID -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } Use this API to update a specific memory by its type and ID. This unified API supports updating session, working, and long-term memory data. History memory does not support updates. diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md index af4ea79820d..5b4fa548f95 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md @@ -7,7 +7,7 @@ nav_order: 15 --- # Update memory container -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } Use this API to update an existing memory container's properties such as name and description. diff --git a/_ml-commons-plugin/cluster-settings.md b/_ml-commons-plugin/cluster-settings.md index 2cab887487a..16d9df1b6db 100644 --- a/_ml-commons-plugin/cluster-settings.md +++ b/_ml-commons-plugin/cluster-settings.md @@ -494,6 +494,51 @@ plugins.ml_commons.memory_feature_enabled: true - Default value: `true` - Valid values: `false`, `true` +## Enable agentic memory + +When set to `true`, this setting enables agentic memory functionality, which provides advanced memory management for AI agents including session memory, working memory, long-term memory, and memory history with namespace-based organization. + +### Setting + +```yaml +plugins.ml_commons.agentic_memory_enabled: true +``` + +### Values + +- Default value: `true` +- Valid values: `false`, `true` + +## Set maximum memory containers per user + +Controls the maximum number of memory containers that can be created per user. When set to `0`, no memory containers can be created. + +### Setting + +```yaml +plugins.ml_commons.max_memory_containers_per_user: 100 +``` + +### Values + +- Default value: `100` +- Value range: [0, 10,000] + +## Set maximum memories per container + +Controls the maximum number of memories that can be stored in a single memory container. When set to `0`, no memories can be added to any container. + +### Setting + +```yaml +plugins.ml_commons.max_memories_per_container: 10000 +``` + +### Values + +- Default value: `10,000` +- Value range: [0, 1,000,000] + ## Enable RAG pipeline From 7c976f2081af129eaa382d431988ba00bf4aae02 Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Fri, 10 Oct 2025 11:07:42 -0700 Subject: [PATCH 07/27] update path parameters Signed-off-by: Dhrubo Saha --- .../api/agentic-memory-apis/delete-memory-by-type.md | 8 ++++---- .../api/agentic-memory-apis/search-memories-by-type.md | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md index 8fa06b9e6c7..82c1585652e 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md @@ -20,11 +20,11 @@ DELETE /_plugins/_ml/memory_containers//memories///memories//_searc ## Path parameters -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | -| `type` | String | The type of memory: "sessions", "working", "long-term", or "history". Required. | +| Field | Data type | Required/Optional | Description | +|:----------------------| :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container. | +| `type` | String | Required | The type of memory: "sessions", "working", "long-term", or "history". | ## Request fields From 742830738f1cb2d63dcd02b671e414425a0eee4f Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Wed, 1 Oct 2025 16:32:07 -0700 Subject: [PATCH 08/27] 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 Signed-off-by: Dhrubo Saha --- .../api/agentic-memory-apis/add-memory.md | 131 +++++++++++---- .../delete-long-term-memory.md | 57 +++++++ .../delete-memory-by-type.md | 58 +++++++ .../delete-memory-history.md | 57 +++++++ .../agentic-memory-apis/get-memory-by-type.md | 92 ++++++++++ .../api/agentic-memory-apis/index.md | 40 +++-- .../search-long-term-memory.md | 137 +++++++++++++++ .../search-memories-by-type.md | 157 ++++++++++++++++++ .../search-memory-history.md | 117 +++++++++++++ .../update-long-term-memory.md | 75 +++++++++ .../update-memory-by-type.md | 91 ++++++++++ 11 files changed, 972 insertions(+), 40 deletions(-) create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/delete-memory-history.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 1e298dc4f18..76a9187ac8a 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -10,10 +10,14 @@ nav_order: 40 **Introduced 3.2** {: .label .label-purple } -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/). -{: .warning} -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): +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: + +- **Conversation memory** -- Stores conversational messages between users and assistants. Can be processed (when `infer` is `true`) to extract facts or stored as raw messages. + +- **Data memory** -- Stores structured, non-conversational data such as agent state, checkpoints, or reference information. + +Memory processing modes (controlled by the `infer` parameter): - 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. @@ -33,41 +37,113 @@ The following table lists the available request body fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`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`. -`session_id` | String | Optional | The session ID associated with the memory. -`agent_id` | String | Optional | The agent ID associated with the memory. -`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. +`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`. +`structured_data` | Object | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. +`memory_type` | String | Required | The type of memory: `conversation` or `data`. +`namespace` | Object | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). +`session_id` | String | Optional | The session ID associated with the memory. Deprecated in favor of using `namespace.session_id`. +`agent_id` | String | Optional | The agent ID associated with the memory. Deprecated in favor of using `namespace.agent_id`. +`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. `tags` | Object | Optional | Custom metadata for the agentic memory. -## Example request +## Example requests + +### Conversation memory ```json POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories { - "messages": [ - {"role": "user", "content": "Machine learning is a subset of artificial intelligence"} - ], - "session_id": "sess_789", - "agent_id": "agent_123", - "tags": { - "topic": "personal info" + "messages": [ + { + "role": "user", + "content": "I'm Bob, I really like swimming." + }, + { + "role": "assistant", + "content": "Cool, nice. Hope you enjoy your life." } + ], + "namespace": { + "user_id": "bob" + }, + "tags": { + "topic": "personal info" + }, + "infer": true, + "memory_type": "conversation" +} +``` + +### Data memory + +```json +POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories +{ + "structured_data": { + "time_range": { + "start": "2025-09-11", + "end": "2025-09-15" + } + }, + "namespace": { + "agent_id": "testAgent1" + }, + "tags": { + "topic": "agent_state" + }, + "infer": false, + "memory_type": "data" +} +``` + +### Trace data memory + +```json +POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories +{ + "structured_data": { + "tool_invocations": [ + { + "tool_name": "ListIndexTool", + "tool_input": { + "filter": "*,-.plugins*" + }, + "tool_output": "green open security-auditlog-2025.09.17..." + } + ] + }, + "namespace": { + "user_id": "bob", + "agent_id": "testAgent1", + "session_id": "123" + }, + "tags": { + "topic": "personal info", + "parent_memory_id": "o4-WWJkBFT7urc7Ed9hM", + "data_type": "trace" + }, + "infer": false, + "memory_type": "conversation" } ``` {% include copy-curl.html %} -## Example response +## Example responses + +### Conversation memory response + +```json +{ + "session_id": "XSEuiJkBeh2gPPwzjYVh", + "working_memory_id": "XyEuiJkBeh2gPPwzjYWM" +} +``` + +### Data memory response ```json { - "results": [ - { - "id": "T9jtmpgBOh0h20Y91WtZ", - "text": "Machine learning is a subset of artificial intelligence", - "event": "ADD" - } - ], - "session_id": "sess_789" + "working_memory_id": "Z8xeTpkBvwXRq366l0iA" } ``` @@ -77,8 +153,5 @@ The following table lists all response body fields. | Field | Data type | Description | | :-------------- | :-------- | :------------------------------------------------------------------------------------------------ | -| `results` | List | A list of memory entries returned by the request. | -| `results.id` | String | The unique identifier for the memory entry. | -| `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. | -| `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. | -| `session_id` | String | The session ID associated with the memory. | +| `session_id` | String | The session ID associated with the memory (returned for conversation memory when a session is created or used). | +| `working_memory_id` | String | The unique identifier for the created working memory entry. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md new file mode 100644 index 00000000000..c5c0f653ec6 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md @@ -0,0 +1,57 @@ +--- +layout: default +title: Delete long-term memory +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 33 +--- + +# Delete long-term memory +**Introduced 3.2** +{: .label .label-purple } + +Use this API to delete a specific long-term memory from a memory container. + +## Path and HTTP methods + +```json +DELETE /_plugins/_ml/memory_containers//memories/long-term/ +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `memory_id` | String | The ID of the long-term memory to delete. Required. | + +## Example request + +```json +DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "result": "deleted", + "_id": "DcxjTpkBvwXRq366C1Zz", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the delete operation. | +| `_id` | String | The ID of the deleted memory. | +| `_version` | Integer | The version number after deletion. | +| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md new file mode 100644 index 00000000000..0861d95b90c --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md @@ -0,0 +1,58 @@ +--- +layout: default +title: Delete memory by type and ID +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 53 +--- + +# Delete memory by type and ID +**Introduced 3.2** +{: .label .label-purple } + +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. + +## Path and HTTP methods + +```json +DELETE /_plugins/_ml/memory_containers//memories// +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `type` | String | The type of memory: "session", "working", "long-term", or "history". Required. | +| `id` | String | The ID of the memory to delete. Required. | + +## Example request + +```json +DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "result": "deleted", + "_id": "XyEuiJkBeh2gPPwzjYWM", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the delete operation. | +| `_id` | String | The ID of the deleted memory. | +| `_version` | Integer | The version number after deletion. | +| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-history.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-history.md new file mode 100644 index 00000000000..e912b4df488 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-history.md @@ -0,0 +1,57 @@ +--- +layout: default +title: Delete memory history +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 42 +--- + +# Delete memory history +**Introduced 3.2** +{: .label .label-purple } + +Use this API to delete specific memory history events from a memory container. + +## Path and HTTP methods + +```json +DELETE /_plugins/_ml/memory_containers//memories/history/ +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `history_id` | String | The ID of the history event to delete. Required. | + +## Example request + +```json +DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTpkBvwXRq366hmAU +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "result": "deleted", + "_id": "eMxnTpkBvwXRq366hmAU", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the delete operation. | +| `_id` | String | The ID of the deleted history event. | +| `_version` | Integer | The version number after deletion. | +| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md new file mode 100644 index 00000000000..5940b448af8 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md @@ -0,0 +1,92 @@ +--- +layout: default +title: Get memory by type and ID +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 51 +--- + +# Get memory by type and ID +**Introduced 3.2** +{: .label .label-purple } + +Use this API to retrieve a specific memory by its type and ID. This unified API supports four types of memory data: session, working, long-term, and history. + +## Path and HTTP methods + +```json +GET /_plugins/_ml/memory_containers//memories// +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `type` | String | The type of memory: "session", "working", "long-term", or "history". Required. | +| `id` | String | The ID of the memory to retrieve. Required. | + +## Example request + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "memory_container_id": "HudqiJkB1SltqOcZusVU", + "memory_type": "conversation", + "messages": [ + { + "role": "user", + "content_text": "I'm Bob, I really like swimming." + }, + { + "role": "assistant", + "content_text": "Cool, nice. Hope you enjoy your life." + } + ], + "namespace": { + "user_id": "bob", + "session_id": "S-dqiJkB1SltqOcZ1cYO" + }, + "infer": true, + "tags": { + "topic": "personal info" + }, + "created_time": 1758930326804, + "last_updated_time": 1758930326804 +} +``` + +## Response fields + +The response fields vary depending on the memory type: + +### Working memory response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. | +| `memory_type` | String | The type of memory: "conversation" or "data". | +| `messages` | Array | Array of conversation messages (for conversation type). | +| `structured_data` | Object | Structured data content (for data type). | +| `namespace` | Object | The namespace context for this memory. | +| `tags` | Object | Associated tags for categorization. | +| `infer` | Boolean | Whether inference was enabled for this memory. | +| `created_time` | Long | Timestamp when the memory was created. | +| `last_updated_time` | Long | Timestamp when the memory was last updated. | + +### Long-term memory response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `memory` | String | The extracted long-term memory fact. | +| `namespace` | Object | The namespace context for this memory. | +| `memory_type` | String | The type of memory strategy used. | +| `tags` | Object | Associated tags for categorization. | +| `created_time` | Long | Timestamp when the memory was created. | +| `last_updated_time` | Long | Timestamp when the memory was last updated. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/index.md b/_ml-commons-plugin/api/agentic-memory-apis/index.md index ff5a7f73a62..cd9f8c98d68 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/index.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/index.md @@ -13,20 +13,17 @@ redirect_from: **Introduced 3.2** {: .label .label-purple } -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/). -{: .warning} - Agentic Memory APIs provide persistent memory management for AI agents. This enables agents to learn, remember, and reason over structured information across conversations. -## Enabling Agentic Memory APIs +## Disabling Agentic Memory APIs -To enable Agentic Memory APIs, update the following cluster setting: +As Agentinc memory is GA in 3.3, this feature is enabled by default. To disable Agentic Memory APIs, update the following cluster setting: ```json PUT /_cluster/settings { "persistent": { - "plugins.ml_commons.agentic_memory_enabled": true + "plugins.ml_commons.agentic_memory_enabled": false } } ``` @@ -38,12 +35,33 @@ OpenSearch supports the following memory container APIs: - [Create memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container/) - [Get memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory-container/) +- [Update memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory-container/) - [Delete memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory-container/) +- [Search memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory-container/) OpenSearch supports the following memory APIs: -- [Add memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/add-memory/) -- [Get memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/) -- [Search memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory/) -- [Update memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory/) -- [Delete memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory/) \ No newline at end of file +## Working memory APIs + +- [Add working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/add-memory/) +- [Get working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/) +- [Search working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory/) +- [Delete working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory/) + +## Long-term memory APIs + +- [Search long-term memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory/) +- [Update long-term memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory/) +- [Delete long-term memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory/) + +## Memory history APIs + +- [Search memory history]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory-history/) +- [Delete memory history]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory-history/) + +## General memory APIs + +- [Get memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type/) +- [Update memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type/) +- [Delete memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type/) +- [Search memories by type]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type/) \ No newline at end of file diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md new file mode 100644 index 00000000000..1942e273039 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md @@ -0,0 +1,137 @@ +--- +layout: default +title: Search long-term memory +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 31 +--- + +# Search long-term memory +**Introduced 3.2** +{: .label .label-purple } + +Use this API to search for long-term memories within a memory container. Long-term memories are extracted facts from conversation messages that are stored for semantic retrieval. + +## Path and HTTP methods + +```json +GET /_plugins/_ml/memory_containers//memories/long-term/_search +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | + +## Request fields + +The request body supports standard OpenSearch query DSL. Common fields include: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `query` | Object | The search query using OpenSearch query DSL. Optional. | +| `sort` | Array | Sort criteria for the results. Optional. | +| `size` | Integer | Maximum number of results to return. Optional. | +| `from` | Integer | Starting index for pagination. Optional. | + +## Example request + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/_search +{ + "query": { + "bool": { + "must": [ + { + "term": { + "namespace.user_id": "bob" + } + } + ] + } + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "took": 5, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 2, + "relation": "eq" + }, + "max_score": null, + "hits": [ + { + "_index": "test1-long-term-memory", + "_id": "DcxjTpkBvwXRq366C1Zz", + "_score": null, + "_source": { + "created_time": 1757956737699, + "memory": "User's name is Bob", + "last_updated_time": 1757956737699, + "namespace_size": 1, + "namespace": { + "user_id": "bob" + }, + "memory_type": "SEMANTIC", + "tags": { + "topic": "personal info" + } + }, + "sort": [1757956737699] + }, + { + "_index": "test1-long-term-memory", + "_id": "DsxjTpkBvwXRq366C1Zz", + "_score": null, + "_source": { + "created_time": 1757956737699, + "memory": "Bob really likes swimming", + "last_updated_time": 1757956737699, + "namespace_size": 1, + "namespace": { + "user_id": "bob" + }, + "memory_type": "SEMANTIC", + "tags": { + "topic": "personal info" + } + }, + "sort": [1757956737699] + } + ] + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `memory` | String | The extracted long-term memory fact. | +| `namespace` | Object | The namespace context for this memory. | +| `memory_type` | String | The type of memory strategy used (e.g., "SEMANTIC"). | +| `tags` | Object | Associated tags for categorization. | +| `created_time` | Long | Timestamp when the memory was created. | +| `last_updated_time` | Long | Timestamp when the memory was last updated. | +| `namespace_size` | Integer | The size of the namespace. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md new file mode 100644 index 00000000000..6419abe9859 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md @@ -0,0 +1,157 @@ +--- +layout: default +title: Search memories by type +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 54 +--- + +# Search memories by type +**Introduced 3.2** +{: .label .label-purple } + +Use this API to search for memories of a specific type within a memory container. This unified API supports searching session, working, long-term, and history memory data. + +## Path and HTTP methods + +```json +GET /_plugins/_ml/memory_containers//memories//_search +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `type` | String | The type of memory: "session", "working", "long-term", or "history". Required. | + +## Request fields + +The request body supports standard OpenSearch query DSL. Common fields include: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `query` | Object | The search query using OpenSearch query DSL. Optional. | +| `sort` | Array | Sort criteria for the results. Optional. | +| `size` | Integer | Maximum number of results to return. Optional. | +| `from` | Integer | Starting index for pagination. Optional. | + +## Example requests + +### Search session memories + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/session/_search +{ + "query": { + "match_all": {} + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` + +### Search working memories with namespace filter + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_search +{ + "query": { + "bool": { + "must": [ + { + "term": { + "namespace.user_id": "bob" + } + } + ], + "must_not": [ + { + "exists": { + "field": "tags.parent_memory_id" + } + } + ] + } + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` + +### Search trace data by session + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_search +{ + "query": { + "term": { + "namespace.session_id": "123" + } + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "took": 5, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 1, + "relation": "eq" + }, + "max_score": null, + "hits": [ + { + "_index": "test1-session", + "_id": "CcxjTpkBvwXRq366A1aE", + "_score": null, + "_source": { + "memory_container_id": "HudqiJkB1SltqOcZusVU", + "namespace": { + "user_id": "bob" + }, + "created_time": "2025-09-15T17:18:55.881276939Z", + "last_updated_time": "2025-09-15T17:18:55.881276939Z" + }, + "sort": ["2025-09-15T17:18:55.881276939Z"] + } + ] + } +} +``` + +## Response fields + +The response fields vary depending on the memory type being searched. See the individual memory type documentation for specific field descriptions: + +- [Working memory fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/) +- [Long-term memory fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory/) +- [Memory history fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory-history/) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md new file mode 100644 index 00000000000..987aa2c4fc9 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md @@ -0,0 +1,117 @@ +--- +layout: default +title: Search memory history +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 41 +--- + +# Search memory history +**Introduced 3.2** +{: .label .label-purple } + +Use this API to search for memory history events within a memory container. Memory history tracks all add, update, and delete operations performed on long-term memories. + +## Path and HTTP methods + +```json +GET /_plugins/_ml/memory_containers//memories/history/_search +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | + +## Request fields + +The request body supports standard OpenSearch query DSL. Common fields include: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `query` | Object | The search query using OpenSearch query DSL. Optional. | +| `sort` | Array | Sort criteria for the results. Optional. | +| `size` | Integer | Maximum number of results to return. Optional. | +| `from` | Integer | Starting index for pagination. Optional. | + +## Example request + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/_search +{ + "query": { + "match_all": {} + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "took": 3, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 4, + "relation": "eq" + }, + "max_score": null, + "hits": [ + { + "_index": "test1-long-term-memory-history", + "_id": "eMxnTpkBvwXRq366hmAU", + "_score": null, + "_source": { + "created_time": "2025-09-15T17:23:51.302920078Z", + "memory_id": "DsxjTpkBvwXRq366C1Zz", + "action": "DELETE", + "after": { + "memory": "Bob really likes swimming" + } + }, + "sort": ["2025-09-15T17:23:51.302920078Z"] + }, + { + "_index": "test1-long-term-memory-history", + "_id": "ecxnTpkBvwXRq366hmAU", + "_score": null, + "_source": { + "created_time": "2025-09-15T17:23:51.303097838Z", + "memory_id": null, + "action": "ADD", + "after": { + "memory": "User doesn't like swimming currently" + } + }, + "sort": ["2025-09-15T17:23:51.303097838Z"] + } + ] + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `action` | String | The type of operation performed: "ADD", "UPDATE", or "DELETE". | +| `memory_id` | String | The ID of the affected memory (null for ADD operations). | +| `created_time` | String | ISO timestamp when the operation occurred. | +| `after` | Object | The memory content after the operation. | +| `before` | Object | The memory content before the operation (for UPDATE operations). | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md new file mode 100644 index 00000000000..fbe89790462 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md @@ -0,0 +1,75 @@ +--- +layout: default +title: Update long-term memory +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 32 +--- + +# Update long-term memory +**Introduced 3.2** +{: .label .label-purple } + +Use this API to update an existing long-term memory within a memory container. + +## Path and HTTP methods + +```json +PUT /_plugins/_ml/memory_containers//memories/long-term/ +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `memory_id` | String | The ID of the long-term memory to update. Required. | + +## Request fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `memory` | String | The updated memory content. Optional. | +| `tags` | Object | Updated tags for categorization. Optional. | +| `additional_info` | Object | Additional metadata to associate with the memory. Optional. | + +## Example request + +```json +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz +{ + "memory": "User's name is Bob Smith", + "tags": { + "topic": "personal info", + "updated": "true" + }, + "additional_info": { + "source": "user_correction" + } +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "result": "updated", + "_id": "DcxjTpkBvwXRq366C1Zz", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the update operation. | +| `_id` | String | The ID of the updated memory. | +| `_version` | Integer | The version number of the updated memory. | +| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md new file mode 100644 index 00000000000..14b09047011 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md @@ -0,0 +1,91 @@ +--- +layout: default +title: Update memory by type and ID +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 52 +--- + +# Update memory by type and ID +**Introduced 3.2** +{: .label .label-purple } + +Use this API to update a specific memory by its type and ID. This unified API supports updating session, working, and long-term memory data. History memory does not support updates. + +## Path and HTTP methods + +```json +PUT /_plugins/_ml/memory_containers//memories// +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. Required. | +| `type` | String | The type of memory: "session", "working", or "long-term". Required. | +| `id` | String | The ID of the memory to update. Required. | + +## Request fields + +The request fields vary depending on the memory type being updated: + +### For session memory + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `additional_info` | Object | Additional metadata to associate with the session. Optional. | + +### For working memory + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `messages` | Array | Updated conversation messages (for conversation type). Optional. | +| `structured_data` | Object | Updated structured data content (for data type). Optional. | +| `tags` | Object | Updated tags for categorization. Optional. | +| `additional_info` | Object | Additional metadata. Optional. | + +### For long-term memory + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `memory` | String | The updated memory content. Optional. | +| `tags` | Object | Updated tags for categorization. Optional. | +| `additional_info` | Object | Additional metadata. Optional. | + +## Example request + +```json +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/session/N2CDipkB2Mtr6INFFcX8 +{ + "additional_info": { + "key1": "value1", + "last_activity": "2025-09-15T17:30:00Z" + } +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "result": "updated", + "_id": "N2CDipkB2Mtr6INFFcX8", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the update operation. | +| `_id` | String | The ID of the updated memory. | +| `_version` | Integer | The version number of the updated memory. | +| `_shards` | Object | Information about the shards involved in the operation. | From ab7fd46add55c81f74ef5c54f059420df50650e0 Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Thu, 9 Oct 2025 18:15:28 -0700 Subject: [PATCH 09/27] Consolidate agentic memory APIs and update with real response examples - Remove redundant API files in favor of unified memory APIs - Delete legacy files: delete-long-term-memory.md, delete-memory-history.md, search-long-term-memory.md, search-memory-history.md, update-long-term-memory.md, search-memory.md, delete-memory.md, update-memory.md, get-memory.md - Enhance unified APIs with comprehensive examples for all memory types (sessions, working, long-term, history) - Add metadata field documentation to add-memory.md and get-memory-by-type.md - Update response examples and field documentation with actual API responses - Update index.md to reflect clean unified API structure - Fix memory type parameter names (sessions vs session) for consistency Signed-off-by: Dhrubo Saha --- .../api/agentic-memory-apis/add-memory.md | 20 +++ .../delete-long-term-memory.md | 57 ------- .../delete-memory-by-type.md | 26 +++- .../delete-memory-history.md | 57 ------- .../api/agentic-memory-apis/delete-memory.md | 47 ------ .../agentic-memory-apis/get-memory-by-type.md | 141 ++++++++++++++++-- .../api/agentic-memory-apis/get-memory.md | 57 ------- .../api/agentic-memory-apis/index.md | 21 +-- .../search-long-term-memory.md | 137 ----------------- .../search-memories-by-type.md | 56 ++++++- .../search-memory-history.md | 117 --------------- .../api/agentic-memory-apis/search-memory.md | 58 ------- .../update-long-term-memory.md | 75 ---------- .../update-memory-by-type.md | 33 +++- .../api/agentic-memory-apis/update-memory.md | 58 ------- 15 files changed, 252 insertions(+), 708 deletions(-) delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/delete-memory-history.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/delete-memory.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/get-memory.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-memory.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/update-memory.md diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 76a9187ac8a..1798a2896d5 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -41,6 +41,7 @@ Field | Data type | Required/Optional | Description `structured_data` | Object | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. `memory_type` | String | Required | The type of memory: `conversation` or `data`. `namespace` | Object | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). +`metadata` | Object | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). `session_id` | String | Optional | The session ID associated with the memory. Deprecated in favor of using `namespace.session_id`. `agent_id` | String | Optional | The agent ID associated with the memory. Deprecated in favor of using `namespace.agent_id`. `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. @@ -66,6 +67,13 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "namespace": { "user_id": "bob" }, + "metadata": { + "status": "checkpoint", + "branch": { + "branch_name": "high", + "root_event_id": "228nadfs879mtgk" + } + }, "tags": { "topic": "personal info" }, @@ -88,6 +96,10 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "namespace": { "agent_id": "testAgent1" }, + "metadata": { + "status": "checkpoint", + "anyobject": "abc" + }, "tags": { "topic": "agent_state" }, @@ -117,6 +129,14 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "agent_id": "testAgent1", "session_id": "123" }, + "metadata": { + "status": "checkpoint", + "branch": { + "branch_name": "high", + "root_event_id": "228nadfs879mtgk" + }, + "anyobject": "abc" + }, "tags": { "topic": "personal info", "parent_memory_id": "o4-WWJkBFT7urc7Ed9hM", diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md deleted file mode 100644 index c5c0f653ec6..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -layout: default -title: Delete long-term memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 33 ---- - -# Delete long-term memory -**Introduced 3.2** -{: .label .label-purple } - -Use this API to delete a specific long-term memory from a memory container. - -## Path and HTTP methods - -```json -DELETE /_plugins/_ml/memory_containers//memories/long-term/ -``` - -## Path parameters - -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | -| `memory_id` | String | The ID of the long-term memory to delete. Required. | - -## Example request - -```json -DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "result": "deleted", - "_id": "DcxjTpkBvwXRq366C1Zz", - "_version": 2, - "_shards": { - "total": 2, - "successful": 1, - "failed": 0 - } -} -``` - -## Response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `result` | String | The result of the delete operation. | -| `_id` | String | The ID of the deleted memory. | -| `_version` | Integer | The version number after deletion. | -| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md index 0861d95b90c..08fe2adc097 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md @@ -10,7 +10,7 @@ nav_order: 53 **Introduced 3.2** {: .label .label-purple } -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. +Use this API to delete a specific memory by its type and ID. This unified API supports deleting all memory types: session, working, long-term, and history memory data. ## Path and HTTP methods @@ -23,14 +23,34 @@ DELETE /_plugins/_ml/memory_containers//memories///memories/history/ -``` - -## Path parameters - -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | -| `history_id` | String | The ID of the history event to delete. Required. | - -## Example request - -```json -DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTpkBvwXRq366hmAU -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "result": "deleted", - "_id": "eMxnTpkBvwXRq366hmAU", - "_version": 2, - "_shards": { - "total": 2, - "successful": 1, - "failed": 0 - } -} -``` - -## Response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `result` | String | The result of the delete operation. | -| `_id` | String | The ID of the deleted history event. | -| `_version` | Integer | The version number after deletion. | -| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md deleted file mode 100644 index e7263b60e44..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -layout: default -title: Delete agentic memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 80 ---- - -# Delete Agentic Memory API -**Introduced 3.2** -{: .label .label-purple } - -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/). -{: .warning} - -Use this API to delete an agentic memory by its ID. - -## Endpoint - -```json -DELETE /_plugins/_ml/memory_containers/{memory_container_id}/memories/{memory_id} -``` - -## Example request - -```json -DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/T9jtmpgBOh0h20Y91WtZ -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "_index": "ml-static-memory-sdjmmpgboh0h20y9kwun-admin", - "_id": "S9jnmpgBOh0h20Y9qWu7", - "_version": 3, - "result": "deleted", - "_shards": { - "total": 2, - "successful": 2, - "failed": 0 - }, - "_seq_no": 3, - "_primary_term": 1 -} -``` \ No newline at end of file diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md index 5940b448af8..0a9b2ea0e4f 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md @@ -23,17 +23,39 @@ GET /_plugins/_ml/memory_containers//memories// | Parameter | Data type | Description | | :--- | :--- | :--- | | `memory_container_id` | String | The ID of the memory container. Required. | -| `type` | String | The type of memory: "session", "working", "long-term", or "history". Required. | +| `type` | String | The type of memory: "sessions", "working", "long-term", or "history". Required. | | `id` | String | The ID of the memory to retrieve. Required. | -## Example request +## Example requests + +### Get working memory ```json GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM ``` + +### Get long-term memory + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz +``` + +### Get session + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/CcxjTpkBvwXRq366A1aE +``` + +### Get memory history + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTpkBvwXRq366hmAU +``` {% include copy-curl.html %} -## Example response +## Example responses + +### Working memory response ```json { @@ -53,6 +75,13 @@ GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJ "user_id": "bob", "session_id": "S-dqiJkB1SltqOcZ1cYO" }, + "metadata": { + "status": "checkpoint", + "branch": { + "branch_name": "high", + "root_event_id": "228nadfs879mtgk" + } + }, "infer": true, "tags": { "topic": "personal info" @@ -62,31 +91,117 @@ GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJ } ``` +### Long-term memory response + +```json +{ + "memory": "Kubernetes RBAC permission issues detected with CloudWatch agents experiencing persistent permission denials", + "strategy_type": "SUMMARY", + "tags": { + "agent_type": "chat_agent", + "conversation": "true" + }, + "namespace": { + "agent_id": "soap-user" + }, + "namespace_size": 1, + "created_time": 1760052801773, + "last_updated_time": 1760052801773, + "memory_embedding": [0.018510794, 0.056366503, "..."], + "owner_id": "admin", + "strategy_id": "summary_96f04d97" +} +``` + +### Session response + +```json +{ + "memory_container_id": "HudqiJkB1SltqOcZusVU", + "namespace": { + "user_id": "bob" + }, + "created_time": "2025-09-15T17:18:55.881276939Z", + "last_updated_time": "2025-09-15T17:18:55.881276939Z" +} +``` + +### History response + +```json +{ + "owner_id": "admin", + "memory_container_id": "nrJBy5kByIxXWyhQjmqv", + "memory_id": "4bJMy5kByIxXWyhQvGr9", + "action": "ADD", + "after": { + "memory": "A comprehensive security investigation was performed across multiple data sources including 55 OpenSearch indices, 50 CloudTrail events, 22 VPC Flow logs, 38 WAF events, 74 CloudWatch log groups, active CloudWatch alarms, and OpenSearch cluster security configuration." + }, + "namespace": { + "agent_id": "soap-user" + }, + "namespace_size": 1, + "tags": { + "agent_type": "chat_agent", + "conversation": "true" + }, + "created_time": 1760052428089 +} +``` + ## Response fields The response fields vary depending on the memory type: ### Working memory response fields +| Field | Data type | Description | +|:----------------------| :--- |:--------------------------------------------------------| +| `memory_container_id` | String | The ID of the memory container. | +| `payload_type` | String | The type of payload: "conversation" or "data". | +| `messages` | Array | Array of conversation messages (for conversation type). | +| `namespace` | Object | The namespace context for this memory. | +| `metadata` | Object | Additional metadata associated with the memory. | +| `tags` | Object | Associated tags for categorization. | +| `infer` | Boolean | Whether inference was enabled for this memory. | +| `created_time` | Long | Timestamp when the memory was created. | +| `last_updated_time` | Long | Timestamp when the memory was last updated. | + +### Long-term memory response fields + | Field | Data type | Description | | :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. | -| `memory_type` | String | The type of memory: "conversation" or "data". | -| `messages` | Array | Array of conversation messages (for conversation type). | -| `structured_data` | Object | Structured data content (for data type). | +| `memory` | String | The extracted long-term memory fact. | +| `strategy_type` | String | The type of memory strategy used (e.g., "SEMANTIC", "SUMMARY", "USER_PREFERENCE"). | | `namespace` | Object | The namespace context for this memory. | +| `namespace_size` | Integer | The size of the namespace. | | `tags` | Object | Associated tags for categorization. | -| `infer` | Boolean | Whether inference was enabled for this memory. | | `created_time` | Long | Timestamp when the memory was created. | | `last_updated_time` | Long | Timestamp when the memory was last updated. | +| `memory_embedding` | Array | Vector embedding of the memory content (truncated in display). | +| `owner_id` | String | The owner of the memory. | +| `strategy_id` | String | The unique identifier for the strategy instance. | -### Long-term memory response fields +### Session response fields | Field | Data type | Description | | :--- | :--- | :--- | -| `memory` | String | The extracted long-term memory fact. | +| `memory_container_id` | String | The ID of the memory container. | +| `namespace` | Object | The namespace context for this session. | +| `created_time` | String | ISO timestamp when the session was created. | +| `last_updated_time` | String | ISO timestamp when the session was last updated. | + +### History response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `owner_id` | String | The owner of the memory. | +| `memory_container_id` | String | The ID of the memory container. | +| `memory_id` | String | The ID of the affected memory. | +| `action` | String | The type of operation: "ADD", "UPDATE", or "DELETE". | +| `after` | Object | The memory content after the operation. | +| `before` | Object | The memory content before the operation (for UPDATE operations). | | `namespace` | Object | The namespace context for this memory. | -| `memory_type` | String | The type of memory strategy used. | +| `namespace_size` | Integer | The size of the namespace. | | `tags` | Object | Associated tags for categorization. | -| `created_time` | Long | Timestamp when the memory was created. | -| `last_updated_time` | Long | Timestamp when the memory was last updated. | +| `created_time` | Long | Timestamp when the operation occurred. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md deleted file mode 100644 index 7030fc4b090..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -layout: default -title: Get agentic memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 60 ---- - -# Get Agentic Memory API -**Introduced 3.2** -{: .label .label-purple } - -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/). -{: .warning} - -Use this API to retrieve an agentic memory by its ID. - -## Endpoint - -```json -GET /_plugins/_ml/memory_containers/{memory_container_id}/memories/{memory_id} -``` - -## Example request - -```json -GET /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/T9jtmpgBOh0h20Y91WtZ -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "session_id": "sess_a99c5a19-cee3-44ce-b64d-6fbdc411c537", - "memory": "Machine learning is a subset of artificial intelligence", - "memory_type": "RAW_MESSAGE", - "user_id": "admin", - "role": "assistant", - "created_time": 1754945934681, - "last_updated_time": 1754945934681 -} -``` - -## Response body fields - -The following table lists all response body fields. - -| Field | Data type | Description | -| :------------------ | :-------- | :--------------------------------------------------------------------------------------- | -| `session_id` | String | The unique identifier for the session associated with this memory. | -| `memory` | String | If the memory was created with `infer: false`, contains the stored text from the message. If the memory was created with `infer: true`, contains the extracted fact from the message. | -| `memory_type` | String | The type of memory. `RAW_MESSAGE` indicates the unprocessed message text. `FACT` indicates a fact inferred by the large language model. | -| `user_id` | String | The ID of the user associated with this memory. | -| `role` | String | The role of the message author. Can be any string, such as `assistant` or `user`. | -| `created_time` | Integer | The Unix timestamp, in milliseconds, when the memory entry was created. | -| `last_updated_time` | Integer | The Unix timestamp, in milliseconds, when the memory entry was last updated. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/index.md b/_ml-commons-plugin/api/agentic-memory-apis/index.md index cd9f8c98d68..bb4ca70a7b9 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/index.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/index.md @@ -41,26 +41,9 @@ OpenSearch supports the following memory container APIs: OpenSearch supports the following memory APIs: -## Working memory APIs - -- [Add working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/add-memory/) -- [Get working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/) -- [Search working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory/) -- [Delete working memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory/) - -## Long-term memory APIs - -- [Search long-term memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory/) -- [Update long-term memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory/) -- [Delete long-term memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-long-term-memory/) - -## Memory history APIs - -- [Search memory history]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory-history/) -- [Delete memory history]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory-history/) - -## General memory APIs +## Memory APIs (Unified) +- [Add memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/add-memory/) - [Get memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type/) - [Update memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type/) - [Delete memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type/) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md deleted file mode 100644 index 1942e273039..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -layout: default -title: Search long-term memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 31 ---- - -# Search long-term memory -**Introduced 3.2** -{: .label .label-purple } - -Use this API to search for long-term memories within a memory container. Long-term memories are extracted facts from conversation messages that are stored for semantic retrieval. - -## Path and HTTP methods - -```json -GET /_plugins/_ml/memory_containers//memories/long-term/_search -``` - -## Path parameters - -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | - -## Request fields - -The request body supports standard OpenSearch query DSL. Common fields include: - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `query` | Object | The search query using OpenSearch query DSL. Optional. | -| `sort` | Array | Sort criteria for the results. Optional. | -| `size` | Integer | Maximum number of results to return. Optional. | -| `from` | Integer | Starting index for pagination. Optional. | - -## Example request - -```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/_search -{ - "query": { - "bool": { - "must": [ - { - "term": { - "namespace.user_id": "bob" - } - } - ] - } - }, - "sort": [ - { - "created_time": { - "order": "desc" - } - } - ] -} -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "took": 5, - "timed_out": false, - "_shards": { - "total": 1, - "successful": 1, - "skipped": 0, - "failed": 0 - }, - "hits": { - "total": { - "value": 2, - "relation": "eq" - }, - "max_score": null, - "hits": [ - { - "_index": "test1-long-term-memory", - "_id": "DcxjTpkBvwXRq366C1Zz", - "_score": null, - "_source": { - "created_time": 1757956737699, - "memory": "User's name is Bob", - "last_updated_time": 1757956737699, - "namespace_size": 1, - "namespace": { - "user_id": "bob" - }, - "memory_type": "SEMANTIC", - "tags": { - "topic": "personal info" - } - }, - "sort": [1757956737699] - }, - { - "_index": "test1-long-term-memory", - "_id": "DsxjTpkBvwXRq366C1Zz", - "_score": null, - "_source": { - "created_time": 1757956737699, - "memory": "Bob really likes swimming", - "last_updated_time": 1757956737699, - "namespace_size": 1, - "namespace": { - "user_id": "bob" - }, - "memory_type": "SEMANTIC", - "tags": { - "topic": "personal info" - } - }, - "sort": [1757956737699] - } - ] - } -} -``` - -## Response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `memory` | String | The extracted long-term memory fact. | -| `namespace` | Object | The namespace context for this memory. | -| `memory_type` | String | The type of memory strategy used (e.g., "SEMANTIC"). | -| `tags` | Object | Associated tags for categorization. | -| `created_time` | Long | Timestamp when the memory was created. | -| `last_updated_time` | Long | Timestamp when the memory was last updated. | -| `namespace_size` | Integer | The size of the namespace. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md index 6419abe9859..8818efa8547 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md @@ -23,7 +23,7 @@ GET /_plugins/_ml/memory_containers//memories//_searc | Parameter | Data type | Description | | :--- | :--- | :--- | | `memory_container_id` | String | The ID of the memory container. Required. | -| `type` | String | The type of memory: "session", "working", "long-term", or "history". Required. | +| `type` | String | The type of memory: "sessions", "working", "long-term", or "history". Required. | ## Request fields @@ -38,10 +38,54 @@ The request body supports standard OpenSearch query DSL. Common fields include: ## Example requests -### Search session memories +### Search sessions ```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/session/_search +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/_search +{ + "query": { + "match_all": {} + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` + +### Search long-term memories + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/_search +{ + "query": { + "bool": { + "must": [ + { + "term": { + "namespace.user_id": "bob" + } + } + ] + } + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` + +### Search memory history + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/_search { "query": { "match_all": {} @@ -150,8 +194,6 @@ GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_searc ## Response fields -The response fields vary depending on the memory type being searched. See the individual memory type documentation for specific field descriptions: +The response fields vary depending on the memory type being searched. See the unified memory API documentation for specific field descriptions: -- [Working memory fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/) -- [Long-term memory fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-long-term-memory/) -- [Memory history fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory-history/) +- [Get memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type/) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md deleted file mode 100644 index 987aa2c4fc9..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-history.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -layout: default -title: Search memory history -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 41 ---- - -# Search memory history -**Introduced 3.2** -{: .label .label-purple } - -Use this API to search for memory history events within a memory container. Memory history tracks all add, update, and delete operations performed on long-term memories. - -## Path and HTTP methods - -```json -GET /_plugins/_ml/memory_containers//memories/history/_search -``` - -## Path parameters - -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | - -## Request fields - -The request body supports standard OpenSearch query DSL. Common fields include: - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `query` | Object | The search query using OpenSearch query DSL. Optional. | -| `sort` | Array | Sort criteria for the results. Optional. | -| `size` | Integer | Maximum number of results to return. Optional. | -| `from` | Integer | Starting index for pagination. Optional. | - -## Example request - -```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/_search -{ - "query": { - "match_all": {} - }, - "sort": [ - { - "created_time": { - "order": "desc" - } - } - ] -} -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "took": 3, - "timed_out": false, - "_shards": { - "total": 1, - "successful": 1, - "skipped": 0, - "failed": 0 - }, - "hits": { - "total": { - "value": 4, - "relation": "eq" - }, - "max_score": null, - "hits": [ - { - "_index": "test1-long-term-memory-history", - "_id": "eMxnTpkBvwXRq366hmAU", - "_score": null, - "_source": { - "created_time": "2025-09-15T17:23:51.302920078Z", - "memory_id": "DsxjTpkBvwXRq366C1Zz", - "action": "DELETE", - "after": { - "memory": "Bob really likes swimming" - } - }, - "sort": ["2025-09-15T17:23:51.302920078Z"] - }, - { - "_index": "test1-long-term-memory-history", - "_id": "ecxnTpkBvwXRq366hmAU", - "_score": null, - "_source": { - "created_time": "2025-09-15T17:23:51.303097838Z", - "memory_id": null, - "action": "ADD", - "after": { - "memory": "User doesn't like swimming currently" - } - }, - "sort": ["2025-09-15T17:23:51.303097838Z"] - } - ] - } -} -``` - -## Response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `action` | String | The type of operation performed: "ADD", "UPDATE", or "DELETE". | -| `memory_id` | String | The ID of the affected memory (null for ADD operations). | -| `created_time` | String | ISO timestamp when the operation occurred. | -| `after` | Object | The memory content after the operation. | -| `before` | Object | The memory content before the operation (for UPDATE operations). | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md deleted file mode 100644 index bee96e6f0ca..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -layout: default -title: Search agentic memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 70 ---- - -# Search Agentic Memory APIs -**Introduced 3.2** -{: .label .label-purple } - -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/). -{: .warning} - -Use these APIs to to search for an agentic memory in a memory container. These APIs use a query to search for matching memories. - -## Endpoints - -```json -GET /_plugins/_ml/memory_containers/{memory_container_id}/memories/_search -POST /_plugins/_ml/memory_containers/{memory_container_id}/memories/_search -``` - -## Example request - -```json -POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/_search -{ - "query": "machine learning concepts" -} -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "timed_out": false, - "hits": { - "total": 1, - "max_score": 0.69813377, - "hits": [ - { - "memory_id": "T9jtmpgBOh0h20Y91WtZ", - "memory": "Machine learning is a subset of artificial intelligence", - "_score": 0.69813377, - "session_id": "sess_a99c5a19-cee3-44ce-b64d-6fbdc411c537", - "user_id": "admin", - "memory_type": "RAW_MESSAGE", - "role": "assistant", - "created_time": 1754945934681, - "last_updated_time": 1754945934681 - } - ] - } -} -``` \ No newline at end of file diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md deleted file mode 100644 index fbe89790462..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-long-term-memory.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -layout: default -title: Update long-term memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 32 ---- - -# Update long-term memory -**Introduced 3.2** -{: .label .label-purple } - -Use this API to update an existing long-term memory within a memory container. - -## Path and HTTP methods - -```json -PUT /_plugins/_ml/memory_containers//memories/long-term/ -``` - -## Path parameters - -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | -| `memory_id` | String | The ID of the long-term memory to update. Required. | - -## Request fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `memory` | String | The updated memory content. Optional. | -| `tags` | Object | Updated tags for categorization. Optional. | -| `additional_info` | Object | Additional metadata to associate with the memory. Optional. | - -## Example request - -```json -PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz -{ - "memory": "User's name is Bob Smith", - "tags": { - "topic": "personal info", - "updated": "true" - }, - "additional_info": { - "source": "user_correction" - } -} -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "result": "updated", - "_id": "DcxjTpkBvwXRq366C1Zz", - "_version": 2, - "_shards": { - "total": 2, - "successful": 1, - "failed": 0 - } -} -``` - -## Response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `result` | String | The result of the update operation. | -| `_id` | String | The ID of the updated memory. | -| `_version` | Integer | The version number of the updated memory. | -| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md index 14b09047011..5f3f56d9459 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md @@ -23,7 +23,7 @@ PUT /_plugins/_ml/memory_containers//memories// | Parameter | Data type | Description | | :--- | :--- | :--- | | `memory_container_id` | String | The ID of the memory container. Required. | -| `type` | String | The type of memory: "session", "working", or "long-term". Required. | +| `type` | String | The type of memory: "sessions", "working", or "long-term". Required. Note: History memory cannot be updated. | | `id` | String | The ID of the memory to update. Required. | ## Request fields @@ -53,10 +53,12 @@ The request fields vary depending on the memory type being updated: | `tags` | Object | Updated tags for categorization. Optional. | | `additional_info` | Object | Additional metadata. Optional. | -## Example request +## Example requests + +### Update session ```json -PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/session/N2CDipkB2Mtr6INFFcX8 +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/N2CDipkB2Mtr6INFFcX8 { "additional_info": { "key1": "value1", @@ -64,6 +66,31 @@ PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/session/N2CDip } } ``` + +### Update working memory + +```json +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM +{ + "tags": { + "topic": "updated_topic", + "priority": "high" + } +} +``` + +### Update long-term memory + +```json +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz +{ + "memory": "User's name is Bob Smith", + "tags": { + "topic": "personal info", + "updated": "true" + } +} +``` {% include copy-curl.html %} ## Example response diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md deleted file mode 100644 index b6b2bc44ce2..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -layout: default -title: Update agentic memory -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 50 ---- - -# Update Agentic Memory API -**Introduced 3.2** -{: .label .label-purple } - -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/). -{: .warning} - -Use this API to update an agentic memory. - -## Endpoint - -```json -PUT /_plugins/_ml/memory_containers/{memory_container_id}/memories/{memory_id} -``` - -## Request body fields - -The following table lists the available request body fields. - -Field | Data type | Required/Optional | Description -:--- | :--- | :--- | :--- -`text` | String | Required | The updated `text` content. - -## Example request - -```json -PUT /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/T9jtmpgBOh0h20Y91WtZ -{ - "text": "Updated content with new information about machine learning" -} -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "_index": "ml-static-memory-sdjmmpgboh0h20y9kwun-admin", - "_id": "S9jnmpgBOh0h20Y9qWu7", - "_version": 2, - "result": "updated", - "_shards": { - "total": 2, - "successful": 2, - "failed": 0 - }, - "_seq_no": 2, - "_primary_term": 1 -} -``` \ No newline at end of file From c5a4cc80ab47aaf1a3d0c3e9b38c1b5c5204de41 Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Thu, 9 Oct 2025 20:24:41 -0700 Subject: [PATCH 10/27] Complete agentic memory API documentation with missing container APIs - Add missing update-memory-container.md and search-memory-container.md files - Update create-memory-container.md with advanced features from Postman collection: * Multiple strategy support (SEMANTIC, USER_PREFERENCE, SUMMARY) * Strategy configuration with llm_result_path * Index configuration (index_prefix, use_system_index) * Remove experimental warning (GA in 3.3) - Remove experimental feature reference from index.md - All APIs now match actual implementation from Postman collection Signed-off-by: Dhrubo Saha --- .../create-memory-container.md | 110 +++++++++++++++--- .../api/agentic-memory-apis/index.md | 2 - .../search-memory-container.md | 100 ++++++++++++++++ .../update-memory-container.md | 66 +++++++++++ 4 files changed, 258 insertions(+), 20 deletions(-) create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index 34437cf68cc..6747ee3c084 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -10,9 +10,6 @@ nav_order: 10 **Introduced 3.2** {: .label .label-purple } -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/). -{: .warning} - Use this API to create a memory container to hold agentic memories. The container can have two model types associated with it: - 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. @@ -143,33 +140,110 @@ Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- `name` | String | Required | The name of the memory container. `description` | String | Optional | The description of the memory container. -`memory_storage_config` | Object | Optional | The memory storage configuration. See [the `memory_storage_config` object](#the-memory_storage_config-object). +`configuration` | Object | Required | The memory container configuration. See [the `configuration` object](#the-configuration-object). -### The memory_storage_config object +### The configuration object -The `memory_storage_config` object supports the following fields. +The `configuration` object supports the following fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`dimension` | Integer | Optional | The dimension of the embedding model. Required if `embedding_model_type` is `TEXT_EMBEDDING`. -`embedding_model_id` | String | Optional | The embedding model ID. `embedding_model_type` | String | Optional | The embedding model type. Supported types are `TEXT_EMBEDDING` and `SPARSE_ENCODING`. -`llm_model_id` | String | Optional | The LLM ID. -`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. -`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. +`embedding_model_id` | String | Optional | The embedding model ID. +`embedding_dimension` | Integer | Optional | The dimension of the embedding model. Required if `embedding_model_type` is `TEXT_EMBEDDING`. +`llm_id` | String | Optional | The LLM model ID for processing and inference. +`index_prefix` | String | Optional | Custom prefix for the memory indices. If not specified, a default prefix is used. +`use_system_index` | Boolean | Optional | Whether to use system indices. Default is `true`. +`strategies` | Array | Optional | Array of memory processing strategies. See [the `strategies` array](#the-strategies-array). +`parameters` | Object | Optional | Global parameters for the memory container. See [the `parameters` object](#the-parameters-object). + +### The strategies array + +Each strategy in the `strategies` array supports the following fields. + +Field | Data type | Required/Optional | Description +:--- | :--- | :--- | :--- +`type` | String | Required | The strategy type: `SEMANTIC`, `USER_PREFERENCE`, or `SUMMARY`. +`namespace` | Array | Required | Array of namespace dimensions for organizing memories (e.g., `["user_id"]`, `["agent_id"]`). +`configuration` | Object | Optional | Strategy-specific configuration. See [the strategy `configuration` object](#the-strategy-configuration-object). + +### The strategy configuration object + +Field | Data type | Required/Optional | Description +:--- | :--- | :--- | :--- +`llm_result_path` | String | Optional | JSONPath to extract LLM results (e.g., `"$.output.message.content[0].text"`). + +### The parameters object + +Field | Data type | Required/Optional | Description +:--- | :--- | :--- | :--- +`llm_result_path` | String | Optional | Global JSONPath for extracting LLM results from responses. + +## Example requests + +### Basic memory container + +```json +POST /_plugins/_ml/memory_containers/_create +{ + "name": "agentic memory test", + "description": "Store conversations with semantic search and summarization", + "configuration": { + "embedding_model_type": "TEXT_EMBEDDING", + "embedding_model_id": "{{embedding_model_id}}", + "embedding_dimension": 1024, + "llm_id": "{{llm_id}}", + "strategies": [ + { + "type": "SEMANTIC", + "namespace": ["user_id"] + } + ] + } +} +``` -## Example request +### Advanced memory container with multiple strategies ```json POST /_plugins/_ml/memory_containers/_create { - "name": "Sparse memory container", - "description": "Store sparse conversations with semantic search", - "memory_storage_config": { - "llm_model_id": "bbphdJgB9L0Qb_M6ipnn", - "embedding_model_type": "SPARSE_ENCODING", - "embedding_model_id": "RodoX5gBfObQ5OgTHf1X" + "name": "agentic memory test", + "description": "Store conversations with semantic search and summarization", + "configuration": { + "embedding_model_type": "TEXT_EMBEDDING", + "embedding_model_id": "{{embedding_model_id}}", + "embedding_dimension": 1024, + "llm_id": "{{llm_id}}", + "index_prefix": "my_custom_prefix", + "use_system_index": false, + "strategies": [ + { + "type": "SEMANTIC", + "namespace": ["agent_id"], + "configuration": { + "llm_result_path": "$.output.message.content[0].text" + } + }, + { + "type": "USER_PREFERENCE", + "namespace": ["agent_id"], + "configuration": { + "llm_result_path": "$.output.message.content[0].text" + } + }, + { + "type": "SUMMARY", + "namespace": ["agent_id"], + "configuration": { + "llm_result_path": "$.output.message.content[0].text" + } + } + ], + "parameters": { + "llm_result_path": "$.output.message.content[0].text" } + } } ``` {% include copy-curl.html %} diff --git a/_ml-commons-plugin/api/agentic-memory-apis/index.md b/_ml-commons-plugin/api/agentic-memory-apis/index.md index bb4ca70a7b9..9695a62a7d8 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/index.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/index.md @@ -29,8 +29,6 @@ PUT /_cluster/settings ``` {% include copy-curl.html %} -For more information and other ways to enable experimental features, see [Experimental feature flags]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/experimental/). - OpenSearch supports the following memory container APIs: - [Create memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container/) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md new file mode 100644 index 00000000000..98eee0bb1b6 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md @@ -0,0 +1,100 @@ +--- +layout: default +title: Search memory containers +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 25 +--- + +# Search memory containers +**Introduced 3.2** +{: .label .label-purple } + +Use this API to search for memory containers using OpenSearch query DSL. + +## Path and HTTP methods + +```json +GET /_plugins/_ml/memory_containers/_search +POST /_plugins/_ml/memory_containers/_search +``` + +## Request fields + +The request body supports standard OpenSearch query DSL. Common fields include: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `query` | Object | The search query using OpenSearch query DSL. Optional. | +| `sort` | Array | Sort criteria for the results. Optional. | +| `size` | Integer | Maximum number of results to return. Optional. | +| `from` | Integer | Starting index for pagination. Optional. | + +## Example request + +```json +GET /_plugins/_ml/memory_containers/_search +{ + "query": { + "match_all": {} + } +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "took": 5, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 2, + "relation": "eq" + }, + "max_score": 1.0, + "hits": [ + { + "_index": ".plugins-ml-memory-meta", + "_id": "HudqiJkB1SltqOcZusVU", + "_score": 1.0, + "_source": { + "name": "agentic memory test", + "description": "Store conversations with semantic search and summarization", + "configuration": { + "embedding_model_type": "TEXT_EMBEDDING", + "embedding_model_id": "uXZAtJkBvHNmcp1JAROh", + "embedding_dimension": 1024, + "llm_id": "aFouy5kBrfmzAZ6R6wo-", + "strategies": [ + { + "type": "SEMANTIC", + "namespace": ["user_id"] + } + ] + }, + "created_time": 1757956737699, + "last_updated_time": 1757956737699 + } + } + ] + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `name` | String | The name of the memory container. | +| `description` | String | The description of the memory container. | +| `configuration` | Object | The memory container configuration including models and strategies. | +| `created_time` | Long | Timestamp when the container was created. | +| `last_updated_time` | Long | Timestamp when the container was last updated. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md new file mode 100644 index 00000000000..af4ea79820d --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md @@ -0,0 +1,66 @@ +--- +layout: default +title: Update memory container +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 15 +--- + +# Update memory container +**Introduced 3.2** +{: .label .label-purple } + +Use this API to update an existing memory container's properties such as name and description. + +## Path and HTTP methods + +```json +PUT /_plugins/_ml/memory_containers/ +``` + +## Path parameters + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container to update. Required. | + +## Request fields + +| Field | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `name` | String | Optional | The updated name of the memory container. | +| `description` | String | Optional | The updated description of the memory container. | + +## Example request + +```json +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU +{ + "name": "opensearch-agents-memory" +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "result": "updated", + "_id": "HudqiJkB1SltqOcZusVU", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the update operation. | +| `_id` | String | The ID of the updated memory container. | +| `_version` | Integer | The version number of the updated memory container. | +| `_shards` | Object | Information about the shards involved in the operation. | From ee90e2404ed6322a3e7fa35b87e2b61c528b6909 Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Thu, 9 Oct 2025 20:34:13 -0700 Subject: [PATCH 11/27] Document default llm_result_path and LLM connector requirements - Add default llm_result_path value: $.output.message.content[0].text (Bedrock Converse format) - Document LLM connector requirement for system_prompt and user_prompt parameters - Reference ml-commons PR #4283 for standardized connector format - Clarify that default is optimized for Bedrock Converse API Signed-off-by: Dhrubo Saha --- .../api/agentic-memory-apis/create-memory-container.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index 6747ee3c084..f909c4c4d87 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -15,6 +15,8 @@ Use this API to create a memory container to hold agentic memories. The containe - 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. - 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. +**Note**: LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is configured for Bedrock Converse API format (`"$.output.message.content[0].text"`). + Once a memory container is created, you'll provide its `memory_container_id` to other APIs. ## Prerequisites @@ -171,13 +173,13 @@ Field | Data type | Required/Optional | Description Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`llm_result_path` | String | Optional | JSONPath to extract LLM results (e.g., `"$.output.message.content[0].text"`). +`llm_result_path` | String | Optional | JSONPath to extract LLM results. Default is `"$.output.message.content[0].text"` for Bedrock Converse API format. ### The parameters object Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`llm_result_path` | String | Optional | Global JSONPath for extracting LLM results from responses. +`llm_result_path` | String | Optional | Global JSONPath for extracting LLM results from responses. Default is `"$.output.message.content[0].text"` for Bedrock Converse API format. ## Example requests From e82965d48bb3af8c4d332ba81d1fd59a4d7ecdec Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Fri, 10 Oct 2025 10:38:12 -0700 Subject: [PATCH 12/27] Address ylwu-amzn review comments - Update add-memory.md terminology: memory_type -> payload_type, conversational/data types - Add Required/Optional column format to parameter tables - Update version labels from 3.2 to 3.3 for new unified APIs - Add binary_data and tags fields with correct data types - Fix metadata field representation as string in response examples - Add detailed explanations for namespace session creation behavior - Update create-memory-container.md with system_prompt and llm_id strategy fields - Add detailed index_prefix default behavior explanation - Show multiple namespace field examples in strategy configuration Signed-off-by: Dhrubo Saha --- .../api/agentic-memory-apis/add-memory.md | 43 ++++++++++--------- .../create-memory-container.md | 12 ++++-- .../delete-memory-by-type.md | 12 +++--- .../agentic-memory-apis/get-memory-by-type.md | 7 +-- 4 files changed, 38 insertions(+), 36 deletions(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 1798a2896d5..4fdd8d9e185 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -11,17 +11,15 @@ nav_order: 40 {: .label .label-purple } -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: +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 provide memory payload in two types: -- **Conversation memory** -- Stores conversational messages between users and assistants. Can be processed (when `infer` is `true`) to extract facts or stored as raw messages. +- **conversational** -- Stores conversational messages between users and assistants. -- **Data memory** -- Stores structured, non-conversational data such as agent state, checkpoints, or reference information. +- **data** -- Stores extra messages, structured, non-conversational data such as agent state, checkpoints, or reference information. -Memory processing modes (controlled by the `infer` parameter): +- **infer=true** -- Use large language model (LLM) to extract key information or knowledge from the messages. -- 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. - -- Raw message memory -- The unprocessed message content. +- **infer=false** -- Only store raw messages and data in working memory. Once an agentic memory is created, you'll provide its `memory_id` to other APIs. @@ -37,19 +35,18 @@ The following table lists the available request body fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`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`. -`structured_data` | Object | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. -`memory_type` | String | Required | The type of memory: `conversation` or `data`. -`namespace` | Object | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). -`metadata` | Object | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). -`session_id` | String | Optional | The session ID associated with the memory. Deprecated in favor of using `namespace.session_id`. -`agent_id` | String | Optional | The agent ID associated with the memory. Deprecated in favor of using `namespace.agent_id`. -`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. -`tags` | Object | Optional | Custom metadata for the agentic memory. +`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`. +`structured_data` | Map | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. +`binary_data` | String | Optional | Binary data content encoded as base64 string for binary payloads. +`payload_type` | String | Required | The type of payload: `conversational` or `data`. +`namespace` | List | 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. +`metadata` | Map | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). +`tags` | List | Optional | Tags for categorizing and organizing memories. +`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. ## Example requests -### Conversation memory +### Conversational payload ```json POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories @@ -78,11 +75,13 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "topic": "personal info" }, "infer": true, - "memory_type": "conversation" + "payload_type": "conversational" } ``` -### Data memory +### Data payload + +Store agent state in working memory: ```json POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories @@ -104,12 +103,14 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "topic": "agent_state" }, "infer": false, - "memory_type": "data" + "payload_type": "data" } ``` ### Trace data memory +Store agent trace data in working memory: + ```json POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories { @@ -143,7 +144,7 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "data_type": "trace" }, "infer": false, - "memory_type": "conversation" + "payload_type": "conversational" } ``` {% include copy-curl.html %} diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index f909c4c4d87..ce919dd90df 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -154,7 +154,7 @@ Field | Data type | Required/Optional | Description `embedding_model_id` | String | Optional | The embedding model ID. `embedding_dimension` | Integer | Optional | The dimension of the embedding model. Required if `embedding_model_type` is `TEXT_EMBEDDING`. `llm_id` | String | Optional | The LLM model ID for processing and inference. -`index_prefix` | String | Optional | Custom prefix for the memory indices. If not specified, a default prefix is used. +`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. `use_system_index` | Boolean | Optional | Whether to use system indices. Default is `true`. `strategies` | Array | Optional | Array of memory processing strategies. See [the `strategies` array](#the-strategies-array). `parameters` | Object | Optional | Global parameters for the memory container. See [the `parameters` object](#the-parameters-object). @@ -166,14 +166,16 @@ Each strategy in the `strategies` array supports the following fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- `type` | String | Required | The strategy type: `SEMANTIC`, `USER_PREFERENCE`, or `SUMMARY`. -`namespace` | Array | Required | Array of namespace dimensions for organizing memories (e.g., `["user_id"]`, `["agent_id"]`). -`configuration` | Object | Optional | Strategy-specific configuration. See [the strategy `configuration` object](#the-strategy-configuration-object). +`namespace` | Array | Required | Array of namespace dimensions for organizing memories (e.g., `["user_id"]`, `["agent_id", "session_id"]`). +`configuration` | Map | Optional | Strategy-specific configuration. See [the strategy `configuration` object](#the-strategy-configuration-object). ### The strategy configuration object Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- `llm_result_path` | String | Optional | JSONPath to extract LLM results. Default is `"$.output.message.content[0].text"` for Bedrock Converse API format. +`system_prompt` | String | Optional | Custom system prompt to override the default strategy prompt. +`llm_id` | String | Optional | LLM model ID for this specific strategy, overrides the global LLM setting. ### The parameters object @@ -224,7 +226,9 @@ POST /_plugins/_ml/memory_containers/_create "type": "SEMANTIC", "namespace": ["agent_id"], "configuration": { - "llm_result_path": "$.output.message.content[0].text" + "llm_result_path": "$.output.message.content[0].text", + "system_prompt": "Extract semantic information from user conversations", + "llm_id": "{{custom_llm_id}}" } }, { diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md index 08fe2adc097..8fa06b9e6c7 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md @@ -7,7 +7,7 @@ nav_order: 53 --- # Delete memory by type and ID -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } Use this API to delete a specific memory by its type and ID. This unified API supports deleting all memory types: session, working, long-term, and history memory data. @@ -20,11 +20,11 @@ DELETE /_plugins/_ml/memory_containers//memories// Date: Fri, 10 Oct 2025 10:56:10 -0700 Subject: [PATCH 13/27] Add agentic memory cluster setting - Add plugins.ml_commons.agentic_memory_enabled setting to cluster-settings.md - Enables/disables agentic memory functionality for AI agents - Includes session, working, long-term memory, and memory history features Signed-off-by: Dhrubo Saha --- .../agentic-memory-apis/get-memory-by-type.md | 4 +- .../search-memories-by-type.md | 11 +---- .../search-memory-container.md | 11 +---- .../update-memory-by-type.md | 2 +- .../update-memory-container.md | 2 +- _ml-commons-plugin/cluster-settings.md | 45 +++++++++++++++++++ 6 files changed, 53 insertions(+), 22 deletions(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md index 1e598ccde5e..df474bc54d7 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md @@ -99,7 +99,7 @@ GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTp "conversation": "true" }, "namespace": { - "agent_id": "soap-user" + "agent_id": "chat-agent" }, "namespace_size": 1, "created_time": 1760052801773, @@ -135,7 +135,7 @@ GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTp "memory": "A comprehensive security investigation was performed across multiple data sources including 55 OpenSearch indices, 50 CloudTrail events, 22 VPC Flow logs, 38 WAF events, 74 CloudWatch log groups, active CloudWatch alarms, and OpenSearch cluster security configuration." }, "namespace": { - "agent_id": "soap-user" + "agent_id": "chat-agent" }, "namespace_size": 1, "tags": { diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md index 8818efa8547..84704d31cff 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md @@ -7,7 +7,7 @@ nav_order: 54 --- # Search memories by type -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } Use this API to search for memories of a specific type within a memory container. This unified API supports searching session, working, long-term, and history memory data. @@ -27,14 +27,7 @@ GET /_plugins/_ml/memory_containers//memories//_searc ## Request fields -The request body supports standard OpenSearch query DSL. Common fields include: - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `query` | Object | The search query using OpenSearch query DSL. Optional. | -| `sort` | Array | Sort criteria for the results. Optional. | -| `size` | Integer | Maximum number of results to return. Optional. | -| `from` | Integer | Starting index for pagination. Optional. | +The request body supports standard OpenSearch query DSL. ## Example requests diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md index 98eee0bb1b6..092808264fe 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md @@ -7,7 +7,7 @@ nav_order: 25 --- # Search memory containers -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } Use this API to search for memory containers using OpenSearch query DSL. @@ -21,14 +21,7 @@ POST /_plugins/_ml/memory_containers/_search ## Request fields -The request body supports standard OpenSearch query DSL. Common fields include: - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `query` | Object | The search query using OpenSearch query DSL. Optional. | -| `sort` | Array | Sort criteria for the results. Optional. | -| `size` | Integer | Maximum number of results to return. Optional. | -| `from` | Integer | Starting index for pagination. Optional. | +The request body supports standard OpenSearch query DSL. ## Example request diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md index 5f3f56d9459..10f182ff846 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md @@ -7,7 +7,7 @@ nav_order: 52 --- # Update memory by type and ID -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } Use this API to update a specific memory by its type and ID. This unified API supports updating session, working, and long-term memory data. History memory does not support updates. diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md index af4ea79820d..5b4fa548f95 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md @@ -7,7 +7,7 @@ nav_order: 15 --- # Update memory container -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } Use this API to update an existing memory container's properties such as name and description. diff --git a/_ml-commons-plugin/cluster-settings.md b/_ml-commons-plugin/cluster-settings.md index 2cab887487a..16d9df1b6db 100644 --- a/_ml-commons-plugin/cluster-settings.md +++ b/_ml-commons-plugin/cluster-settings.md @@ -494,6 +494,51 @@ plugins.ml_commons.memory_feature_enabled: true - Default value: `true` - Valid values: `false`, `true` +## Enable agentic memory + +When set to `true`, this setting enables agentic memory functionality, which provides advanced memory management for AI agents including session memory, working memory, long-term memory, and memory history with namespace-based organization. + +### Setting + +```yaml +plugins.ml_commons.agentic_memory_enabled: true +``` + +### Values + +- Default value: `true` +- Valid values: `false`, `true` + +## Set maximum memory containers per user + +Controls the maximum number of memory containers that can be created per user. When set to `0`, no memory containers can be created. + +### Setting + +```yaml +plugins.ml_commons.max_memory_containers_per_user: 100 +``` + +### Values + +- Default value: `100` +- Value range: [0, 10,000] + +## Set maximum memories per container + +Controls the maximum number of memories that can be stored in a single memory container. When set to `0`, no memories can be added to any container. + +### Setting + +```yaml +plugins.ml_commons.max_memories_per_container: 10000 +``` + +### Values + +- Default value: `10,000` +- Value range: [0, 1,000,000] + ## Enable RAG pipeline From f4d4bbf68066b668fff29c0cd74274c1f77de487 Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Fri, 10 Oct 2025 11:07:42 -0700 Subject: [PATCH 14/27] update path parameters Signed-off-by: Dhrubo Saha --- .../api/agentic-memory-apis/delete-memory-by-type.md | 8 ++++---- .../api/agentic-memory-apis/search-memories-by-type.md | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md index 8fa06b9e6c7..82c1585652e 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md @@ -20,11 +20,11 @@ DELETE /_plugins/_ml/memory_containers//memories///memories//_searc ## Path parameters -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | -| `type` | String | The type of memory: "sessions", "working", "long-term", or "history". Required. | +| Field | Data type | Required/Optional | Description | +|:----------------------| :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container. | +| `type` | String | Required | The type of memory: "sessions", "working", "long-term", or "history". | ## Request fields From 1340f345206436ba19a49deab549464de06d5968 Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Fri, 10 Oct 2025 18:03:25 -0700 Subject: [PATCH 15/27] addressed comments Signed-off-by: Dhrubo Saha --- .../api/agentic-memory-apis/add-memory.md | 26 +++---- .../create-memory-container.md | 44 ++++++++++- .../delete-memory-by-type.md | 76 +++++++++++++++++++ .../delete-memory-container.md | 3 - .../agentic-memory-apis/get-memory-by-type.md | 10 +-- .../update-memory-by-type.md | 41 +++++----- .../update-memory-container.md | 57 ++++++++++++-- _ml-commons-plugin/cluster-settings.md | 31 -------- 8 files changed, 207 insertions(+), 81 deletions(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 4fdd8d9e185..1756edaed73 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -17,9 +17,7 @@ Use this API to add an agentic memory to a [memory container]({{site.url}}{{site - **data** -- Stores extra messages, structured, non-conversational data such as agent state, checkpoints, or reference information. -- **infer=true** -- Use large language model (LLM) to extract key information or knowledge from the messages. - -- **infer=false** -- Only store raw messages and data in working memory. +- **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. Once an agentic memory is created, you'll provide its `memory_id` to other APIs. @@ -33,16 +31,16 @@ POST /_plugins/_ml/memory_containers/{memory_container_id}/memories The following table lists the available request body fields. -Field | Data type | Required/Optional | Description -:--- | :--- | :--- | :--- -`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`. -`structured_data` | Map | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. -`binary_data` | String | Optional | Binary data content encoded as base64 string for binary payloads. -`payload_type` | String | Required | The type of payload: `conversational` or `data`. -`namespace` | List | 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. -`metadata` | Map | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). -`tags` | List | Optional | Tags for categorizing and organizing memories. -`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. +Field | Data type | Required/Optional | Description +:--- |:---------------------| :--- | :--- +`messages` | List | Conditional | A list of messages for conversational payload. Each message requires `content`. Required for `payload_type` of `conversational`. +`structured_data` | Map | Conditional | Structured data content for data memory. Required for `payload_type` of `data`. +`binary_data` | String | Optional | Binary data content encoded as base64 string for binary payloads. +`payload_type` | String | Required | The type of payload: `conversational` or `data`. +`namespace` | List | 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. +`metadata` | Map | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). +`tags` | List | Optional | Tags for categorizing and organizing memories. +`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. ## Example requests @@ -107,8 +105,6 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories } ``` -### Trace data memory - Store agent trace data in working memory: ```json diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index ce919dd90df..4ad6e893c63 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -139,10 +139,10 @@ POST /_plugins/_ml/memory_containers/_create The following table lists the available request body fields. Field | Data type | Required/Optional | Description -:--- | :--- | :--- | :--- -`name` | String | Required | The name of the memory container. -`description` | String | Optional | The description of the memory container. -`configuration` | Object | Required | The memory container configuration. See [the `configuration` object](#the-configuration-object). +:--- | :--- |:------------------| :--- +`name` | String | Required | The name of the memory container. +`description` | String | Optional | The description of the memory container. +`configuration` | Object | Optional | The memory container configuration. See [the `configuration` object](#the-configuration-object). ### The configuration object @@ -156,9 +156,44 @@ Field | Data type | Required/Optional | Description `llm_id` | String | Optional | The LLM model ID for processing and inference. `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. `use_system_index` | Boolean | Optional | Whether to use system indices. Default is `true`. +`disable_history` | Boolean | Optional | if disabled no history will be persisted. Default is `false`, so history will be persisted by default. +`disable_session` | Boolean | Optional | if disabled no session will be persisted. Default is `true`, so session will not be persisted by default. +`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. +`index_settings` | Map | Optional | Customer can also provide the index settings. See [the `index settings` array](#the-index-settings). `strategies` | Array | Optional | Array of memory processing strategies. See [the `strategies` array](#the-strategies-array). `parameters` | Object | Optional | Global parameters for the memory container. See [the `parameters` object](#the-parameters-object). +### The index settings + +Example of index settings + + "index_settings": { + "session_index" : { + "index": { + "number_of_shards": "2", + "number_of_replicas": "2" + } + }, + "short_term_memory_index" : { + "index": { + "number_of_shards": "2", + "number_of_replicas": "2" + } + }, + "long_term_memory_index" : { + "index": { + "number_of_shards": "2", + "number_of_replicas": "2" + } + }, + "long_term_memory_history_index" : { + "index": { + "number_of_shards": "2", + "number_of_replicas": "2" + } + } + } + ### The strategies array Each strategy in the `strategies` array supports the following fields. @@ -168,6 +203,7 @@ Field | Data type | Required/Optional | Description `type` | String | Required | The strategy type: `SEMANTIC`, `USER_PREFERENCE`, or `SUMMARY`. `namespace` | Array | Required | Array of namespace dimensions for organizing memories (e.g., `["user_id"]`, `["agent_id", "session_id"]`). `configuration` | Map | Optional | Strategy-specific configuration. See [the strategy `configuration` object](#the-strategy-configuration-object). +`enabled` | boolean | Optional | To enable the Strategy in the memory container. Default is True. ### The strategy configuration object diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md index 82c1585652e..dc466944783 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md @@ -76,3 +76,79 @@ DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMx | `_id` | String | The ID of the deleted memory. | | `_version` | Integer | The version number after deletion. | | `_shards` | Object | Information about the shards involved in the operation. | + +## Delete memory by query + +You can also delete multiple memories using a query to match specific criteria. + +### Path and HTTP methods + +```json +POST /_plugins/_ml/memory_containers//memories//_delete_by_query +``` + +### Path parameters + +| Field | Data type | Required/Optional | Description | +|:----------------------| :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container. | +| `type` | String | Required | The type of memory: "sessions", "working", "long-term", or "history". | + +### Request body + +The request body should contain a query to match the memories you want to delete. + +### Example request + +```json +POST /_plugins/_ml/memory_containers/{{container_id_user1}}/memories/working/_delete_by_query +{ + "query": { + "match": { + "owner_id": "admin" + } + } +} +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "took": 159, + "timed_out": false, + "total": 6, + "updated": 0, + "created": 0, + "deleted": 6, + "batches": 1, + "version_conflicts": 0, + "noops": 0, + "retries": { + "bulk": 0, + "search": 0 + }, + "throttled_millis": 0, + "requests_per_second": -1.0, + "throttled_until_millis": 0, + "failures": [] +} +``` + +### Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `took` | Integer | The time in milliseconds it took to execute the request. | +| `timed_out` | Boolean | Whether the request timed out. | +| `total` | Integer | The total number of documents processed. | +| `deleted` | Integer | The number of documents deleted. | +| `batches` | Integer | The number of batches processed. | +| `version_conflicts` | Integer | The number of version conflicts encountered. | +| `noops` | Integer | The number of no-operation updates. | +| `retries` | Object | Information about bulk and search retries. | +| `throttled_millis` | Integer | The time in milliseconds the request was throttled. | +| `requests_per_second` | Float | The number of requests processed per second. | +| `throttled_until_millis` | Integer | The time in milliseconds until throttling is lifted. | +| `failures` | Array | Any failures that occurred during the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md index f23f3249463..1b243d1ee7f 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md @@ -10,9 +10,6 @@ nav_order: 30 **Introduced 3.2** {: .label .label-purple } -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/). -{: .warning} - Use this API to delete a memory container by its ID. ## Endpoint diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md index df474bc54d7..6597b973116 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md @@ -20,11 +20,11 @@ GET /_plugins/_ml/memory_containers//memories// ## Path parameters -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | -| `type` | String | The type of memory: "sessions", "working", "long-term", or "history". Required. | -| `id` | String | The ID of the memory to retrieve. Required. | +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container. | +| `type` | String | Required | The type of memory: "sessions", "working", "long-term", or "history". | +| `id` | String | Required | The ID of the memory to retrieve. | ## Example requests diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md index 10f182ff846..2277d4844cc 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md @@ -20,11 +20,11 @@ PUT /_plugins/_ml/memory_containers//memories// ## Path parameters -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. Required. | -| `type` | String | The type of memory: "sessions", "working", or "long-term". Required. Note: History memory cannot be updated. | -| `id` | String | The ID of the memory to update. Required. | +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container. | +| `type` | String | Required | The type of memory: "sessions", "working", or "long-term". Note: History memory cannot be updated. | +| `id` | String | Required | The ID of the memory to update. | ## Request fields @@ -32,26 +32,31 @@ The request fields vary depending on the memory type being updated: ### For session memory -| Field | Data type | Description | -| :--- | :--- | :--- | -| `additional_info` | Object | Additional metadata to associate with the session. Optional. | +| Field | Data type | Description | +|:-----------|:----------------------| :--- | +| `summary` | String | The summary of the session. +| `metadata` | Map | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). +| `agents` | Map | Additional information about agents. +| `additional_info` | Map | Additional information about memory + + ### For working memory -| Field | Data type | Description | -| :--- | :--- | :--- | +| Field | Data type | Description | +| :--- | :--- |:-----------------------------------------------------------------| | `messages` | Array | Updated conversation messages (for conversation type). Optional. | -| `structured_data` | Object | Updated structured data content (for data type). Optional. | -| `tags` | Object | Updated tags for categorization. Optional. | -| `additional_info` | Object | Additional metadata. Optional. | +| `structured_data` | Object | Updated structured data content (for data type). Optional. | +| `binary_data` | Object | Updated binary data content (for data type). Optional. | +| `tags` | Object | Updated tags for categorization. Optional. | +| `metadata` | Map | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). ### For long-term memory -| Field | Data type | Description | -| :--- | :--- | :--- | -| `memory` | String | The updated memory content. Optional. | -| `tags` | Object | Updated tags for categorization. Optional. | -| `additional_info` | Object | Additional metadata. Optional. | +| Field | Data type | Description | +| :--- | :--- |:-----------------------------------------------------------------------------------------------------------| +| `memory` | String | The updated memory content. Optional. Updating memory field will automatically update the memory embedding | +| `tags` | Object | Updated tags for categorization. Optional. | ## Example requests diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md index 5b4fa548f95..9f2390ba982 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md @@ -10,7 +10,7 @@ nav_order: 15 **Introduced 3.3** {: .label .label-purple } -Use this API to update an existing memory container's properties such as name and description. +Use this API to update an existing memory container's properties such as name, description, configuration, and access permissions. ## Path and HTTP methods @@ -20,9 +20,9 @@ PUT /_plugins/_ml/memory_containers/ ## Path parameters -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container to update. Required. | +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container to update. | ## Request fields @@ -30,13 +30,60 @@ PUT /_plugins/_ml/memory_containers/ | :--- | :--- | :--- | :--- | | `name` | String | Optional | The updated name of the memory container. | | `description` | String | Optional | The updated description of the memory container. | +| `configuration` | Object | Optional | Configuration object containing strategies and embedding settings. | + +### Configuration object fields + +| Field | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `llm_id` | String | Optional | The large language model ID to use to extract facts. | +| `strategies` | Array | Optional | Array of strategy objects for memory processing. | +| `embedding_model_id` | String | Optional | The embedding model ID. Can only be updated if no long-term memory index exists. | +| `embedding_model_type` | String | Optional | The embedding model type. Can only be updated if no long-term memory index exists. | +| `embedding_dimension` | Integer | Optional | The embedding dimension. Can only be updated if no long-term memory index exists. | + +## Update behavior + +### Strategy updates +- **Update existing strategy**: Include the strategy `id` to update that specific strategy. +- **Create new strategy**: Specify a strategy without an `id` to create a new strategy. + +### Backend roles updates +- Adding new `backend_roles` grants new users read or write access with those roles. +- The `backend_roles` field is updated by overwriting, so include original roles if you want to keep them. + +### Namespace updates +- The `namespace` field inside strategies is updated by overwriting. +- Include the original namespace if you want to keep it. + +### Embedding model restrictions +- 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. +- Once a long-term memory index with the specified `index_prefix` is created, these embedding fields cannot be updated. + ## Example request ```json PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU { - "name": "opensearch-agents-memory" + "name": "opensearch-agents-memory", + "description": "Updated memory container for OpenSearch agents", + "backend_roles": ["admin", "ml_user"], + "configuration": { + "strategies": [ + { + "id": "existing_strategy_id", + "type": "summarization", + "namespace": "updated_namespace" + }, + { + "type": "keyword_extraction" + } + ], + "embedding_model_id": "new_embedding_model", + "embedding_model_type": "dense", + "embedding_dimension": 768 + } } ``` {% include copy-curl.html %} diff --git a/_ml-commons-plugin/cluster-settings.md b/_ml-commons-plugin/cluster-settings.md index 16d9df1b6db..26e8f94a522 100644 --- a/_ml-commons-plugin/cluster-settings.md +++ b/_ml-commons-plugin/cluster-settings.md @@ -509,37 +509,6 @@ plugins.ml_commons.agentic_memory_enabled: true - Default value: `true` - Valid values: `false`, `true` -## Set maximum memory containers per user - -Controls the maximum number of memory containers that can be created per user. When set to `0`, no memory containers can be created. - -### Setting - -```yaml -plugins.ml_commons.max_memory_containers_per_user: 100 -``` - -### Values - -- Default value: `100` -- Value range: [0, 10,000] - -## Set maximum memories per container - -Controls the maximum number of memories that can be stored in a single memory container. When set to `0`, no memories can be added to any container. - -### Setting - -```yaml -plugins.ml_commons.max_memories_per_container: 10000 -``` - -### Values - -- Default value: `10,000` -- Value range: [0, 1,000,000] - - ## Enable RAG pipeline When set to `true`, this setting enables the search processors for retrieval-augmented generation (RAG). RAG enhances query results by generating responses using relevant information from memory and previous conversations. From b18236c7b4a8f389df07932f44a8818366485dd4 Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Sun, 12 Oct 2025 13:35:09 -0700 Subject: [PATCH 16/27] addressed comments Signed-off-by: Dhrubo Saha --- .../api/agentic-memory-apis/add-memory.md | 20 +++++++++---------- .../create-memory-container.md | 9 ++++----- 2 files changed, 13 insertions(+), 16 deletions(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 1756edaed73..605aef9444e 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -17,8 +17,6 @@ Use this API to add an agentic memory to a [memory container]({{site.url}}{{site - **data** -- Stores extra messages, structured, non-conversational data such as agent state, checkpoints, or reference information. -- **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. - Once an agentic memory is created, you'll provide its `memory_id` to other APIs. ## Endpoint @@ -32,15 +30,15 @@ POST /_plugins/_ml/memory_containers/{memory_container_id}/memories The following table lists the available request body fields. Field | Data type | Required/Optional | Description -:--- |:---------------------| :--- | :--- -`messages` | List | Conditional | A list of messages for conversational payload. Each message requires `content`. Required for `payload_type` of `conversational`. -`structured_data` | Map | Conditional | Structured data content for data memory. Required for `payload_type` of `data`. -`binary_data` | String | Optional | Binary data content encoded as base64 string for binary payloads. -`payload_type` | String | Required | The type of payload: `conversational` or `data`. -`namespace` | List | 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. -`metadata` | Map | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). -`tags` | List | Optional | Tags for categorizing and organizing memories. -`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. +:--- |:---------------------|:------------------| :--- +`messages` | List | Conditional | A list of messages for conversational payload. Each message requires `content`. Required for `payload_type` of `conversational`. +`structured_data` | Map | Optional | Structured data content for data memory. +`binary_data` | String | Optional | Binary data content encoded as base64 string for binary payloads. +`payload_type` | String | Optional | The type of payload: `conversational` or `data`. Default is `conversational` +`namespace` | List | 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. +`metadata` | Map | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). +`tags` | List | Optional | Tags for categorizing and organizing memories. +`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. ## Example requests diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index 4ad6e893c63..8bd0ab616be 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -13,7 +13,7 @@ nav_order: 10 Use this API to create a memory container to hold agentic memories. The container can have two model types associated with it: - 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. -- 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. +- 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. Long term memory requires both an LLM model and embedding model to be configured. **Note**: LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is configured for Bedrock Converse API format (`"$.output.message.content[0].text"`). @@ -79,7 +79,6 @@ POST /_plugins/_ml/models/_register ### LLM -Currently, agentic memory supports only the Anthropic Claude model for LLM capabilities. Starting with OpenSearch 3.3, this feature will be generally available and will include support for additional LLM providers, such as OpenAI. To register an Anthropic Claude model, send the following request: @@ -90,7 +89,7 @@ POST /_plugins/_ml/models/_register "function_name": "remote", "description": "test model", "connector": { - "name": "Amazon Bedrock Connector: embedding", + "name": "Amazon Bedrock Connector: Chat", "description": "The connector to bedrock Claude 3.7 sonnet model", "version": 1, "protocol": "aws_sigv4", @@ -114,8 +113,8 @@ POST /_plugins/_ml/models/_register "headers": { "content-type": "application/json" }, - "url": "https://bedrock-runtime.${parameters.region}.amazonaws.com/model/${parameters.model}/invoke", - "request_body": """{ "system": "${parameters.system_prompt}", "anthropic_version": "${parameters.anthropic_version}", "max_tokens": ${parameters.max_tokens}, "temperature": ${parameters.temperature}, "messages": ${parameters.messages} }""" + "url": "https://bedrock-runtime.${parameters.region}.amazonaws.com/model/${parameters.model}/converse", + "request_body": "{ \"anthropic_version\": \"${parameters.anthropic_version}\", \"max_tokens\": ${parameters.max_tokens}, \"temperature\": ${parameters.temperature}, \"system\": [{\"text\": \"${parameters.system_prompt}\"}], \"messages\": [ { \"role\": \"user\", \"content\": [ {\"text\": \"${parameters.user_prompt}\" }] }]}" } ] } From 0a258d2b45b6e1ba520a26c68ffb52b0948add5b Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 13 Oct 2025 11:03:37 -0400 Subject: [PATCH 17/27] Resolve merge conflicts Signed-off-by: Fanit Kolchina --- .../api/agentic-memory-apis/add-memory.md | 90 ++++---- .../create-memory-container.md | 60 +++--- .../delete-memory-by-type.md | 154 ------------- .../delete-memory-container.md | 27 ++- .../api/agentic-memory-apis/delete-memory.md | 99 ++++++++- .../agentic-memory-apis/get-memory-by-type.md | 204 ------------------ .../get-memory-container.md | 10 +- .../api/agentic-memory-apis/index.md | 63 +++++- .../search-memories-by-type.md | 192 ----------------- .../search-memory-container.md | 16 +- .../update-memory-by-type.md | 123 ----------- .../update-memory-container.md | 8 +- .../api/agentic-memory-apis/update-memory.md | 19 +- 13 files changed, 278 insertions(+), 787 deletions(-) delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md delete mode 100644 _ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 605aef9444e..f0ddb0add01 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -1,48 +1,50 @@ --- layout: default title: Add agentic memory -parent: Agentic Memory APIs +parent: Agentic memory APIs grand_parent: ML Commons APIs nav_order: 40 --- # Add Agentic Memory API -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } -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 provide memory payload in two types: +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 specify different [payload types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#payload-types) and control [inference mode]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#inference-mode) for how OpenSearch processes the memory. -- **conversational** -- Stores conversational messages between users and assistants. +Once an agentic memory is created, provide its `memory_id` to other APIs. -- **data** -- Stores extra messages, structured, non-conversational data such as agent state, checkpoints, or reference information. - -Once an agentic memory is created, you'll provide its `memory_id` to other APIs. - -## Endpoint +## Endpoints ```json -POST /_plugins/_ml/memory_containers/{memory_container_id}/memories +POST /_plugins/_ml/memory_containers//memories ``` +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container to add the memory to. | + ## Request body fields The following table lists the available request body fields. -Field | Data type | Required/Optional | Description -:--- |:---------------------|:------------------| :--- -`messages` | List | Conditional | A list of messages for conversational payload. Each message requires `content`. Required for `payload_type` of `conversational`. -`structured_data` | Map | Optional | Structured data content for data memory. -`binary_data` | String | Optional | Binary data content encoded as base64 string for binary payloads. -`payload_type` | String | Optional | The type of payload: `conversational` or `data`. Default is `conversational` -`namespace` | List | 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. -`metadata` | Map | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). -`tags` | List | Optional | Tags for categorizing and organizing memories. -`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. +Field | Data type | Required/Optional | Description +:--- | :--- | :--- | :--- +`messages` | Array | Conditional | A list of messages for a `conversational` payload. Each message requires a `content` field and may include a `role` (commonly, `user` or `assistant`) when `infer` is set to `true`. Required when `payload_type` is `conversational`. +`structured_data` | Object | Conditional | Structured data content for data memory. Required when `payload_type` is `data`. +`binary_data` | String | Optional | Binary data content encoded as a Base64 string for binary payloads. +`payload_type` | String | Required | The type of payload. Valid values are `conversational` or `data`. See [Payload types](#payload-types). +`namespace` | Object | Optional | The namespace context for organizing memories (for example, `user_id`, `session_id`, or `agent_id`). If `session_id` is not specified in the `namespace` field, a new session with a new session ID is created. +`metadata` | Object | Optional | Additional metadata for the memory (for example, `status`, `branch`, or custom fields). +`tags` | Object | Optional | Tags for categorizing and organizing memories. +`infer` | Boolean | Optional | Whether to use an 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 a memory. See [Inference mode](#inference-mode). -## Example requests - -### Conversational payload +## Example request: Conversational payload ```json POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories @@ -74,10 +76,20 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "payload_type": "conversational" } ``` +{% include copy-curl.html %} -### Data payload +## Example response: Conversation memory -Store agent state in working memory: +```json +{ + "session_id": "XSEuiJkBeh2gPPwzjYVh", + "working_memory_id": "XyEuiJkBeh2gPPwzjYWM" +} +``` + +## Example request: Data payload + +To store agent state in working memory, send the following request: ```json POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories @@ -102,8 +114,19 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "payload_type": "data" } ``` +{% include copy-curl.html %} -Store agent trace data in working memory: +## Example response: Data memory + +```json +{ + "working_memory_id": "Z8xeTpkBvwXRq366l0iA" +} +``` + +### Trace data memory + +To store agent trace data in working memory, send the following request: ```json POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories @@ -143,18 +166,7 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories ``` {% include copy-curl.html %} -## Example responses - -### Conversation memory response - -```json -{ - "session_id": "XSEuiJkBeh2gPPwzjYVh", - "working_memory_id": "XyEuiJkBeh2gPPwzjYWM" -} -``` - -### Data memory response +## Example response: Trace memory ```json { @@ -168,5 +180,5 @@ The following table lists all response body fields. | Field | Data type | Description | | :-------------- | :-------- | :------------------------------------------------------------------------------------------------ | -| `session_id` | String | The session ID associated with the memory (returned for conversation memory when a session is created or used). | +| `session_id` | String | The session ID associated with the memory (returned for `conversation` memory when a session is created or used). | | `working_memory_id` | String | The unique identifier for the created working memory entry. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index 40c1a5822af..0d547ac0833 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -1,31 +1,34 @@ --- layout: default title: Create memory container -parent: Agentic Memory APIs +parent: Agentic memory APIs grand_parent: ML Commons APIs nav_order: 10 --- # Create Memory Container API -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } -Use this API to create a memory container to hold agentic memories. The container can have two model types associated with it: +Use this API to create a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#memory-containers) to hold agentic memories. The container can have two model types associated with it: - 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. - 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. Long term memory requires both an LLM model and embedding model to be configured. **Note**: LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is configured for Bedrock Converse API format (`"$.output.message.content[0].text"`). -**Note**: LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is configured for Bedrock Converse API format (`"$.output.message.content[0].text"`). +For more information, see [Integrating ML models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/integrating-ml-models/). + +LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). +{: .note} -Once a memory container is created, you'll provide its `memory_container_id` to other APIs. +Once a memory container is created, provide its `memory_container_id` to other APIs. ## Prerequisites If you want to use one of the model types to process memories, register the models in OpenSearch. -### Embedding model +### Embedding model Register either a local or externally hosted embedding model. OpenSearch supports text embedding and sparse encoding models. @@ -79,7 +82,7 @@ POST /_plugins/_ml/models/_register ``` {% include copy-curl.html %} -### LLM +### LLM To register an Anthropic Claude model, send the following request: @@ -129,7 +132,7 @@ The `system_prompt` parameter is required for Claude models. For more information about using externally hosted models, see [Connecting to externally hosted models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/index/). -## Endpoint +## Endpoints ```json POST /_plugins/_ml/memory_containers/_create @@ -140,10 +143,10 @@ POST /_plugins/_ml/memory_containers/_create The following table lists the available request body fields. Field | Data type | Required/Optional | Description -:--- | :--- |:------------------| :--- -`name` | String | Required | The name of the memory container. -`description` | String | Optional | The description of the memory container. -`configuration` | Object | Optional | The memory container configuration. See [the `configuration` object](#the-configuration-object). +:--- | :--- | :--- | :--- +`name` | String | Required | The name of the memory container. +`description` | String | Optional | The description of the memory container. +`configuration` | Object | Required | The memory container configuration. See [The `configuration` object](#the-configuration-object). ### The configuration object @@ -155,14 +158,14 @@ Field | Data type | Required/Optional | Description `embedding_model_id` | String | Optional | The embedding model ID. `embedding_dimension` | Integer | Optional | The dimension of the embedding model. Required if `embedding_model_type` is `TEXT_EMBEDDING`. `llm_id` | String | Optional | The LLM model ID for processing and inference. -`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. -`use_system_index` | Boolean | Optional | Whether to use system indices. Default is `true`. +`index_prefix` | String | Optional | A custom prefix for memory indexes. If not specified, a default prefix is used: `default` when `use_system_index` is `true`, or an 8-character random UUID when `use_system_index` is `false`. +`use_system_index` | Boolean | Optional | Whether to use system indexes. Default is `true`. `disable_history` | Boolean | Optional | if disabled no history will be persisted. Default is `false`, so history will be persisted by default. `disable_session` | Boolean | Optional | if disabled no session will be persisted. Default is `true`, so session will not be persisted by default. `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. `index_settings` | Map | Optional | Customer can also provide the index settings. See [the `index settings` array](#the-index-settings). -`strategies` | Array | Optional | Array of memory processing strategies. See [the `strategies` array](#the-strategies-array). -`parameters` | Object | Optional | Global parameters for the memory container. See [the `parameters` object](#the-parameters-object). +`strategies` | Array | Optional | An array of [memory processing strategies]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#memory-processing-strategies). See [The `strategies` array](#the-strategies-array). +`parameters` | Object | Optional | Global parameters for the memory container. See [The `parameters` object](#the-parameters-object). ### The index settings @@ -201,28 +204,28 @@ Each strategy in the `strategies` array supports the following fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`type` | String | Required | The strategy type: `SEMANTIC`, `USER_PREFERENCE`, or `SUMMARY`. -`namespace` | Array | Required | Array of namespace dimensions for organizing memories (e.g., `["user_id"]`, `["agent_id", "session_id"]`). -`configuration` | Map | Optional | Strategy-specific configuration. See [the strategy `configuration` object](#the-strategy-configuration-object). -`enabled` | boolean | Optional | To enable the Strategy in the memory container. Default is True. +`type` | String | Required | The strategy type. Valid values are `SEMANTIC`, `USER_PREFERENCE`, and `SUMMARY`. +`namespace` | Array | Required | An array of namespace dimensions for organizing memories (for example, `["user_id"]` or `["agent_id", "session_id"]`). +`configuration` | Object | Optional | Strategy-specific configuration. See [The strategy `configuration` object](#the-strategy-configuration-object). +`enabled` | Boolean | Optional | Whether to enable the strategy in the memory container. Default is `true`. ### The strategy configuration object +The strategy `configuration` object supports the following fields. + Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`llm_result_path` | String | Optional | JSONPath to extract LLM results. Default is `"$.output.message.content[0].text"` for Bedrock Converse API format. -`system_prompt` | String | Optional | Custom system prompt to override the default strategy prompt. -`llm_id` | String | Optional | LLM model ID for this specific strategy, overrides the global LLM setting. +`llm_result_path` | String | Optional | A JSONPath for extracting LLM results from responses. Default is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). +`system_prompt` | String | Optional | A custom system prompt to override the default strategy prompt. +`llm_id` | String | Optional | The LLM model ID for this strategy. Overrides the global LLM setting. ### The parameters object Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`llm_result_path` | String | Optional | Global JSONPath for extracting LLM results from responses. Default is `"$.output.message.content[0].text"` for Bedrock Converse API format. - -## Example requests +`llm_result_path` | String | Optional | A global JSONPath for extracting LLM results from responses. Default is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). -### Basic memory container +## Example request: Basic memory container ```json POST /_plugins/_ml/memory_containers/_create @@ -243,8 +246,9 @@ POST /_plugins/_ml/memory_containers/_create } } ``` +{% include copy-curl.html %} -### Advanced memory container with multiple strategies +### Example request: Advanced memory container with multiple strategies ```json POST /_plugins/_ml/memory_containers/_create diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md deleted file mode 100644 index dc466944783..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -layout: default -title: Delete memory by type and ID -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 53 ---- - -# Delete memory by type and ID -**Introduced 3.3** -{: .label .label-purple } - -Use this API to delete a specific memory by its type and ID. This unified API supports deleting all memory types: session, working, long-term, and history memory data. - -## Path and HTTP methods - -```json -DELETE /_plugins/_ml/memory_containers//memories// -``` - -## Path parameters - -| Field | Data type | Required/Optional | Description | -|:----------------------| :--- | :--- | :--- | -| `memory_container_id` | String | Required | The ID of the memory container. | -| `type` | String | Required | The type of memory: "sessions", "working", "long-term", or "history". | -| `id` | String | Required | The ID of the memory to delete. | - -## Example requests - -### Delete working memory - -```json -DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM -``` - -### Delete long-term memory - -```json -DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz -``` - -### Delete session - -```json -DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/CcxjTpkBvwXRq366A1aE -``` - -### Delete memory history - -```json -DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTpkBvwXRq366hmAU -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "result": "deleted", - "_id": "XyEuiJkBeh2gPPwzjYWM", - "_version": 2, - "_shards": { - "total": 2, - "successful": 1, - "failed": 0 - } -} -``` - -## Response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `result` | String | The result of the delete operation. | -| `_id` | String | The ID of the deleted memory. | -| `_version` | Integer | The version number after deletion. | -| `_shards` | Object | Information about the shards involved in the operation. | - -## Delete memory by query - -You can also delete multiple memories using a query to match specific criteria. - -### Path and HTTP methods - -```json -POST /_plugins/_ml/memory_containers//memories//_delete_by_query -``` - -### Path parameters - -| Field | Data type | Required/Optional | Description | -|:----------------------| :--- | :--- | :--- | -| `memory_container_id` | String | Required | The ID of the memory container. | -| `type` | String | Required | The type of memory: "sessions", "working", "long-term", or "history". | - -### Request body - -The request body should contain a query to match the memories you want to delete. - -### Example request - -```json -POST /_plugins/_ml/memory_containers/{{container_id_user1}}/memories/working/_delete_by_query -{ - "query": { - "match": { - "owner_id": "admin" - } - } -} -``` -{% include copy-curl.html %} - -### Example response - -```json -{ - "took": 159, - "timed_out": false, - "total": 6, - "updated": 0, - "created": 0, - "deleted": 6, - "batches": 1, - "version_conflicts": 0, - "noops": 0, - "retries": { - "bulk": 0, - "search": 0 - }, - "throttled_millis": 0, - "requests_per_second": -1.0, - "throttled_until_millis": 0, - "failures": [] -} -``` - -### Response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `took` | Integer | The time in milliseconds it took to execute the request. | -| `timed_out` | Boolean | Whether the request timed out. | -| `total` | Integer | The total number of documents processed. | -| `deleted` | Integer | The number of documents deleted. | -| `batches` | Integer | The number of batches processed. | -| `version_conflicts` | Integer | The number of version conflicts encountered. | -| `noops` | Integer | The number of no-operation updates. | -| `retries` | Object | Information about bulk and search retries. | -| `throttled_millis` | Integer | The time in milliseconds the request was throttled. | -| `requests_per_second` | Float | The number of requests processed per second. | -| `throttled_until_millis` | Integer | The time in milliseconds until throttling is lifted. | -| `failures` | Array | Any failures that occurred during the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md index 1b243d1ee7f..4e5ca47ef08 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md @@ -1,21 +1,25 @@ --- layout: default title: Delete memory container -parent: Agentic Memory APIs +parent: Agentic memory APIs grand_parent: ML Commons APIs nav_order: 30 --- # Delete Memory Container API -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } +<<<<<<< Updated upstream +======= + +>>>>>>> Stashed changes Use this API to delete a memory container by its ID. -## Endpoint +## Endpoints ```json -DELETE /_plugins/_ml/memory_containers/{memory_container_id} +DELETE /_plugins/_ml/memory_containers/ ``` ## Example request @@ -42,4 +46,17 @@ DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN "_seq_no": 6, "_primary_term": 1 } -``` \ No newline at end of file +``` + +## Response fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the delete operation. | +| `_id` | String | The ID of the deleted memory container. | +| `_version` | Integer | The version number after deletion. | +| `_shards` | Object | Information about the shards involved in the operation. | +| `_seq_no` | Long | The sequence number assigned to the delete operation. | +| `_primary_term` | Long | The primary term of the index. | \ No newline at end of file diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md index fc6932450af..1f6aa8c435e 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md @@ -10,15 +10,19 @@ nav_order: 53 **Introduced 3.3** {: .label .label-purple } -Use this API to delete a specific memory by its type and ID. This unified API supports deleting memories of any [memory type]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#memory-types): `sessions`, `working`, `long-term`, or `history`. +Use this API to delete a specific memory by its type and ID or to delete memories matching a query. This unified API supports deleting memories of any [memory type]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#memory-types): `sessions`, `working`, `long-term`, or `history`. -## Endpoints +## Delete a memory by type or ID + +Use this API to delete a memory by type or ID. + +### Endpoints ```json DELETE /_plugins/_ml/memory_containers//memories// ``` -## Path parameters +### Path parameters The following table lists the available path parameters. @@ -28,35 +32,35 @@ The following table lists the available path parameters. | `type` | String | Required | The type of memory to delete. Valid values are `sessions`, `working`, `long-term`, and `history`. | | `id` | String | Required | The ID of the specific memory to delete. | -## Example request: Delete a working memory +### Example request: Delete a working memory ```json DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM ``` {% include copy-curl.html %} -## Example request: Delete a long-term memory +### Example request: Delete a long-term memory ```json DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz ``` {% include copy-curl.html %} -## Example request: Delete a sessions memory +### Example request: Delete a sessions memory ```json DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/CcxjTpkBvwXRq366A1aE ``` {% include copy-curl.html %} -## Example request: Delete a history memory +### Example request: Delete a history memory ```json DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTpkBvwXRq366hmAU ``` {% include copy-curl.html %} -## Example response +### Example response ```json { @@ -71,7 +75,7 @@ DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMx } ``` -## Response fields +### Response fields The following table lists all response body fields. @@ -81,3 +85,80 @@ The following table lists all response body fields. | `_id` | String | The ID of the deleted memory. | | `_version` | Integer | The version number after deletion. | | `_shards` | Object | Information about the shards involved in the operation. | + +## Delete memories by query + +Use this API to delete multiple memories using a query to match specific criteria. + +### Endpoints + +```json +POST /_plugins/_ml/memory_containers//memories//_delete_by_query +``` + +### Path parameters + +| Field | Data type | Required/Optional | Description | +|:----------------------| :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container from which to delete the memory. | +| `type` | String | Required | The type of memory to delete. Valid values are `sessions`, `working`, `long-term`, and `history`. | + +### Request body fields + +The request body must contain a query to match the memories you want to delete. + +### Example request + +```json +POST /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_delete_by_query +{ + "query": { + "match": { + "owner_id": "admin" + } + } +} +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "took": 159, + "timed_out": false, + "total": 6, + "updated": 0, + "created": 0, + "deleted": 6, + "batches": 1, + "version_conflicts": 0, + "noops": 0, + "retries": { + "bulk": 0, + "search": 0 + }, + "throttled_millis": 0, + "requests_per_second": -1.0, + "throttled_until_millis": 0, + "failures": [] +} +``` + +### Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `took` | Integer | The time, in milliseconds, it took to execute the request. | +| `timed_out` | Boolean | Whether the request timed out. | +| `total` | Integer | The total number of documents processed. | +| `deleted` | Integer | The number of documents deleted. | +| `batches` | Integer | The number of batches processed. | +| `version_conflicts` | Integer | The number of version conflicts encountered. | +| `noops` | Integer | The number of no-operation updates. | +| `retries` | Object | Information about bulk and search retries. | +| `throttled_millis` | Integer | The time, in milliseconds, the request was throttled. | +| `requests_per_second` | Float | The number of requests processed per second. | +| `throttled_until_millis` | Integer | The time, in milliseconds, until throttling is lifted. | +| `failures` | Array | Any failures that occurred during the operation. | + diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md deleted file mode 100644 index 6597b973116..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -layout: default -title: Get memory by type and ID -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 51 ---- - -# Get memory by type and ID -**Introduced 3.3** -{: .label .label-purple } - -Use this API to retrieve a specific memory by its type and ID. This unified API supports four types of memory data: session, working, long-term, and history. - -## Path and HTTP methods - -```json -GET /_plugins/_ml/memory_containers//memories// -``` - -## Path parameters - -| Parameter | Data type | Required/Optional | Description | -| :--- | :--- | :--- | :--- | -| `memory_container_id` | String | Required | The ID of the memory container. | -| `type` | String | Required | The type of memory: "sessions", "working", "long-term", or "history". | -| `id` | String | Required | The ID of the memory to retrieve. | - -## Example requests - -### Get working memory - -```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM -``` - -### Get long-term memory - -```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz -``` - -### Get session - -```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/CcxjTpkBvwXRq366A1aE -``` - -### Get memory history - -```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTpkBvwXRq366hmAU -``` -{% include copy-curl.html %} - -## Example responses - -### Working memory response - -```json -{ - "memory_container_id": "HudqiJkB1SltqOcZusVU", - "memory_type": "conversation", - "messages": [ - { - "role": "user", - "content_text": "I'm Bob, I really like swimming." - }, - { - "role": "assistant", - "content_text": "Cool, nice. Hope you enjoy your life." - } - ], - "namespace": { - "user_id": "bob", - "session_id": "S-dqiJkB1SltqOcZ1cYO" - }, - "metadata": { - "status": "checkpoint", - "branch": "{\"root_event_id\":\"228nadfs879mtgk\",\"branch_name\":\"high\"}" - }, - "infer": true, - "tags": { - "topic": "personal info" - }, - "created_time": 1758930326804, - "last_updated_time": 1758930326804 -} -``` - -### Long-term memory response - -```json -{ - "memory": "Kubernetes RBAC permission issues detected with CloudWatch agents experiencing persistent permission denials", - "strategy_type": "SUMMARY", - "tags": { - "agent_type": "chat_agent", - "conversation": "true" - }, - "namespace": { - "agent_id": "chat-agent" - }, - "namespace_size": 1, - "created_time": 1760052801773, - "last_updated_time": 1760052801773, - "memory_embedding": [0.018510794, 0.056366503, "..."], - "owner_id": "admin", - "strategy_id": "summary_96f04d97" -} -``` - -### Session response - -```json -{ - "memory_container_id": "HudqiJkB1SltqOcZusVU", - "namespace": { - "user_id": "bob" - }, - "created_time": "2025-09-15T17:18:55.881276939Z", - "last_updated_time": "2025-09-15T17:18:55.881276939Z" -} -``` - -### History response - -```json -{ - "owner_id": "admin", - "memory_container_id": "nrJBy5kByIxXWyhQjmqv", - "memory_id": "4bJMy5kByIxXWyhQvGr9", - "action": "ADD", - "after": { - "memory": "A comprehensive security investigation was performed across multiple data sources including 55 OpenSearch indices, 50 CloudTrail events, 22 VPC Flow logs, 38 WAF events, 74 CloudWatch log groups, active CloudWatch alarms, and OpenSearch cluster security configuration." - }, - "namespace": { - "agent_id": "chat-agent" - }, - "namespace_size": 1, - "tags": { - "agent_type": "chat_agent", - "conversation": "true" - }, - "created_time": 1760052428089 -} -``` - -## Response fields - -The response fields vary depending on the memory type: - -### Working memory response fields - -| Field | Data type | Description | -|:----------------------| :--- |:--------------------------------------------------------| -| `memory_container_id` | String | The ID of the memory container. | -| `payload_type` | String | The type of payload: "conversation" or "data". | -| `messages` | Array | Array of conversation messages (for conversation type). | -| `namespace` | Object | The namespace context for this memory. | -| `metadata` | Object | Additional metadata associated with the memory. | -| `tags` | Object | Associated tags for categorization. | -| `infer` | Boolean | Whether inference was enabled for this memory. | -| `created_time` | Long | Timestamp when the memory was created. | -| `last_updated_time` | Long | Timestamp when the memory was last updated. | - -### Long-term memory response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `memory` | String | The extracted long-term memory fact. | -| `strategy_type` | String | The type of memory strategy used (e.g., "SEMANTIC", "SUMMARY", "USER_PREFERENCE"). | -| `namespace` | Object | The namespace context for this memory. | -| `namespace_size` | Integer | The size of the namespace. | -| `tags` | Object | Associated tags for categorization. | -| `created_time` | Long | Timestamp when the memory was created. | -| `last_updated_time` | Long | Timestamp when the memory was last updated. | -| `memory_embedding` | Array | Vector embedding of the memory content (truncated in display). | -| `owner_id` | String | The owner of the memory. | -| `strategy_id` | String | The unique identifier for the strategy instance. | - -### Session response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container. | -| `namespace` | Object | The namespace context for this session. | -| `created_time` | String | ISO timestamp when the session was created. | -| `last_updated_time` | String | ISO timestamp when the session was last updated. | - -### History response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `owner_id` | String | The owner of the memory. | -| `memory_container_id` | String | The ID of the memory container. | -| `memory_id` | String | The ID of the affected memory. | -| `action` | String | The type of operation: "ADD", "UPDATE", or "DELETE". | -| `after` | Object | The memory content after the operation. | -| `before` | Object | The memory content before the operation (for UPDATE operations). | -| `namespace` | Object | The namespace context for this memory. | -| `namespace_size` | Integer | The size of the namespace. | -| `tags` | Object | Associated tags for categorization. | -| `created_time` | Long | Timestamp when the operation occurred. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-container.md index 33cad3b4f16..0521c33ba6e 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-container.md @@ -1,24 +1,22 @@ --- layout: default title: Get memory container -parent: Agentic Memory APIs +parent: Agentic memory APIs grand_parent: ML Commons APIs nav_order: 20 --- # Get Memory Container API -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } -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/). -{: .warning} Use this API to retrieve a memory container by its ID. -## Endpoint +## Endpoints ```json -GET /_plugins/_ml/memory_containers/{memory_container_id} +GET /_plugins/_ml/memory_containers/ ``` ## Example request diff --git a/_ml-commons-plugin/api/agentic-memory-apis/index.md b/_ml-commons-plugin/api/agentic-memory-apis/index.md index 9695a62a7d8..7f8448523a3 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/index.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/index.md @@ -1,6 +1,6 @@ --- layout: default -title: Agentic Memory APIs +title: Agentic memory APIs parent: ML Commons APIs has_children: true has_toc: false @@ -9,15 +9,60 @@ redirect_from: - /ml-commons-plugin/api/agentic-memory-apis/ --- -# Agentic Memory APIs -**Introduced 3.2** +# Agentic memory APIs +**Introduced 3.3** {: .label .label-purple } Agentic Memory APIs provide persistent memory management for AI agents. This enables agents to learn, remember, and reason over structured information across conversations. +## Memory containers + +Agentic memory is organized into **memory containers** that hold different types of memory data. Memory containers are the top-level organizational unit that holds all memory types for a specific use case. Each container can be configured with: + +- **Text embedding models** for semantic search capabilities +- **Large language models (LLMs)** for inference and knowledge extraction +- **Memory processing strategies** (semantic analysis, summarization, user preference extraction) +- **Namespace organization** for multi-tenant or multi-session scenarios + +## Memory types + +Each memory container can store the following memory types: + +- **`sessions`** - Manages conversation sessions and their metadata. Each session represents a distinct interaction context between users and agents, containing session-specific information such as start time, participants, and session state. + +- **`working`** - Stores active conversation data and structured information that agents use during ongoing interactions. This includes recent messages, current context, agent state, execution traces, and temporary data needed for immediate processing. + +- **`long-term`** - Contains processed knowledge and facts extracted from conversations over time. When inference is enabled, large language models extract key insights, user preferences, and important information from working memory and store them as persistent knowledge. + +- **`history`** - Maintains an audit trail of all memory operations (add, update, delete) across the memory container. This provides a comprehensive log of how memories have evolved and changed over time. + +## Payload types + +When adding memories, you can specify the following payload types: + +- **`conversational`** - Stores conversational messages between users and assistants. +- **`data`** - Stores structured, non-conversational data such as agent state, checkpoints, or reference information. + +## Inference mode + +You can control how OpenSearch processes memories using the `infer` parameter: + +- **`false` (default)** - Stores raw messages and data in `working` memory without LLM processing. +- **`true`** - Uses the configured large language model (LLM) to extract key information and knowledge from the content. + +## Memory processing strategies + +Memory containers can use strategies to automatically process and organize memories: + +- **`SEMANTIC`** - Groups related memories by meaning and content similarity +- **`USER_PREFERENCE`** - Extracts and stores user preferences from conversations +- **`SUMMARY`** - Creates condensed summaries of conversation content + +Strategies are optional - you can create containers without them for simple storage needs. + ## Disabling Agentic Memory APIs -As Agentinc memory is GA in 3.3, this feature is enabled by default. To disable Agentic Memory APIs, update the following cluster setting: +Agentic Memory APIs are enabled by default. To disable Agentic Memory APIs, update the following cluster setting: ```json PUT /_cluster/settings @@ -39,10 +84,8 @@ OpenSearch supports the following memory container APIs: OpenSearch supports the following memory APIs: -## Memory APIs (Unified) - - [Add memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/add-memory/) -- [Get memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type/) -- [Update memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type/) -- [Delete memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory-by-type/) -- [Search memories by type]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type/) \ No newline at end of file +- [Get memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/) +- [Update memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory/) +- [Delete memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory/) +- [Search memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory/) \ No newline at end of file diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md deleted file mode 100644 index cdf3e88a4e1..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memories-by-type.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -layout: default -title: Search memories by type -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 54 ---- - -# Search memories by type -**Introduced 3.3** -{: .label .label-purple } - -Use this API to search for memories of a specific type within a memory container. This unified API supports searching session, working, long-term, and history memory data. - -## Path and HTTP methods - -```json -GET /_plugins/_ml/memory_containers//memories//_search -``` - -## Path parameters - -| Field | Data type | Required/Optional | Description | -|:----------------------| :--- | :--- | :--- | -| `memory_container_id` | String | Required | The ID of the memory container. | -| `type` | String | Required | The type of memory: "sessions", "working", "long-term", or "history". | - -## Request fields - -The request body supports standard OpenSearch query DSL. - -## Example requests - -### Search sessions - -```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/_search -{ - "query": { - "match_all": {} - }, - "sort": [ - { - "created_time": { - "order": "desc" - } - } - ] -} -``` - -### Search long-term memories - -```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/_search -{ - "query": { - "bool": { - "must": [ - { - "term": { - "namespace.user_id": "bob" - } - } - ] - } - }, - "sort": [ - { - "created_time": { - "order": "desc" - } - } - ] -} -``` - -### Search memory history - -```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/_search -{ - "query": { - "match_all": {} - }, - "sort": [ - { - "created_time": { - "order": "desc" - } - } - ] -} -``` - -### Search working memories with namespace filter - -```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_search -{ - "query": { - "bool": { - "must": [ - { - "term": { - "namespace.user_id": "bob" - } - } - ], - "must_not": [ - { - "exists": { - "field": "tags.parent_memory_id" - } - } - ] - } - }, - "sort": [ - { - "created_time": { - "order": "desc" - } - } - ] -} -``` - -### Search trace data by session - -```json -GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_search -{ - "query": { - "term": { - "namespace.session_id": "123" - } - }, - "sort": [ - { - "created_time": { - "order": "desc" - } - } - ] -} -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "took": 5, - "timed_out": false, - "_shards": { - "total": 1, - "successful": 1, - "skipped": 0, - "failed": 0 - }, - "hits": { - "total": { - "value": 1, - "relation": "eq" - }, - "max_score": null, - "hits": [ - { - "_index": "test1-session", - "_id": "CcxjTpkBvwXRq366A1aE", - "_score": null, - "_source": { - "memory_container_id": "HudqiJkB1SltqOcZusVU", - "namespace": { - "user_id": "bob" - }, - "created_time": "2025-09-15T17:18:55.881276939Z", - "last_updated_time": "2025-09-15T17:18:55.881276939Z" - }, - "sort": ["2025-09-15T17:18:55.881276939Z"] - } - ] - } -} -``` - -## Response fields - -The response fields vary depending on the memory type being searched. See the unified memory API documentation for specific field descriptions: - -- [Get memory by type and ID]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory-by-type/) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md index 092808264fe..b2dad4e2b20 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md @@ -1,18 +1,18 @@ --- layout: default title: Search memory containers -parent: Agentic Memory APIs +parent: Agentic memory APIs grand_parent: ML Commons APIs nav_order: 25 --- -# Search memory containers +# Search Memory Containers API **Introduced 3.3** {: .label .label-purple } Use this API to search for memory containers using OpenSearch query DSL. -## Path and HTTP methods +## Endpoints ```json GET /_plugins/_ml/memory_containers/_search @@ -21,7 +21,7 @@ POST /_plugins/_ml/memory_containers/_search ## Request fields -The request body supports standard OpenSearch query DSL. +The request body supports standard OpenSearch query DSL. For more information, see [Query DSL]({{site.url}}{{site.baseurl}}/query-dsl/). ## Example request @@ -84,10 +84,12 @@ GET /_plugins/_ml/memory_containers/_search ## Response fields +The following table lists all response body fields. + | Field | Data type | Description | | :--- | :--- | :--- | | `name` | String | The name of the memory container. | | `description` | String | The description of the memory container. | -| `configuration` | Object | The memory container configuration including models and strategies. | -| `created_time` | Long | Timestamp when the container was created. | -| `last_updated_time` | Long | Timestamp when the container was last updated. | +| `configuration` | Object | The memory container configuration, including models and strategies. | +| `created_time` | Long | The timestamp when the container was created. | +| `last_updated_time` | Long | The timestamp when the container was last updated. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md deleted file mode 100644 index 2277d4844cc..00000000000 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-by-type.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -layout: default -title: Update memory by type and ID -parent: Agentic Memory APIs -grand_parent: ML Commons APIs -nav_order: 52 ---- - -# Update memory by type and ID -**Introduced 3.3** -{: .label .label-purple } - -Use this API to update a specific memory by its type and ID. This unified API supports updating session, working, and long-term memory data. History memory does not support updates. - -## Path and HTTP methods - -```json -PUT /_plugins/_ml/memory_containers//memories// -``` - -## Path parameters - -| Parameter | Data type | Required/Optional | Description | -| :--- | :--- | :--- | :--- | -| `memory_container_id` | String | Required | The ID of the memory container. | -| `type` | String | Required | The type of memory: "sessions", "working", or "long-term". Note: History memory cannot be updated. | -| `id` | String | Required | The ID of the memory to update. | - -## Request fields - -The request fields vary depending on the memory type being updated: - -### For session memory - -| Field | Data type | Description | -|:-----------|:----------------------| :--- | -| `summary` | String | The summary of the session. -| `metadata` | Map | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). -| `agents` | Map | Additional information about agents. -| `additional_info` | Map | Additional information about memory - - - -### For working memory - -| Field | Data type | Description | -| :--- | :--- |:-----------------------------------------------------------------| -| `messages` | Array | Updated conversation messages (for conversation type). Optional. | -| `structured_data` | Object | Updated structured data content (for data type). Optional. | -| `binary_data` | Object | Updated binary data content (for data type). Optional. | -| `tags` | Object | Updated tags for categorization. Optional. | -| `metadata` | Map | Additional metadata for the memory (e.g., `status`, `branch`, custom fields). - -### For long-term memory - -| Field | Data type | Description | -| :--- | :--- |:-----------------------------------------------------------------------------------------------------------| -| `memory` | String | The updated memory content. Optional. Updating memory field will automatically update the memory embedding | -| `tags` | Object | Updated tags for categorization. Optional. | - -## Example requests - -### Update session - -```json -PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/N2CDipkB2Mtr6INFFcX8 -{ - "additional_info": { - "key1": "value1", - "last_activity": "2025-09-15T17:30:00Z" - } -} -``` - -### Update working memory - -```json -PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM -{ - "tags": { - "topic": "updated_topic", - "priority": "high" - } -} -``` - -### Update long-term memory - -```json -PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz -{ - "memory": "User's name is Bob Smith", - "tags": { - "topic": "personal info", - "updated": "true" - } -} -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "result": "updated", - "_id": "N2CDipkB2Mtr6INFFcX8", - "_version": 2, - "_shards": { - "total": 2, - "successful": 1, - "failed": 0 - } -} -``` - -## Response fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `result` | String | The result of the update operation. | -| `_id` | String | The ID of the updated memory. | -| `_version` | Integer | The version number of the updated memory. | -| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md index c9a796da7cf..2f3d327242c 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md @@ -1,12 +1,12 @@ --- layout: default title: Update memory container -parent: Agentic Memory APIs +parent: Agentic memory APIs grand_parent: ML Commons APIs nav_order: 15 --- -# Update memory container +# Update Memory Container API **Introduced 3.3** {: .label .label-purple } @@ -16,7 +16,7 @@ Use this API to update an existing memory container's properties such as name an Use this API to update an existing memory container's properties such as name, description, configuration, and access permissions. >>>>>>> b18236c7b4a8f389df07932f44a8818366485dd4 -## Path and HTTP methods +## Endpoints ```json PUT /_plugins/_ml/memory_containers/ @@ -119,6 +119,8 @@ PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU ## Response fields +The following table lists all response body fields. + | Field | Data type | Description | | :--- | :--- | :--- | | `result` | String | The result of the update operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md index ac15cfd7e82..17759f9cbf7 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md @@ -30,15 +30,20 @@ The following table lists the available path parameters. ## Request fields -The request fields vary depending on the memory type being updated. +The request fields vary depending on the memory type being updated. All request fields are optional. ### Session memory request fields -The following table lists all session memory request body fields. +The following table lists all session memory request body fields. | Field | Data type | Description | | :--- | :--- | :--- | -| `additional_info` | Object | Additional metadata to associate with the session. Optional. | +| Field | Data type | Description | +|:-----------|:----------------------| :--- | +| `summary` | String | The summary of the session. +| `metadata` | Object | Additional metadata for the memory (for example, `status`, `branch`, or custom fields). | +| `agents` | Object | Additional information about the agents. | +| `additional_info` | Object | Additional metadata to associate with the session. | ### Working memory request fields @@ -47,9 +52,10 @@ The following table lists all working memory request body fields. | Field | Data type | Description | | :--- | :--- | :--- | | `messages` | Array | Updated conversation messages (for conversation type). Optional. | -| `structured_data` | Object | Updated structured data content (for data type). Optional. | -| `tags` | Object | Updated tags for categorization. Optional. | -| `additional_info` | Object | Additional metadata. Optional. | +| `structured_data` | Object | Updated structured data content (for `data` memory payloads). | +| `binary_data` | Object | Updated binary data content (for `data` memory payloads). Optional. | +| `tags` | Object | Updated tags for categorization. | +| `metadata` | Object | Additional metadata for the memory (for example, `status`, `branch`, or custom fields). ### Long-term memory request fields @@ -59,7 +65,6 @@ The following table lists all long-term memory request body fields. | :--- | :--- | :--- | | `memory` | String | The updated memory content. Optional. | | `tags` | Object | Updated tags for categorization. Optional. | -| `additional_info` | Object | Additional metadata. Optional. | ## Example request: Update a session From 2e2ed1675796bcd85d40153feae52679ecd1b1e3 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 13 Oct 2025 12:24:43 -0400 Subject: [PATCH 18/27] Doc review part 2 Signed-off-by: Fanit Kolchina --- .../agents-tools/agentic-memory.md | 208 ++++++++++++++++++ _ml-commons-plugin/agents-tools/index.md | 6 +- .../api/agentic-memory-apis/add-memory.md | 6 +- .../create-memory-container.md | 29 ++- .../delete-memory-container.md | 4 - .../api/agentic-memory-apis/index.md | 47 +--- .../update-memory-container.md | 37 ++-- _ml-commons-plugin/api/index.md | 10 +- _ml-commons-plugin/cluster-settings.md | 38 +++- 9 files changed, 296 insertions(+), 89 deletions(-) create mode 100644 _ml-commons-plugin/agents-tools/agentic-memory.md diff --git a/_ml-commons-plugin/agents-tools/agentic-memory.md b/_ml-commons-plugin/agents-tools/agentic-memory.md new file mode 100644 index 00000000000..a6d348ba30e --- /dev/null +++ b/_ml-commons-plugin/agents-tools/agentic-memory.md @@ -0,0 +1,208 @@ +--- +layout: default +title: Agentic memory +parent: Agents and tools +nav_order: 30 +--- + +# Agentic memory +**Introduced 3.3** +{: .label .label-purple } + +Agentic memory enables AI agents to learn, remember, and reason over structured information across conversations. Unlike simple conversational memory that only stores message history, agentic memory provides persistent, intelligent storage that helps agents maintain context, learn user preferences, and improve their responses over time. + +Using agentic memory, you can build AI agents that can do the following: + +- Remember user preferences across multiple conversation sessions +- Learn from past interactions to provide more personalized responses +- Maintain conversation context beyond simple message history +- Store and retrieve factual knowledge extracted from conversations +- Track agent execution traces for debugging and analysis +- Organize information across different users, sessions, or agent instances + +## Memory containers + +Agentic memory is organized into _memory containers_ that hold all memory types for a specific use case, such as a chatbot, research assistant, or customer service agent. + +Each container can be configured with the following components: + +- Text embedding models: For semantic search capabilities. +- Large language models (LLMs): For inference and knowledge extraction. +- [Memory processing strategies](#memory-processing-strategies): For automatic content organization. +- [Namespaces](#namespaces): For organizing memories within containers. + +For example, to create a memory container with two strategies, send the following request: + +```json +POST /_plugins/_ml/memory_containers/_create +{ + "name": "customer-service-agent", + "description": "Memory container for customer service agent", + "configuration": { + "embedding_model_type": "TEXT_EMBEDDING", + "embedding_model_id": "your-embedding-model-id", + "llm_id": "your-llm-model-id", + "strategies": [ + { + "type": "USER_PREFERENCE", + "namespace": ["user_id"] + }, + { + "type": "SUMMARY", + "namespace": ["user_id", "session_id"] + } + ] + } +} +``` +{% include copy-curl.html %} + +## Memory types + +Each memory container can store four distinct types of memory: + +- `sessions` -- Manages conversation sessions and their metadata. Each session represents a distinct interaction context between users and agents, containing session-specific information such as start time, participants, and session state. + +- `working` -- Stores active conversation data and structured information that agents use during ongoing interactions. This includes recent messages, current context, agent state, execution traces, and temporary data needed for immediate processing. + +- `long-term` -- Contains processed knowledge and facts extracted from conversations over time. When inference is enabled, large language models extract key insights, user preferences, and important information from working memory and store them as persistent knowledge. + +- `history` -- Maintains an audit trail of all memory operations (add, update, delete) across the memory container. This provides a comprehensive log of how memories have evolved and changed over time. + +## Payload types + +When adding memories, you can specify different payload types: + +- `conversational` -- Stores conversational messages between users and assistants. +- `data` -- Stores structured, non-conversational data such as agent state, checkpoints, or reference information. + +To add a conversational memory with inference, send the following request: + +```json +POST /_plugins/_ml/memory_containers//memories +{ + "messages": [ + { + "role": "user", + "content": "I prefer email notifications over SMS" + }, + { + "role": "assistant", + "content": "I've noted your preference for email notifications" + } + ], + "namespace": { + "user_id": "user123", + "session_id": "session456" + }, + "payload_type": "conversational", + "infer": true +} +``` +{% include copy-curl.html %} + +To add agent state data, send the following request: + +```json +POST /_plugins/_ml/memory_containers//memories +{ + "structured_data": { + "agent_state": "researching", + "current_task": "analyze customer feedback", + "progress": 0.75 + }, + "namespace": { + "agent_id": "research-agent-1", + "session_id": "session456" + }, + "payload_type": "data", + "infer": false +} +``` +{% include copy-curl.html %} + +## Inference mode + +You can control how OpenSearch processes memories using the `infer` parameter: + +- `false` (default) -- Stores raw messages and data in `working` memory without LLM processing +- `true` -- Uses the configured large language model (LLM) to extract key information and knowledge from the content + +## Memory processing strategies + +Memory containers can use the following _strategies_ to automatically process and organize memories: + +- `SEMANTIC` -- Groups related memories by meaning and content similarity. +- `USER_PREFERENCE` -- Extracts and stores user preferences from conversations. +- `SUMMARY` -- Creates condensed summaries of conversation content. + +Strategies are optional; you can create containers without them for simple storage needs. + +## Namespaces + +_Namespaces_ organize memories within containers by grouping them with identifiers like `user_id`, `session_id`, or `agent_id`. This allows you to separate memories for different users or conversation sessions. + +To search memories by namespace, send the following request: + +```json +GET /_plugins/_ml/memory_containers//memories/long-term/_search +{ + "query": { + "bool": { + "must": [ + { + "term": { + "namespace.user_id": "user123" + } + } + ] + } + } +} +``` +{% include copy-curl.html %} + +## Example use cases + +The following examples demonstrate how you can use agentic memory. + +### Personalized chatbot + +Create a memory container that learns user preferences over time: + +- Store conversations in `working` memory with inference enabled +- Extract user preferences into `long-term` memory using the `USER_PREFERENCE` strategy +- Use namespaces to separate different users' memories + +### Research assistant agent + +Build an agent that accumulates knowledge from research sessions: + +- Store research queries and results in `working` memory +- Use the `SEMANTIC` strategy to group related research topics +- Maintain `history` to track how knowledge evolved over time + +### Customer service agent + +Develop an agent that remembers customer interactions: + +- Store customer conversations with inference to extract key issues +- Use `SUMMARY` strategy to create concise interaction summaries +- Organize by customer ID using namespaces + +## Getting started + +To implement agentic memory in your agents: + +1. **[Create a memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container/)** with appropriate models and strategies. +2. **[Add memories]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/add-memory/)** during agent interactions. +3. **[Search and retrieve]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory/)** relevant memories to inform agent responses. +4. **[Update memories]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory/)** as conversations evolve. + +For detailed API documentation, see [Agentic Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/). + +## Next steps + +- Learn about [agent types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/) and how to integrate agentic memory +- Explore [memory container configuration]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container/) options +- Review the complete [Agentic Memory API reference]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/) \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/index.md b/_ml-commons-plugin/agents-tools/index.md index e0625bde53f..334d92d127e 100644 --- a/_ml-commons-plugin/agents-tools/index.md +++ b/_ml-commons-plugin/agents-tools/index.md @@ -12,9 +12,13 @@ redirect_from: **Introduced 2.13** {: .label .label-purple } -You can automate machine learning (ML) tasks using agents and tools. +You can automate machine learning (ML) tasks using agents and tools. An _agent_ orchestrates and runs ML models and tools. For a list of supported agents, see [Agents]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/). A _tool_ performs a set of specific tasks. Some examples of tools are the [`VectorDBTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/vector-db-tool/), which supports vector search, and the [`ListIndexTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/list-index-tool/), which executes the List Indices API. For a list of supported tools, see [Tools]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/index/). +## Agentic memory + +Agents can use [agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agentic-memory/) to learn, remember, and reason over structured information across conversations. This enables agents to maintain context, learn user preferences, and improve their responses over time. + diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index f0ddb0add01..5cfda31bbb5 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -39,7 +39,7 @@ Field | Data type | Required/Optional | Description `structured_data` | Object | Conditional | Structured data content for data memory. Required when `payload_type` is `data`. `binary_data` | String | Optional | Binary data content encoded as a Base64 string for binary payloads. `payload_type` | String | Required | The type of payload. Valid values are `conversational` or `data`. See [Payload types](#payload-types). -`namespace` | Object | Optional | The namespace context for organizing memories (for example, `user_id`, `session_id`, or `agent_id`). If `session_id` is not specified in the `namespace` field, a new session with a new session ID is created. +`namespace` | Object | Optional | The [namespace]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#namespaces) context for organizing memories (for example, `user_id`, `session_id`, or `agent_id`). If `session_id` is not specified in the `namespace` field, a new session with a new session ID is created. `metadata` | Object | Optional | Additional metadata for the memory (for example, `status`, `branch`, or custom fields). `tags` | Object | Optional | Tags for categorizing and organizing memories. `infer` | Boolean | Optional | Whether to use an 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 a memory. See [Inference mode](#inference-mode). @@ -124,7 +124,7 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories } ``` -### Trace data memory +## Example request: Storing trace data To store agent trace data in working memory, send the following request: @@ -166,7 +166,7 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories ``` {% include copy-curl.html %} -## Example response: Trace memory +## Example response: Trace data ```json { diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index 0d547ac0833..3e84bb1c1bc 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -163,40 +163,51 @@ Field | Data type | Required/Optional | Description `disable_history` | Boolean | Optional | if disabled no history will be persisted. Default is `false`, so history will be persisted by default. `disable_session` | Boolean | Optional | if disabled no session will be persisted. Default is `true`, so session will not be persisted by default. `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. -`index_settings` | Map | Optional | Customer can also provide the index settings. See [the `index settings` array](#the-index-settings). +`index_settings` | Object | Optional | Custom OpenSearch index settings for the memory storage indexes that will be created for this container. Each memory type (`sessions`, `working`, `long_term`, and `history`) uses its own index. See [Index settings](#index-settings). `strategies` | Array | Optional | An array of [memory processing strategies]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#memory-processing-strategies). See [The `strategies` array](#the-strategies-array). `parameters` | Object | Optional | Global parameters for the memory container. See [The `parameters` object](#the-parameters-object). -### The index settings +### Index settings -Example of index settings +You can customize the OpenSearch index settings for the storage indexes that will be created to store memory data. Each memory type uses a dedicated index, and you can configure settings like the number of shards and replicas for performance optimization. +The following example shows how to specify custom index settings in the `configuration` object: + +```json +{ + "name": "my-memory-container", + "configuration": { + "embedding_model_id": "your-model-id", "index_settings": { - "session_index" : { + "session_index": { "index": { "number_of_shards": "2", "number_of_replicas": "2" } }, - "short_term_memory_index" : { + "short_term_memory_index": { "index": { "number_of_shards": "2", "number_of_replicas": "2" } }, - "long_term_memory_index" : { + "long_term_memory_index": { "index": { "number_of_shards": "2", "number_of_replicas": "2" } }, - "long_term_memory_history_index" : { + "long_term_memory_history_index": { "index": { "number_of_shards": "2", "number_of_replicas": "2" } } } + } +} +``` +{% include copy.html %} ### The strategies array @@ -205,7 +216,7 @@ Each strategy in the `strategies` array supports the following fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- `type` | String | Required | The strategy type. Valid values are `SEMANTIC`, `USER_PREFERENCE`, and `SUMMARY`. -`namespace` | Array | Required | An array of namespace dimensions for organizing memories (for example, `["user_id"]` or `["agent_id", "session_id"]`). +`namespace` | Array | Required | An array of [namespace]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#namespaces) dimensions for organizing memories (for example, `["user_id"]` or `["agent_id", "session_id"]`). `configuration` | Object | Optional | Strategy-specific configuration. See [The strategy `configuration` object](#the-strategy-configuration-object). `enabled` | Boolean | Optional | Whether to enable the strategy in the memory container. Default is `true`. @@ -248,7 +259,7 @@ POST /_plugins/_ml/memory_containers/_create ``` {% include copy-curl.html %} -### Example request: Advanced memory container with multiple strategies +## Example request: Advanced memory container with multiple strategies ```json POST /_plugins/_ml/memory_containers/_create diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md index 4e5ca47ef08..0f5f93e4949 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md @@ -10,10 +10,6 @@ nav_order: 30 **Introduced 3.3** {: .label .label-purple } -<<<<<<< Updated upstream -======= - ->>>>>>> Stashed changes Use this API to delete a memory container by its ID. ## Endpoints diff --git a/_ml-commons-plugin/api/agentic-memory-apis/index.md b/_ml-commons-plugin/api/agentic-memory-apis/index.md index 7f8448523a3..6ab27b0e5b4 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/index.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/index.md @@ -13,52 +13,7 @@ redirect_from: **Introduced 3.3** {: .label .label-purple } -Agentic Memory APIs provide persistent memory management for AI agents. This enables agents to learn, remember, and reason over structured information across conversations. - -## Memory containers - -Agentic memory is organized into **memory containers** that hold different types of memory data. Memory containers are the top-level organizational unit that holds all memory types for a specific use case. Each container can be configured with: - -- **Text embedding models** for semantic search capabilities -- **Large language models (LLMs)** for inference and knowledge extraction -- **Memory processing strategies** (semantic analysis, summarization, user preference extraction) -- **Namespace organization** for multi-tenant or multi-session scenarios - -## Memory types - -Each memory container can store the following memory types: - -- **`sessions`** - Manages conversation sessions and their metadata. Each session represents a distinct interaction context between users and agents, containing session-specific information such as start time, participants, and session state. - -- **`working`** - Stores active conversation data and structured information that agents use during ongoing interactions. This includes recent messages, current context, agent state, execution traces, and temporary data needed for immediate processing. - -- **`long-term`** - Contains processed knowledge and facts extracted from conversations over time. When inference is enabled, large language models extract key insights, user preferences, and important information from working memory and store them as persistent knowledge. - -- **`history`** - Maintains an audit trail of all memory operations (add, update, delete) across the memory container. This provides a comprehensive log of how memories have evolved and changed over time. - -## Payload types - -When adding memories, you can specify the following payload types: - -- **`conversational`** - Stores conversational messages between users and assistants. -- **`data`** - Stores structured, non-conversational data such as agent state, checkpoints, or reference information. - -## Inference mode - -You can control how OpenSearch processes memories using the `infer` parameter: - -- **`false` (default)** - Stores raw messages and data in `working` memory without LLM processing. -- **`true`** - Uses the configured large language model (LLM) to extract key information and knowledge from the content. - -## Memory processing strategies - -Memory containers can use strategies to automatically process and organize memories: - -- **`SEMANTIC`** - Groups related memories by meaning and content similarity -- **`USER_PREFERENCE`** - Extracts and stores user preferences from conversations -- **`SUMMARY`** - Creates condensed summaries of conversation content - -Strategies are optional - you can create containers without them for simple storage needs. +Agentic Memory APIs provide persistent memory management for AI agents. For an overview of concepts, use cases, and getting started information, see [Agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agentic-memory/). ## Disabling Agentic Memory APIs diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md index 2f3d327242c..04866990461 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md @@ -10,11 +10,7 @@ nav_order: 15 **Introduced 3.3** {: .label .label-purple } -<<<<<<< HEAD -Use this API to update an existing memory container's properties such as name and description. -======= Use this API to update an existing memory container's properties such as name, description, configuration, and access permissions. ->>>>>>> b18236c7b4a8f389df07932f44a8818366485dd4 ## Endpoints @@ -24,15 +20,9 @@ PUT /_plugins/_ml/memory_containers/ ## Path parameters -<<<<<<< HEAD -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `memory_container_id` | String | The ID of the memory container to update. Required. | -======= | Parameter | Data type | Required/Optional | Description | | :--- | :--- | :--- | :--- | | `memory_container_id` | String | Required | The ID of the memory container to update. | ->>>>>>> b18236c7b4a8f389df07932f44a8818366485dd4 ## Request fields @@ -40,9 +30,11 @@ PUT /_plugins/_ml/memory_containers/ | :--- | :--- | :--- | :--- | | `name` | String | Optional | The updated name of the memory container. | | `description` | String | Optional | The updated description of the memory container. | -| `configuration` | Object | Optional | Configuration object containing strategies and embedding settings. | +| `configuration` | Object | Optional | Configuration object containing strategies and embedding settings. See [The configuration object](#the-configuration-object). | + +### The configuration object -### Configuration object fields +The `configuration` objects supports the following fields. | Field | Data type | Required/Optional | Description | | :--- | :--- | :--- | :--- | @@ -54,31 +46,31 @@ PUT /_plugins/_ml/memory_containers/ ## Update behavior +Note the following update behavior. + ### Strategy updates -- **Update existing strategy**: Include the strategy `id` to update that specific strategy. -- **Create new strategy**: Specify a strategy without an `id` to create a new strategy. + +- To update a specific strategy, specify the strategy `id`. +- To create a new strategy, specify a strategy without an `id`. ### Backend roles updates + - Adding new `backend_roles` grants new users read or write access with those roles. -- The `backend_roles` field is updated by overwriting, so include original roles if you want to keep them. +- The new `backend_roles` field overwrites the existing field, so include original roles if you want to keep them. ### Namespace updates -- The `namespace` field inside strategies is updated by overwriting. -- Include the original namespace if you want to keep it. + +- The `namespace` field in the `strategies` object is updated by overwriting. Include the original namespace if you want to keep it. ### Embedding model restrictions -- 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. -- Once a long-term memory index with the specified `index_prefix` is created, these embedding fields cannot be updated. +- 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. Once a long-term memory index with the specified `index_prefix` is created, these embedding fields cannot be updated. ## Example request ```json PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU { -<<<<<<< HEAD - "name": "opensearch-agents-memory" -======= "name": "opensearch-agents-memory", "description": "Updated memory container for OpenSearch agents", "backend_roles": ["admin", "ml_user"], @@ -97,7 +89,6 @@ PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU "embedding_model_type": "dense", "embedding_dimension": 768 } ->>>>>>> b18236c7b4a8f389df07932f44a8818366485dd4 } ``` {% include copy-curl.html %} diff --git a/_ml-commons-plugin/api/index.md b/_ml-commons-plugin/api/index.md index ab34d954c0f..6e61c381752 100644 --- a/_ml-commons-plugin/api/index.md +++ b/_ml-commons-plugin/api/index.md @@ -24,4 +24,12 @@ OpenSearch supports the following machine learning (ML) APIs: - [Tasks APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/tasks-apis/index/) - [Profile API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/profile/) - [Stats API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/stats/) -- [MCP Server APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/mcp-server-apis/) \ No newline at end of file +- [MCP Server APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/mcp-server-apis/) + +## Memory APIs comparison + +OpenSearch provides two different memory systems: + +- **[Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/index/)** - Simple conversation history storage for [conversational search]({{site.url}}{{site.baseurl}}/search-plugins/conversational-search/). Stores question/answer pairs chronologically without processing or learning. + +- **[Agentic Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/)** - Intelligent memory system for AI agents. Uses LLMs to extract knowledge, learn user preferences, and maintain context across sessions. For conceptual information, see [Agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agentic-memory/). \ No newline at end of file diff --git a/_ml-commons-plugin/cluster-settings.md b/_ml-commons-plugin/cluster-settings.md index 26e8f94a522..843842c6f6c 100644 --- a/_ml-commons-plugin/cluster-settings.md +++ b/_ml-commons-plugin/cluster-settings.md @@ -18,6 +18,7 @@ By default, ML tasks and models only run on ML nodes. When configured without th ```yml node.roles: [ ml ] ``` +{% include copy.html %} ### Setting up a cluster with a dedicated ML node @@ -38,6 +39,7 @@ We recommend setting `plugins.ml_commons.only_run_on_ml_node` to `true` on produ ```yaml plugins.ml_commons.only_run_on_ml_node: true ``` +{% include copy.html %} ### Values @@ -54,6 +56,7 @@ plugins.ml_commons.only_run_on_ml_node: true ```yaml plugins.ml_commons.task_dispatch_policy: round_robin ``` +{% include copy.html %} ### Values @@ -70,6 +73,7 @@ Sets the number of ML tasks that can run on each ML node. When set to `0`, no ML ```yaml plugins.ml_commons.max_ml_task_per_node: 10 ``` +{% include copy.html %} ### Values @@ -85,6 +89,7 @@ Sets the number of ML models that can be deployed to each ML node. When set to ` ```yaml plugins.ml_commons.max_model_on_node: 10 ``` +{% include copy.html %} ### Values @@ -101,6 +106,7 @@ When returning runtime information with the [Profile API]({{site.url}}{{site.bas ```yaml plugins.ml_commons.sync_up_job_interval_in_seconds: 3 ``` +{% include copy.html %} ### Values @@ -116,6 +122,7 @@ Controls how many predict requests are monitored on one node. If set to `0`, Ope ```yaml plugins.ml_commons.monitoring_request_count: 100 ``` +{% include copy.html %} ### Value range @@ -131,6 +138,7 @@ Controls how many register model tasks can run in parallel on one node. If set t ```yaml plugins.ml_commons.max_register_model_tasks_per_node: 10 ``` +{% include copy.html %} ### Values @@ -148,6 +156,7 @@ Controls how many deploy model tasks can run in parallel on one node. If set to ```yaml plugins.ml_commons.max_deploy_model_tasks_per_node: 10 ``` +{% include copy.html %} ### Values @@ -163,6 +172,7 @@ This setting gives you the ability to register models using a URL. By default, M ```yaml plugins.ml_commons.allow_registering_model_via_url: false ``` +{% include copy.html %} ### Values @@ -178,6 +188,7 @@ This setting gives you the ability to register a model using a local file. By de ```yaml plugins.ml_commons.allow_registering_model_via_local_file: false ``` +{% include copy.html %} ### Values @@ -198,6 +209,7 @@ The default URL value for this trusted URL setting is not secure. For security, ```yaml plugins.ml_commons.trusted_url_regex: ``` +{% include copy.html %} ### Values @@ -213,6 +225,7 @@ Assigns how long in seconds an ML task will live. After the timeout, the task wi ```yaml plugins.ml_commons.ml_task_timeout_in_seconds: 600 ``` +{% include copy.html %} ### Values @@ -232,6 +245,7 @@ Starting with OpenSearch 2.5, ML Commons runs a native memory circuit breaker to ```yaml plugins.ml_commons.native_memory_threshold: 90 ``` +{% include copy.html %} ### Values @@ -249,6 +263,7 @@ Values are based on the percentage of JVM heap memory available. When set to `0` ```yaml plugins.ml_commons.jvm_heap_memory_threshold: 85 ``` +{% include copy.html %} ### Values @@ -266,6 +281,7 @@ Valid values are in byte units. To disable the circuit breaker, set this value t ```yaml plugins.ml_commons.disk_free_space_threshold: 5G ``` +{% include copy.html %} ### Values @@ -281,6 +297,7 @@ Use this setting to specify the names of nodes on which you don't want to run ML ```yaml plugins.ml_commons.exclude_nodes._name: node1, node2 ``` +{% include copy.html %} ## Allow custom deployment plans @@ -291,6 +308,7 @@ When enabled, this setting grants users the ability to deploy models to specific ```yaml plugins.ml_commons.allow_custom_deployment_plan: false ``` +{% include copy.html %} ### Values @@ -306,6 +324,7 @@ This setting is applicable when you send a prediction request for an externally ```yaml plugins.ml_commons.model_auto_deploy.enable: false ``` +{% include copy.html %} ### Values @@ -319,8 +338,9 @@ This setting automatically redeploys deployed or partially deployed models upon ### Setting ```yaml -plugins.ml_commons.model_auto_redeploy.enable: true +plugins.ml_commons.model_auto_redeploy.enable: true ``` +{% include copy.html %} ### Values @@ -336,6 +356,7 @@ This setting sets the limit for the number of times a deployed or partially depl ```yaml plugins.ml_commons.model_auto_redeploy.lifetime_retry_times: 3 ``` +{% include copy.html %} ### Values @@ -351,6 +372,7 @@ This setting sets the ratio of success for the auto-redeployment of a model base ```yaml plugins.ml_commons.model_auto_redeploy_success_ratio: 0.8 ``` +{% include copy.html %} ### Values @@ -366,6 +388,8 @@ When set to `true`, this setting enables the ability to run Python-based models ```yaml plugins.ml_commons.enable_inhouse_python_model: false ``` +{% include copy.html %} + ### Values @@ -383,6 +407,7 @@ When set to `true`, this setting enables a safety feature that checks for downst ```yaml plugins.ml_commons.safe_delete_model: true ``` +{% include copy.html %} ### Values @@ -399,6 +424,7 @@ When set to `true`, the setting allows admins to control access and permissions ```yaml plugins.ml_commons.connector_access_control_enabled: true ``` +{% include copy.html %} ### Values @@ -414,6 +440,7 @@ This setting allows a cluster admin to enable running local models on the cluste ```yaml plugins.ml_commons.local_model.enabled: true ``` +{% include copy.html %} ### Values @@ -429,6 +456,7 @@ This setting allows a cluster admin to control the types of nodes on which exter ```yaml plugins.ml_commons.task_dispatcher.eligible_node_role.remote_model: ["ml"] ``` +{% include copy.html %} ### Values @@ -444,6 +472,7 @@ This setting allows a cluster admin to control the types of nodes on which local ```yaml plugins.ml_commons.task_dispatcher.eligible_node_role.remote_model: ["ml"] ``` +{% include copy.html %} ### Values @@ -458,6 +487,7 @@ This setting allows a cluster admin to enable remote inference on the cluster. I ```yaml plugins.ml_commons.remote_inference.enabled: true ``` +{% include copy.html %} ### Values @@ -473,6 +503,7 @@ When set to `true`, this setting enables the agent framework (including agents a ```yaml plugins.ml_commons.agent_framework_enabled: true ``` +{% include copy.html %} ### Values @@ -488,6 +519,7 @@ When set to `true`, this setting enables conversational memory, which stores all ```yaml plugins.ml_commons.memory_feature_enabled: true ``` +{% include copy.html %} ### Values @@ -496,13 +528,14 @@ plugins.ml_commons.memory_feature_enabled: true ## Enable agentic memory -When set to `true`, this setting enables agentic memory functionality, which provides advanced memory management for AI agents including session memory, working memory, long-term memory, and memory history with namespace-based organization. +When set to `true`, this setting enables [agentic memory]({{site.url}}{{site.baseurl}}/agents-tools/agentic-memory/), which provides advanced memory management for AI agents including session memory, working memory, long-term memory, and memory history with namespace-based organization. ### Setting ```yaml plugins.ml_commons.agentic_memory_enabled: true ``` +{% include copy.html %} ### Values @@ -518,6 +551,7 @@ When set to `true`, this setting enables the search processors for retrieval-aug ```yaml plugins.ml_commons.rag_pipeline_feature_enabled: true ``` +{% include copy.html %} ### Values From f7d8364b82212bb4ef6a09ee5b0b0f63ab13226e Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Mon, 13 Oct 2025 13:24:38 -0400 Subject: [PATCH 19/27] Apply suggestions from code review Signed-off-by: Nathan Bower --- .../agents-tools/agentic-memory.md | 34 +++++++++---------- .../api/agentic-memory-apis/add-memory.md | 2 +- .../create-memory-container.md | 19 ++++++----- .../api/agentic-memory-apis/delete-memory.md | 4 +-- .../api/agentic-memory-apis/get-memory.md | 10 +++--- .../api/agentic-memory-apis/index.md | 6 ++-- .../search-memory-container.md | 6 ++-- .../api/agentic-memory-apis/search-memory.md | 2 +- .../update-memory-container.md | 14 ++++---- _ml-commons-plugin/api/index.md | 4 +-- _ml-commons-plugin/cluster-settings.md | 2 +- 11 files changed, 52 insertions(+), 51 deletions(-) diff --git a/_ml-commons-plugin/agents-tools/agentic-memory.md b/_ml-commons-plugin/agents-tools/agentic-memory.md index a6d348ba30e..9fff4e6c2a1 100644 --- a/_ml-commons-plugin/agents-tools/agentic-memory.md +++ b/_ml-commons-plugin/agents-tools/agentic-memory.md @@ -9,7 +9,7 @@ nav_order: 30 **Introduced 3.3** {: .label .label-purple } -Agentic memory enables AI agents to learn, remember, and reason over structured information across conversations. Unlike simple conversational memory that only stores message history, agentic memory provides persistent, intelligent storage that helps agents maintain context, learn user preferences, and improve their responses over time. +Agentic memory enables AI agents to learn, remember, and reason over structured information across conversations. Unlike simple conversation memory that only stores message history, agentic memory provides persistent, intelligent storage that helps agents maintain context, learn user preferences, and improve their responses over time. Using agentic memory, you can build AI agents that can do the following: @@ -65,7 +65,7 @@ Each memory container can store four distinct types of memory: - `working` -- Stores active conversation data and structured information that agents use during ongoing interactions. This includes recent messages, current context, agent state, execution traces, and temporary data needed for immediate processing. -- `long-term` -- Contains processed knowledge and facts extracted from conversations over time. When inference is enabled, large language models extract key insights, user preferences, and important information from working memory and store them as persistent knowledge. +- `long-term` -- Contains processed knowledge and facts extracted from conversations over time. When inference is enabled, LLMs extract key insights, user preferences, and important information from working memory and store them as persistent knowledge. - `history` -- Maintains an audit trail of all memory operations (add, update, delete) across the memory container. This provides a comprehensive log of how memories have evolved and changed over time. @@ -76,7 +76,7 @@ When adding memories, you can specify different payload types: - `conversational` -- Stores conversational messages between users and assistants. - `data` -- Stores structured, non-conversational data such as agent state, checkpoints, or reference information. -To add a conversational memory with inference, send the following request: +To add a conversation memory with inference, send the following request: ```json POST /_plugins/_ml/memory_containers//memories @@ -125,8 +125,8 @@ POST /_plugins/_ml/memory_containers//memories You can control how OpenSearch processes memories using the `infer` parameter: -- `false` (default) -- Stores raw messages and data in `working` memory without LLM processing -- `true` -- Uses the configured large language model (LLM) to extract key information and knowledge from the content +- `false` (default) -- Stores raw messages and data in `working` memory without LLM processing. +- `true` -- Uses the configured LLM to extract key information and knowledge from the content. ## Memory processing strategies @@ -170,25 +170,25 @@ The following examples demonstrate how you can use agentic memory. Create a memory container that learns user preferences over time: -- Store conversations in `working` memory with inference enabled -- Extract user preferences into `long-term` memory using the `USER_PREFERENCE` strategy -- Use namespaces to separate different users' memories +- Store conversations in `working` memory with inference enabled. +- Extract user preferences into `long-term` memory using the `USER_PREFERENCE` strategy. +- Use namespaces to separate different users' memories. ### Research assistant agent Build an agent that accumulates knowledge from research sessions: -- Store research queries and results in `working` memory -- Use the `SEMANTIC` strategy to group related research topics -- Maintain `history` to track how knowledge evolved over time +- Store research queries and results in `working` memory. +- Use the `SEMANTIC` strategy to group related research topics. +- Maintain `history` to track how knowledge evolved over time. ### Customer service agent Develop an agent that remembers customer interactions: -- Store customer conversations with inference to extract key issues -- Use `SUMMARY` strategy to create concise interaction summaries -- Organize by customer ID using namespaces +- Store customer conversations with inference to extract key issues. +- Use `SUMMARY` strategy to create concise interaction summaries. +- Organize by customer ID using namespaces. ## Getting started @@ -203,6 +203,6 @@ For detailed API documentation, see [Agentic Memory APIs]({{site.url}}{{site.bas ## Next steps -- Learn about [agent types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/) and how to integrate agentic memory -- Explore [memory container configuration]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container/) options -- Review the complete [Agentic Memory API reference]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/) \ No newline at end of file +- Learn about [agent types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/) and how to integrate agentic memory. +- Explore [memory container configuration]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container/) options. +- Review the complete [Agentic Memory API reference]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/). \ No newline at end of file diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 5cfda31bbb5..1d124110034 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -42,7 +42,7 @@ Field | Data type | Required/Optional | Description `namespace` | Object | Optional | The [namespace]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#namespaces) context for organizing memories (for example, `user_id`, `session_id`, or `agent_id`). If `session_id` is not specified in the `namespace` field, a new session with a new session ID is created. `metadata` | Object | Optional | Additional metadata for the memory (for example, `status`, `branch`, or custom fields). `tags` | Object | Optional | Tags for categorizing and organizing memories. -`infer` | Boolean | Optional | Whether to use an 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 a memory. See [Inference mode](#inference-mode). +`infer` | Boolean | Optional | Whether to use a large language model (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 a memory. See [Inference mode](#inference-mode). ## Example request: Conversational payload diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index 3e84bb1c1bc..794d4723160 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -13,9 +13,9 @@ nav_order: 10 Use this API to create a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#memory-containers) to hold agentic memories. The container can have two model types associated with it: - 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. -- 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. Long term memory requires both an LLM model and embedding model to be configured. +- 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. Long-term memory requires both an LLM model and embedding model to be configured. -**Note**: LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is configured for Bedrock Converse API format (`"$.output.message.content[0].text"`). +**Note**: LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is configured for Amazon Bedrock Converse API format (`"$.output.message.content[0].text"`). For more information, see [Integrating ML models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/integrating-ml-models/). @@ -160,9 +160,9 @@ Field | Data type | Required/Optional | Description `llm_id` | String | Optional | The LLM model ID for processing and inference. `index_prefix` | String | Optional | A custom prefix for memory indexes. If not specified, a default prefix is used: `default` when `use_system_index` is `true`, or an 8-character random UUID when `use_system_index` is `false`. `use_system_index` | Boolean | Optional | Whether to use system indexes. Default is `true`. -`disable_history` | Boolean | Optional | if disabled no history will be persisted. Default is `false`, so history will be persisted by default. -`disable_session` | Boolean | Optional | if disabled no session will be persisted. Default is `true`, so session will not be persisted by default. -`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. +`disable_history` | Boolean | Optional | If disabled, no history will be persisted. Default is `false`, so history will be persisted by default. +`disable_session` | Boolean | Optional | If disabled, no session will be persisted. Default is `true`, so the session will not be persisted by default. +`max_infer_size` | int | Optional | Controls the top k number of similar existing memories retrieved during memory consolidation to make ADD/UPDATE/DELETE decisions. `index_settings` | Object | Optional | Custom OpenSearch index settings for the memory storage indexes that will be created for this container. Each memory type (`sessions`, `working`, `long_term`, and `history`) uses its own index. See [Index settings](#index-settings). `strategies` | Array | Optional | An array of [memory processing strategies]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#memory-processing-strategies). See [The `strategies` array](#the-strategies-array). `parameters` | Object | Optional | Global parameters for the memory container. See [The `parameters` object](#the-parameters-object). @@ -171,7 +171,7 @@ Field | Data type | Required/Optional | Description You can customize the OpenSearch index settings for the storage indexes that will be created to store memory data. Each memory type uses a dedicated index, and you can configure settings like the number of shards and replicas for performance optimization. -The following example shows how to specify custom index settings in the `configuration` object: +The following example shows you how to specify custom index settings in the `configuration` object: ```json { @@ -226,15 +226,16 @@ The strategy `configuration` object supports the following fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`llm_result_path` | String | Optional | A JSONPath for extracting LLM results from responses. Default is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). -`system_prompt` | String | Optional | A custom system prompt to override the default strategy prompt. +`llm_result_path` | String | Optional | A JSONPath expression for extracting LLM results from responses. Default is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). +`system_prompt` | String | Optional | A custom system prompt used to override the default strategy prompt. `llm_id` | String | Optional | The LLM model ID for this strategy. Overrides the global LLM setting. ### The parameters object +The `parameters` object supports the following field. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`llm_result_path` | String | Optional | A global JSONPath for extracting LLM results from responses. Default is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). +`llm_result_path` | String | Optional | A global JSONPath expression for extracting LLM results from responses. Default is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). ## Example request: Basic memory container diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md index 1f6aa8c435e..6a5cf6d97f0 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md @@ -149,7 +149,7 @@ POST /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_dele | Field | Data type | Description | | :--- | :--- | :--- | -| `took` | Integer | The time, in milliseconds, it took to execute the request. | +| `took` | Integer | The time, in milliseconds, taken to execute the request. | | `timed_out` | Boolean | Whether the request timed out. | | `total` | Integer | The total number of documents processed. | | `deleted` | Integer | The number of documents deleted. | @@ -157,7 +157,7 @@ POST /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_dele | `version_conflicts` | Integer | The number of version conflicts encountered. | | `noops` | Integer | The number of no-operation updates. | | `retries` | Object | Information about bulk and search retries. | -| `throttled_millis` | Integer | The time, in milliseconds, the request was throttled. | +| `throttled_millis` | Integer | The time, in milliseconds, that the request was throttled. | | `requests_per_second` | Float | The number of requests processed per second. | | `throttled_until_millis` | Integer | The time, in milliseconds, until throttling is lifted. | | `failures` | Array | Any failures that occurred during the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md index bf95aee236f..84fe1c18ca1 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md @@ -164,8 +164,8 @@ The following table lists all working memory response body fields. | `metadata` | Object | Additional metadata associated with the memory. | | `tags` | Object | Associated tags for categorization. | | `infer` | Boolean | Whether inference was enabled for this memory. | -| `created_time` | Long | The timestamp when the memory was created. | -| `last_updated_time` | Long | The timestamp when the memory was last updated. | +| `created_time` | Long | The timestamp of when the memory was created. | +| `last_updated_time` | Long | The timestamp of when the memory was last updated. | ### Long-term memory response fields @@ -192,8 +192,8 @@ The following table lists all session response body fields. | :--- | :--- | :--- | | `memory_container_id` | String | The ID of the memory container. | | `namespace` | Object | The namespace context for this session. | -| `created_time` | String | The timestamp when the session was created. | -| `last_updated_time` | String | The timestamp when the session was last updated. | +| `created_time` | String | The timestamp of when the session was created. | +| `last_updated_time` | String | The timestamp of when the session was last updated. | ### History response fields @@ -210,4 +210,4 @@ The following table lists all history response body fields. | `namespace` | Object | The namespace context for this memory. | | `namespace_size` | Integer | The namespace size. | | `tags` | Object | Associated tags for categorization. | -| `created_time` | Long | The timestamp when the operation occurred. | +| `created_time` | Long | The timestamp of when the operation occurred. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/index.md b/_ml-commons-plugin/api/agentic-memory-apis/index.md index 6ab27b0e5b4..1bb0e29156d 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/index.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/index.md @@ -13,11 +13,11 @@ redirect_from: **Introduced 3.3** {: .label .label-purple } -Agentic Memory APIs provide persistent memory management for AI agents. For an overview of concepts, use cases, and getting started information, see [Agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agentic-memory/). +Agentic memory APIs provide persistent memory management for AI agents. For an overview of concepts, use cases, and getting started information, see [Agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agentic-memory/). -## Disabling Agentic Memory APIs +## Disabling agentic memory APIs -Agentic Memory APIs are enabled by default. To disable Agentic Memory APIs, update the following cluster setting: +Agentic memory APIs are enabled by default. To disable agentic memory APIs, update the following cluster setting: ```json PUT /_cluster/settings diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md index b2dad4e2b20..b79c65fc993 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md @@ -10,7 +10,7 @@ nav_order: 25 **Introduced 3.3** {: .label .label-purple } -Use this API to search for memory containers using OpenSearch query DSL. +Use this API to search for memory containers using OpenSearch query domain-specific language (DSL). ## Endpoints @@ -91,5 +91,5 @@ The following table lists all response body fields. | `name` | String | The name of the memory container. | | `description` | String | The description of the memory container. | | `configuration` | Object | The memory container configuration, including models and strategies. | -| `created_time` | Long | The timestamp when the container was created. | -| `last_updated_time` | Long | The timestamp when the container was last updated. | +| `created_time` | Long | The timestamp of when the container was created. | +| `last_updated_time` | Long | The timestamp of when the container was last updated. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md index 22e43dfa71f..9033ffeff8c 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md @@ -29,7 +29,7 @@ The following table lists the available path parameters. ## Request fields -The request body supports standard OpenSearch query DSL. For more information, see [Query DSL]({{site.url}}{{site.baseurl}}/query-dsl/). +The request body supports standard OpenSearch query domain-specific language (DSL). For more information, see [Query DSL]({{site.url}}{{site.baseurl}}/query-dsl/). ## Example request: Search sessions diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md index 04866990461..55659ce8d4f 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md @@ -10,7 +10,7 @@ nav_order: 15 **Introduced 3.3** {: .label .label-purple } -Use this API to update an existing memory container's properties such as name, description, configuration, and access permissions. +Use this API to update an existing memory container's properties, such as name, description, configuration, and access permissions. ## Endpoints @@ -30,16 +30,16 @@ PUT /_plugins/_ml/memory_containers/ | :--- | :--- | :--- | :--- | | `name` | String | Optional | The updated name of the memory container. | | `description` | String | Optional | The updated description of the memory container. | -| `configuration` | Object | Optional | Configuration object containing strategies and embedding settings. See [The configuration object](#the-configuration-object). | +| `configuration` | Object | Optional | The configuration object containing strategies and embedding settings. See [The configuration object](#the-configuration-object). | ### The configuration object -The `configuration` objects supports the following fields. +The `configuration` object supports the following fields. | Field | Data type | Required/Optional | Description | | :--- | :--- | :--- | :--- | -| `llm_id` | String | Optional | The large language model ID to use to extract facts. | -| `strategies` | Array | Optional | Array of strategy objects for memory processing. | +| `llm_id` | String | Optional | The large language model (LLM) ID to use to extract facts. | +| `strategies` | Array | Optional | An array of strategy objects for memory processing. | | `embedding_model_id` | String | Optional | The embedding model ID. Can only be updated if no long-term memory index exists. | | `embedding_model_type` | String | Optional | The embedding model type. Can only be updated if no long-term memory index exists. | | `embedding_dimension` | Integer | Optional | The embedding dimension. Can only be updated if no long-term memory index exists. | @@ -50,13 +50,13 @@ Note the following update behavior. ### Strategy updates -- To update a specific strategy, specify the strategy `id`. +- To update a specific strategy, specify the strategy `id`. - To create a new strategy, specify a strategy without an `id`. ### Backend roles updates - Adding new `backend_roles` grants new users read or write access with those roles. -- The new `backend_roles` field overwrites the existing field, so include original roles if you want to keep them. +- The new `backend_roles` field overwrites the existing field, so include the original roles if you want to keep them. ### Namespace updates diff --git a/_ml-commons-plugin/api/index.md b/_ml-commons-plugin/api/index.md index 6e61c381752..659b939954c 100644 --- a/_ml-commons-plugin/api/index.md +++ b/_ml-commons-plugin/api/index.md @@ -30,6 +30,6 @@ OpenSearch supports the following machine learning (ML) APIs: OpenSearch provides two different memory systems: -- **[Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/index/)** - Simple conversation history storage for [conversational search]({{site.url}}{{site.baseurl}}/search-plugins/conversational-search/). Stores question/answer pairs chronologically without processing or learning. +- **[Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/index/)** -- Simple conversation history storage for [conversational search]({{site.url}}{{site.baseurl}}/search-plugins/conversational-search/). Stores question/answer pairs chronologically without processing or learning. -- **[Agentic Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/)** - Intelligent memory system for AI agents. Uses LLMs to extract knowledge, learn user preferences, and maintain context across sessions. For conceptual information, see [Agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agentic-memory/). \ No newline at end of file +- **[Agentic Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/)** -- Intelligent memory system for AI agents. Uses large language models (LLMs) to extract knowledge, learn user preferences, and maintain context across sessions. For conceptual information, see [Agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agentic-memory/). \ No newline at end of file diff --git a/_ml-commons-plugin/cluster-settings.md b/_ml-commons-plugin/cluster-settings.md index 843842c6f6c..67607ccca37 100644 --- a/_ml-commons-plugin/cluster-settings.md +++ b/_ml-commons-plugin/cluster-settings.md @@ -528,7 +528,7 @@ plugins.ml_commons.memory_feature_enabled: true ## Enable agentic memory -When set to `true`, this setting enables [agentic memory]({{site.url}}{{site.baseurl}}/agents-tools/agentic-memory/), which provides advanced memory management for AI agents including session memory, working memory, long-term memory, and memory history with namespace-based organization. +When set to `true`, this setting enables [agentic memory]({{site.url}}{{site.baseurl}}/agents-tools/agentic-memory/), which provides advanced memory management for AI agents, including session memory, working memory, long-term memory, and memory history with namespace-based organization. ### Setting From 32d60a65ac0cc3c087a8dc4254fc62d70a53fc64 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 13 Oct 2025 14:56:17 -0400 Subject: [PATCH 20/27] Doc review part 3 Signed-off-by: Fanit Kolchina --- .../{agents-tools => }/agentic-memory.md | 11 ++++++----- _ml-commons-plugin/agents-tools/index.md | 2 +- .../api/agentic-memory-apis/add-memory.md | 10 +++++----- .../agentic-memory-apis/create-memory-container.md | 8 +++----- .../api/agentic-memory-apis/delete-memory.md | 6 +++--- .../api/agentic-memory-apis/get-memory.md | 6 +++--- _ml-commons-plugin/api/agentic-memory-apis/index.md | 2 +- .../api/agentic-memory-apis/search-memory.md | 2 +- .../api/agentic-memory-apis/update-memory.md | 2 +- _ml-commons-plugin/api/index.md | 2 +- _ml-commons-plugin/cluster-settings.md | 2 +- 11 files changed, 26 insertions(+), 27 deletions(-) rename _ml-commons-plugin/{agents-tools => }/agentic-memory.md (94%) diff --git a/_ml-commons-plugin/agents-tools/agentic-memory.md b/_ml-commons-plugin/agentic-memory.md similarity index 94% rename from _ml-commons-plugin/agents-tools/agentic-memory.md rename to _ml-commons-plugin/agentic-memory.md index 9fff4e6c2a1..1ab3de95d02 100644 --- a/_ml-commons-plugin/agents-tools/agentic-memory.md +++ b/_ml-commons-plugin/agentic-memory.md @@ -1,8 +1,7 @@ --- layout: default title: Agentic memory -parent: Agents and tools -nav_order: 30 +nav_order: 60 --- # Agentic memory @@ -20,6 +19,9 @@ Using agentic memory, you can build AI agents that can do the following: - Track agent execution traces for debugging and analysis - Organize information across different users, sessions, or agent instances +Currently, agentic memory is designed for integration with external agent frameworks like LangChain and LangGraph. OpenSearch's internal [agents]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/) cannot interact with agentic memory. +{: .note} + ## Memory containers Agentic memory is organized into _memory containers_ that hold all memory types for a specific use case, such as a chatbot, research assistant, or customer service agent. @@ -28,8 +30,8 @@ Each container can be configured with the following components: - Text embedding models: For semantic search capabilities. - Large language models (LLMs): For inference and knowledge extraction. -- [Memory processing strategies](#memory-processing-strategies): For automatic content organization. -- [Namespaces](#namespaces): For organizing memories within containers. +- [Memory processing strategies](#memory-processing-strategies): For defining how memories are processed or extracted. +- [Namespaces](#namespaces): For partitioning and isolating memories by context, user, agent, or session. For example, to create a memory container with two strategies, send the following request: @@ -203,6 +205,5 @@ For detailed API documentation, see [Agentic Memory APIs]({{site.url}}{{site.bas ## Next steps -- Learn about [agent types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/) and how to integrate agentic memory. - Explore [memory container configuration]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container/) options. - Review the complete [Agentic Memory API reference]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/). \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/index.md b/_ml-commons-plugin/agents-tools/index.md index 334d92d127e..13b23ddd129 100644 --- a/_ml-commons-plugin/agents-tools/index.md +++ b/_ml-commons-plugin/agents-tools/index.md @@ -20,5 +20,5 @@ A _tool_ performs a set of specific tasks. Some examples of tools are the [`Vect ## Agentic memory -Agents can use [agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agentic-memory/) to learn, remember, and reason over structured information across conversations. This enables agents to maintain context, learn user preferences, and improve their responses over time. +Agents can use [agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/) to learn, remember, and reason over structured information across conversations. This enables agents to maintain context, learn user preferences, and improve their responses over time. diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 1d124110034..86506809cbc 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -11,7 +11,7 @@ nav_order: 40 {: .label .label-purple } -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 specify different [payload types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#payload-types) and control [inference mode]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#inference-mode) for how OpenSearch processes the memory. +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 specify different [payload types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#payload-types) and control [inference mode]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#inference-mode) for how OpenSearch processes the memory. Once an agentic memory is created, provide its `memory_id` to other APIs. @@ -38,11 +38,11 @@ Field | Data type | Required/Optional | Description `messages` | Array | Conditional | A list of messages for a `conversational` payload. Each message requires a `content` field and may include a `role` (commonly, `user` or `assistant`) when `infer` is set to `true`. Required when `payload_type` is `conversational`. `structured_data` | Object | Conditional | Structured data content for data memory. Required when `payload_type` is `data`. `binary_data` | String | Optional | Binary data content encoded as a Base64 string for binary payloads. -`payload_type` | String | Required | The type of payload. Valid values are `conversational` or `data`. See [Payload types](#payload-types). -`namespace` | Object | Optional | The [namespace]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#namespaces) context for organizing memories (for example, `user_id`, `session_id`, or `agent_id`). If `session_id` is not specified in the `namespace` field, a new session with a new session ID is created. +`payload_type` | String | Required | The type of payload. Valid values are `conversational` or `data`. See [Payload types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#payload-types). +`namespace` | Object | Optional | The [namespace]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#namespaces) context for organizing memories (for example, `user_id`, `session_id`, or `agent_id`). If `session_id` is not specified in the `namespace` field, a new session with a new session ID is created. `metadata` | Object | Optional | Additional metadata for the memory (for example, `status`, `branch`, or custom fields). `tags` | Object | Optional | Tags for categorizing and organizing memories. -`infer` | Boolean | Optional | Whether to use a large language model (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 a memory. See [Inference mode](#inference-mode). +`infer` | Boolean | Optional | Whether to use a large language model (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 a memory. See [Inference mode]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#inference-mode). ## Example request: Conversational payload @@ -161,7 +161,7 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories "data_type": "trace" }, "infer": false, - "payload_type": "conversational" + "payload_type": "data" } ``` {% include copy-curl.html %} diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index 794d4723160..94ab43f01be 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -10,13 +10,11 @@ nav_order: 10 **Introduced 3.3** {: .label .label-purple } -Use this API to create a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#memory-containers) to hold agentic memories. The container can have two model types associated with it: +Use this API to create a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-containers) to hold agentic memories. The container can have two model types associated with it: - 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. - 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. Long-term memory requires both an LLM model and embedding model to be configured. -**Note**: LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is configured for Amazon Bedrock Converse API format (`"$.output.message.content[0].text"`). - For more information, see [Integrating ML models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/integrating-ml-models/). LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). @@ -164,7 +162,7 @@ Field | Data type | Required/Optional | Description `disable_session` | Boolean | Optional | If disabled, no session will be persisted. Default is `true`, so the session will not be persisted by default. `max_infer_size` | int | Optional | Controls the top k number of similar existing memories retrieved during memory consolidation to make ADD/UPDATE/DELETE decisions. `index_settings` | Object | Optional | Custom OpenSearch index settings for the memory storage indexes that will be created for this container. Each memory type (`sessions`, `working`, `long_term`, and `history`) uses its own index. See [Index settings](#index-settings). -`strategies` | Array | Optional | An array of [memory processing strategies]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#memory-processing-strategies). See [The `strategies` array](#the-strategies-array). +`strategies` | Array | Optional | An array of [memory processing strategies]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-processing-strategies). See [The `strategies` array](#the-strategies-array). `parameters` | Object | Optional | Global parameters for the memory container. See [The `parameters` object](#the-parameters-object). ### Index settings @@ -216,7 +214,7 @@ Each strategy in the `strategies` array supports the following fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- `type` | String | Required | The strategy type. Valid values are `SEMANTIC`, `USER_PREFERENCE`, and `SUMMARY`. -`namespace` | Array | Required | An array of [namespace]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#namespaces) dimensions for organizing memories (for example, `["user_id"]` or `["agent_id", "session_id"]`). +`namespace` | Array | Required | An array of [namespace]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#namespaces) dimensions for organizing memories (for example, `["user_id"]` or `["agent_id", "session_id"]`). `configuration` | Object | Optional | Strategy-specific configuration. See [The strategy `configuration` object](#the-strategy-configuration-object). `enabled` | Boolean | Optional | Whether to enable the strategy in the memory container. Default is `true`. diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md index 6a5cf6d97f0..99779994a8d 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md @@ -10,11 +10,11 @@ nav_order: 53 **Introduced 3.3** {: .label .label-purple } -Use this API to delete a specific memory by its type and ID or to delete memories matching a query. This unified API supports deleting memories of any [memory type]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#memory-types): `sessions`, `working`, `long-term`, or `history`. +Use this API to delete a specific memory by its type and ID or to delete memories matching a query. This unified API supports deleting memories of any [memory type]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-types): `sessions`, `working`, `long-term`, or `history`. -## Delete a memory by type or ID +## Delete a memory by type and ID -Use this API to delete a memory by type or ID. +Use this API to delete a memory by type and ID. ### Endpoints diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md index 84fe1c18ca1..b647325f0f6 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md @@ -10,7 +10,7 @@ nav_order: 51 **Introduced 3.3** {: .label .label-purple } -Use this API to retrieve a specific memory by its type and ID. This unified API supports the four [memory types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#memory-types): `sessions`, `working`, `long-term`, and `history`. +Use this API to retrieve a specific memory by its type and ID. This unified API supports the four [memory types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-types): `sessions`, `working`, `long-term`, and `history`. ## Endpoints @@ -176,7 +176,7 @@ The following table lists all long-term memory response body fields. | `memory` | String | The extracted long-term memory fact. | | `strategy_type` | String | The type of memory strategy used (for example, `SEMANTIC`, `SUMMARY`, or `USER_PREFERENCE`). | | `namespace` | Object | The namespace context for this memory. | -| `namespace_size` | Integer | The namespace size. | +| `namespace_size` | Integer | The number of namespaces. | | `tags` | Object | Associated tags for categorization. | | `created_time` | Long | The timestamp when the memory was created. | | `last_updated_time` | Long | The timestamp when the memory was last updated. | @@ -208,6 +208,6 @@ The following table lists all history response body fields. | `after` | Object | The memory content after the operation. | | `before` | Object | The memory content before the operation (for `UPDATE` operations). | | `namespace` | Object | The namespace context for this memory. | -| `namespace_size` | Integer | The namespace size. | +| `namespace_size` | Integer | The number of namespaces. | | `tags` | Object | Associated tags for categorization. | | `created_time` | Long | The timestamp of when the operation occurred. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/index.md b/_ml-commons-plugin/api/agentic-memory-apis/index.md index 1bb0e29156d..8529aa24a3b 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/index.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/index.md @@ -13,7 +13,7 @@ redirect_from: **Introduced 3.3** {: .label .label-purple } -Agentic memory APIs provide persistent memory management for AI agents. For an overview of concepts, use cases, and getting started information, see [Agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agentic-memory/). +Agentic memory APIs provide persistent memory management for AI agents. For an overview of concepts, use cases, and getting started information, see [Agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/). ## Disabling agentic memory APIs diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md index 9033ffeff8c..5b764edeb60 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md @@ -10,7 +10,7 @@ nav_order: 54 **Introduced 3.3** {: .label .label-purple } -Use this API to search for memories of a specific type within a memory container. This unified API supports searching `sessions`, `working`, `long-term`, and `history` [memory types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#memory-types). +Use this API to search for memories of a specific type within a memory container. This unified API supports searching `sessions`, `working`, `long-term`, and `history` [memory types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-types). ## Endpoints diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md index 17759f9cbf7..91b3f89bf26 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md @@ -10,7 +10,7 @@ nav_order: 52 **Introduced 3.3** {: .label .label-purple } -Use this API to update a specific memory by its type and ID. This unified API supports updating `sessions`, `working`, and `long-term` [memory types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/#memory-types). `history` memory does not support updates. +Use this API to update a specific memory by its type and ID. This unified API supports updating `sessions`, `working`, and `long-term` [memory types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-types). `history` memory does not support updates. ## Endpoints diff --git a/_ml-commons-plugin/api/index.md b/_ml-commons-plugin/api/index.md index 659b939954c..3a3d47559c6 100644 --- a/_ml-commons-plugin/api/index.md +++ b/_ml-commons-plugin/api/index.md @@ -32,4 +32,4 @@ OpenSearch provides two different memory systems: - **[Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/index/)** -- Simple conversation history storage for [conversational search]({{site.url}}{{site.baseurl}}/search-plugins/conversational-search/). Stores question/answer pairs chronologically without processing or learning. -- **[Agentic Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/)** -- Intelligent memory system for AI agents. Uses large language models (LLMs) to extract knowledge, learn user preferences, and maintain context across sessions. For conceptual information, see [Agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agentic-memory/). \ No newline at end of file +- **[Agentic Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/)** -- Intelligent memory system for AI agents. Uses large language models (LLMs) to extract knowledge, learn user preferences, and maintain context across sessions. For conceptual information, see [Agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/). \ No newline at end of file diff --git a/_ml-commons-plugin/cluster-settings.md b/_ml-commons-plugin/cluster-settings.md index 67607ccca37..65518bdd333 100644 --- a/_ml-commons-plugin/cluster-settings.md +++ b/_ml-commons-plugin/cluster-settings.md @@ -528,7 +528,7 @@ plugins.ml_commons.memory_feature_enabled: true ## Enable agentic memory -When set to `true`, this setting enables [agentic memory]({{site.url}}{{site.baseurl}}/agents-tools/agentic-memory/), which provides advanced memory management for AI agents, including session memory, working memory, long-term memory, and memory history with namespace-based organization. +When set to `true`, this setting enables [agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/), which provides advanced memory management for AI agents, including session memory, working memory, long-term memory, and memory history with namespace-based organization. ### Setting From e09a08eb8558da86a1091c1c1f81b82f0c8eaad0 Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Mon, 13 Oct 2025 15:07:09 -0400 Subject: [PATCH 21/27] Update _ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md Signed-off-by: Nathan Bower --- .../api/agentic-memory-apis/create-memory-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index 94ab43f01be..13f635c8a8f 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -10,7 +10,7 @@ nav_order: 10 **Introduced 3.3** {: .label .label-purple } -Use this API to create a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-containers) to hold agentic memories. The container can have two model types associated with it: +Use this API to create a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-containers) to store agentic memories. The container can have two model types associated with it: - 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. - 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. Long-term memory requires both an LLM model and embedding model to be configured. From 77751797a9c7a8c67c8f6debc3265032af31ae53 Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Mon, 13 Oct 2025 16:08:01 -0400 Subject: [PATCH 22/27] Apply suggestions from code review Signed-off-by: Nathan Bower --- _ml-commons-plugin/api/agentic-memory-apis/update-memory.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md index 91b3f89bf26..20e6b142612 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md @@ -36,8 +36,6 @@ The request fields vary depending on the memory type being updated. All request The following table lists all session memory request body fields. -| Field | Data type | Description | -| :--- | :--- | :--- | | Field | Data type | Description | |:-----------|:----------------------| :--- | | `summary` | String | The summary of the session. From a097c3480babbb2f0bb3a837d322532c21a38a7b Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Mon, 13 Oct 2025 16:12:09 -0400 Subject: [PATCH 23/27] Update _ml-commons-plugin/api/agentic-memory-apis/add-memory.md Co-authored-by: Yaliang Wu Signed-off-by: Nathan Bower --- _ml-commons-plugin/api/agentic-memory-apis/add-memory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 86506809cbc..42201029a50 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -39,7 +39,7 @@ Field | Data type | Required/Optional | Description `structured_data` | Object | Conditional | Structured data content for data memory. Required when `payload_type` is `data`. `binary_data` | String | Optional | Binary data content encoded as a Base64 string for binary payloads. `payload_type` | String | Required | The type of payload. Valid values are `conversational` or `data`. See [Payload types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#payload-types). -`namespace` | Object | Optional | The [namespace]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#namespaces) context for organizing memories (for example, `user_id`, `session_id`, or `agent_id`). If `session_id` is not specified in the `namespace` field, a new session with a new session ID is created. +`namespace` | Object | Optional | The [namespace]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#namespaces) context for organizing memories (for example, `user_id`, `session_id`, or `agent_id`). If `session_id` is not specified in the `namespace` field and `disable_session: false` (default is `true`), a new session with a new session ID is created. `metadata` | Object | Optional | Additional metadata for the memory (for example, `status`, `branch`, or custom fields). `tags` | Object | Optional | Tags for categorizing and organizing memories. `infer` | Boolean | Optional | Whether to use a large language model (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 a memory. See [Inference mode]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#inference-mode). From 8ad80e2fc67bd558eba65808507d893ada350826 Mon Sep 17 00:00:00 2001 From: Nathalie Jonathan <143617992+nathaliellenaa@users.noreply.github.com> Date: Mon, 13 Oct 2025 13:39:15 -0700 Subject: [PATCH 24/27] Add execute tool API doc (#11214) * Add execute tool API doc Signed-off-by: Nathalie Jonathan * Address comments Signed-off-by: Nathalie Jonathan * Apply suggestions from code review Signed-off-by: Nathan Bower * Doc review Signed-off-by: Fanit Kolchina * Update _ml-commons-plugin/agents-tools/tools/search-index-tool.md Signed-off-by: Nathan Bower * Apply suggestions from code review Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --------- Signed-off-by: Nathalie Jonathan Signed-off-by: Nathan Bower Signed-off-by: Fanit Kolchina Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Nathan Bower Co-authored-by: Fanit Kolchina Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- .../agents-tools/tools/agent-tool.md | 6 +- .../agents-tools/tools/connector-tool.md | 6 +- .../tools/create-anomaly-detector.md | 4 + .../tools/data-distribution-tool.md | 4 + .../agents-tools/tools/index-mapping-tool.md | 6 +- .../agents-tools/tools/index.md | 2 + .../agents-tools/tools/list-index-tool.md | 6 +- .../tools/log-pattern-analysis-tool.md | 6 +- .../agents-tools/tools/log-pattern-tool.md | 6 +- .../agents-tools/tools/ml-model-tool.md | 8 +- .../agents-tools/tools/neural-sparse-tool.md | 5 + .../agents-tools/tools/ppl-tool.md | 8 +- .../agents-tools/tools/query-planning-tool.md | 6 +- .../agents-tools/tools/rag-tool.md | 6 +- .../agents-tools/tools/search-alerts-tool.md | 4 + .../tools/search-anomaly-detectors.md | 4 + .../tools/search-anomaly-results.md | 4 + .../agents-tools/tools/search-index-tool.md | 6 +- .../tools/search-monitors-tool.md | 4 + .../agents-tools/tools/vector-db-tool.md | 4 + .../agents-tools/tools/visualization-tool.md | 6 +- .../agents-tools/tools/web-search-tool.md | 6 +- _ml-commons-plugin/api/execute-tool.md | 126 ++++++++++++++++++ _ml-commons-plugin/api/index.md | 1 + _ml-commons-plugin/api/profile.md | 2 +- _ml-commons-plugin/api/stats.md | 2 +- 26 files changed, 231 insertions(+), 17 deletions(-) create mode 100644 _ml-commons-plugin/api/execute-tool.md diff --git a/_ml-commons-plugin/agents-tools/tools/agent-tool.md b/_ml-commons-plugin/agents-tools/tools/agent-tool.md index 272af51e4d3..e0e4ec09c08 100644 --- a/_ml-commons-plugin/agents-tools/tools/agent-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/agent-tool.md @@ -104,4 +104,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/connector-tool.md b/_ml-commons-plugin/agents-tools/tools/connector-tool.md index dfe4770932c..ace94c38440 100644 --- a/_ml-commons-plugin/agents-tools/tools/connector-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/connector-tool.md @@ -165,4 +165,8 @@ When running the agent, you can define any parameter needed for the API call in "request_body": "{ \"number1\":\"${parameters.number1}\", \"number2\":\"${parameters.number2}\" }" } ] -``` \ No newline at end of file +``` + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md b/_ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md index a66d85a5cc7..404ad7eacf8 100644 --- a/_ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md +++ b/_ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md @@ -167,3 +167,7 @@ The following table lists the available tool parameters for running the agent. Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `index` | String | Required | The index name. Supports wildcards (for example, `weblogs-*`). If wildcards are used, then the tool fetches mappings from the first resolved index and sends them to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/data-distribution-tool.md b/_ml-commons-plugin/agents-tools/tools/data-distribution-tool.md index 6f35f900411..26ccbbe17ea 100644 --- a/_ml-commons-plugin/agents-tools/tools/data-distribution-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/data-distribution-tool.md @@ -195,6 +195,10 @@ The following table lists the available tool parameters for running the agent. | `dsl` | String | Optional | A complete raw DSL query as a JSON string. If provided, takes precedence over the `filter` parameter. | | `ppl` | String | Optional | A complete PPL statement without time information. Used when `queryType` is `ppl`. | +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. + ## Limitations The Data Distribution tool has the following limitations: diff --git a/_ml-commons-plugin/agents-tools/tools/index-mapping-tool.md b/_ml-commons-plugin/agents-tools/tools/index-mapping-tool.md index 8649d2d74d7..39cc6f91091 100644 --- a/_ml-commons-plugin/agents-tools/tools/index-mapping-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/index-mapping-tool.md @@ -117,4 +117,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. -`index` | Array | Optional | A comma-delimited list of one or more indexes for which to obtain mapping and setting information. Default is an empty list, which means all indexes. \ No newline at end of file +`index` | Array | Optional | A comma-delimited list of one or more indexes for which to obtain mapping and setting information. Default is an empty list, which means all indexes. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/index.md b/_ml-commons-plugin/agents-tools/tools/index.md index 94b0a28ba06..ff4a98f53e9 100644 --- a/_ml-commons-plugin/agents-tools/tools/index.md +++ b/_ml-commons-plugin/agents-tools/tools/index.md @@ -31,6 +31,8 @@ Specify a tool by providing its `type`, `parameters`, and, optionally, a `descri Each tool takes a list of parameters specific to that tool. In the preceding example, the `AgentTool` takes an `agent_id` of the agent it will run. For a list of parameters, see each tool's documentation. +You can also run tools directly without creating an agent using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/), which is useful for testing individual tools or performing standalone operations. + |Tool | Description | |:--- |:--- | |[`AgentTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/agent-tool/) |Runs any agent. | diff --git a/_ml-commons-plugin/agents-tools/tools/list-index-tool.md b/_ml-commons-plugin/agents-tools/tools/list-index-tool.md index 79d9d0d7b0d..41c02dbe497 100644 --- a/_ml-commons-plugin/agents-tools/tools/list-index-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/list-index-tool.md @@ -130,4 +130,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool.md b/_ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool.md index 3249fa2cd6f..0d6a7f334e9 100644 --- a/_ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool.md @@ -14,7 +14,7 @@ grand_parent: Agents and tools {: .label .label-purple } -The `LogPatternAnalysisTool` performs an advanced log analysis by detecting anomalous log patterns and sequences through comparative analysis between baseline and selection time ranges. It supports the following analysis modes: +The `LogPatternAnalysisTool` performs an advanced log analysis by detecting anomalous log patterns and sequences through comparative analysis between baseline and selection time ranges. It supports the following analysis modes: - Log sequence analysis (with trace correlation) - Log pattern difference analysis @@ -192,6 +192,10 @@ The following table lists the available tool parameters for running the agent. | `selectionTimeRangeStart` | String | Required | The start time for the analysis target period, in UTC date string format (for example, `2025-06-24 07:50:26`). | | `selectionTimeRangeEnd` | String | Required | The end time for the analysis target period, in UTC date string format (for example, `2025-06-24 07:55:56`). | +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. + ## Limitations The Log Pattern Analysis tool has the following limitations: diff --git a/_ml-commons-plugin/agents-tools/tools/log-pattern-tool.md b/_ml-commons-plugin/agents-tools/tools/log-pattern-tool.md index 3bbd09b1694..a179fa3b96a 100644 --- a/_ml-commons-plugin/agents-tools/tools/log-pattern-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/log-pattern-tool.md @@ -117,4 +117,8 @@ Parameter | Type | Required/Optional | Description :--- | :--- |:-----------------------| :--- | `index` | String | Required for DSL queries | The index to search for pattern analysis. | | `input` | String | Required for DSL queries | A DSL query JSON as a string. If both `input` and `ppl` are provided, `input` (DSL) takes precedence. | -| `ppl` | String | Required for PPL queries | A PPL query string. Ignored if `input` is also provided. | \ No newline at end of file +| `ppl` | String | Required for PPL queries | A PPL query string. Ignored if `input` is also provided. | + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/ml-model-tool.md b/_ml-commons-plugin/agents-tools/tools/ml-model-tool.md index ceeda405283..048028d8063 100644 --- a/_ml-commons-plugin/agents-tools/tools/ml-model-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/ml-model-tool.md @@ -14,7 +14,7 @@ plugins.ml_commons.rag_pipeline_feature_enabled: true {: .label .label-purple } -The `MLModelTool` runs a machine learning (ML) model and returns inference results. +The `MLModelTool` runs a machine learning (ML) model and returns inference results. ## Step 1: Create a connector for a model @@ -164,4 +164,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/neural-sparse-tool.md b/_ml-commons-plugin/agents-tools/tools/neural-sparse-tool.md index b78d3d641ed..9be67422c0a 100644 --- a/_ml-commons-plugin/agents-tools/tools/neural-sparse-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/neural-sparse-tool.md @@ -221,3 +221,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/ppl-tool.md b/_ml-commons-plugin/agents-tools/tools/ppl-tool.md index 72d8ba30b5b..2cb1cc181fa 100644 --- a/_ml-commons-plugin/agents-tools/tools/ppl-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/ppl-tool.md @@ -12,7 +12,7 @@ grand_parent: Agents and tools **Introduced 2.13** {: .label .label-purple } -The `PPLTool` translates natural language into a PPL query. The tool provides an `execute` flag to specify whether to run the query. If you set the flag to `true`, the `PPLTool` runs the query and returns the query and the results. +The `PPLTool` translates natural language into a PPL query. The tool provides an `execute` flag to specify whether to run the query. If you set the flag to `true`, the `PPLTool` runs the query and returns the query and the results. ## Prerequisite @@ -201,4 +201,8 @@ Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `index` | String | Required | The index on which to run the PPL query. `question` | String | Required | The natural language question to send to the LLM. -`verbose` | Boolean | Optional | Whether to provide verbose output. Default is `false`. \ No newline at end of file +`verbose` | Boolean | Optional | Whether to provide verbose output. Default is `false`. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md b/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md index 1bec951294d..9d3518d1014 100644 --- a/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md @@ -14,7 +14,7 @@ grand_parent: Agents and tools {: .label .label-purple } -The `QueryPlanningTool` generates an OpenSearch query domain-specific language (DSL) query from a natural language question. It is a core component of [agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/index/), which enables natural language query processing through agent-driven workflows. +The `QueryPlanningTool` generates an OpenSearch query domain-specific language (DSL) query from a natural language question. It is a core component of [agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/index/), which enables natural language query processing through agent-driven workflows. The `QueryPlanningTool` supports two approaches for generating DSL queries from natural language questions: @@ -522,6 +522,10 @@ GIVE THE OUTPUT PART ONLY IN YOUR RESPONSE (a single JSON object) Output: ``` +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. + ## Related pages - [Agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/index) \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/rag-tool.md b/_ml-commons-plugin/agents-tools/tools/rag-tool.md index 24e95286a4e..9b22798ec18 100644 --- a/_ml-commons-plugin/agents-tools/tools/rag-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/rag-tool.md @@ -144,4 +144,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-alerts-tool.md b/_ml-commons-plugin/agents-tools/tools/search-alerts-tool.md index 76f9e4b4dc1..c9ce8994cba 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-alerts-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/search-alerts-tool.md @@ -122,3 +122,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-anomaly-detectors.md b/_ml-commons-plugin/agents-tools/tools/search-anomaly-detectors.md index 9f31dea057f..c0978857c25 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-anomaly-detectors.md +++ b/_ml-commons-plugin/agents-tools/tools/search-anomaly-detectors.md @@ -107,3 +107,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-anomaly-results.md b/_ml-commons-plugin/agents-tools/tools/search-anomaly-results.md index 2f2728e32d3..2fb7d98c967 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-anomaly-results.md +++ b/_ml-commons-plugin/agents-tools/tools/search-anomaly-results.md @@ -121,3 +121,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-index-tool.md b/_ml-commons-plugin/agents-tools/tools/search-index-tool.md index b0235228931..50bab482ea5 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-index-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/search-index-tool.md @@ -117,4 +117,8 @@ The following table lists all tool parameters that are available when registerin Parameter | Type | Description :--- | :--- | :--- -`input`| String | The index name and the query to use for search, in JSON format. The `index` parameter contains the name of the index and the `query` parameter contains the query formatted in Query DSL. For example, `"{\"index\": \"opensearch_dashboards_sample_data_ecommerce\", \"query\": {\"size\": 22, \"_source\": \"category\"}}"`. The `input` parameter and the `index` and `query` parameters it contains are required. \ No newline at end of file +`input`| String | The index name and the query to use for search, in JSON format. The `index` parameter contains the name of the index, and the `query` parameter contains the query formatted in Query DSL. For example, `"{\"index\": \"opensearch_dashboards_sample_data_ecommerce\", \"query\": {\"size\": 22, \"_source\": \"category\"}}"`. The `input` parameter and the `index` and `query` parameters it contains are required. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-monitors-tool.md b/_ml-commons-plugin/agents-tools/tools/search-monitors-tool.md index 77b51d4964e..853e6e3fd8f 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-monitors-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/search-monitors-tool.md @@ -122,3 +122,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/vector-db-tool.md b/_ml-commons-plugin/agents-tools/tools/vector-db-tool.md index 61c6028f283..8e8753e101f 100644 --- a/_ml-commons-plugin/agents-tools/tools/vector-db-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/vector-db-tool.md @@ -234,3 +234,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/visualization-tool.md b/_ml-commons-plugin/agents-tools/tools/visualization-tool.md index 98457932c2f..769f9325dce 100644 --- a/_ml-commons-plugin/agents-tools/tools/visualization-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/visualization-tool.md @@ -12,7 +12,7 @@ grand_parent: Agents and tools **Introduced 2.13** {: .label .label-purple } -Use the `VisualizationTool` to find visualizations relevant to a question. +Use the `VisualizationTool` to find visualizations relevant to a question. ## Step 1: Register a flow agent that will run the VisualizationTool @@ -101,3 +101,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/web-search-tool.md b/_ml-commons-plugin/agents-tools/tools/web-search-tool.md index 8cc5814a5f1..2f163320411 100644 --- a/_ml-commons-plugin/agents-tools/tools/web-search-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/web-search-tool.md @@ -319,4 +319,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/api/execute-tool.md b/_ml-commons-plugin/api/execute-tool.md new file mode 100644 index 00000000000..865d79bd2a0 --- /dev/null +++ b/_ml-commons-plugin/api/execute-tool.md @@ -0,0 +1,126 @@ +--- +layout: default +title: Execute tool +parent: ML Commons APIs +nav_order: 100 +--- + +# Execute Tool API +**Introduced 3.3** +{: .label .label-purple } + +The Execute Tool API allows you to run individual tools directly without creating an agent first. This API is particularly beneficial for applications requiring quick, single-tool operations where the overhead of agent creation and management is unnecessary. + +## Use cases + +The Execute Tool API is ideal for: + +- **Direct tool execution**: Run specific tools like search, data analysis, or retrieval operations without agent setup. +- **Testing and debugging**: Quickly test tool functionality during development. +- **Lightweight integrations**: Integrate specific OpenSearch capabilities into applications without full agent workflows. +- **Standalone operations**: Perform single tasks that don't require conversation memory or complex orchestration. + +## Supported tools + +This API supports all available OpenSearch tools. Each tool can be executed independently with its specific parameters. + +For more information regarding the list of available tools, see [Tools]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/index/). + +## Endpoint + +```json +POST /_plugins/_ml/tools/_execute/ +``` + +The `` parameter refers to the predefined tool type name, such as `PPLTool`, `SearchIndexTool`, or `VectorDBTool`,---not a custom tool name that you define. +{: .note} + +## Request body fields + +The following table lists all request body fields. + +| Field | Data type | Required | Description | +| :--- | :--- | :--- | :--- | +| `parameters` | Object | Yes | Contains tool-specific parameters that vary depending on the tool being executed. Each tool requires different parameters based on its functionality. | + +### Parameter structure + +The `parameters` object combines the parameters used during tool registration and tool execution. The specific fields depend on the tool being executed. + +To determine the required parameters for a specific tool, refer to the individual tool documentation in the [Tools]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/index/) section. + +| Component | Description | +|:-------------------------|:-----------------------------------------------| +| Tool registration parameters | Parameters specified during tool registration. | +| Tool execution parameters | Parameters specified during tool execution. | + +## Example requests + +The following are examples of both simple and complex tool execution. + +### Example 1: Simple tool execution + +```json +POST /_plugins/_ml/tools/_execute/ListIndexTool +{ + "parameters": { + "question": "How many indices do I have?" + } +} +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "result": """row,health,status,index,uuid,pri(number of primary shards),rep(number of replica shards),docs.count(number of available documents),docs.deleted(number of deleted documents),store.size(store size of primary and replica shards),pri.store.size(store size of primary shards) +1,yellow,open,movies,kKcJKu2aT0C9uwJIPP4hxw,2,1,2,0,7.8kb,7.8kb +2,green,open,.plugins-ml-config,h8ovp_KFTq6_zvcBEn2kvg,1,0,1,0,4kb,4kb +3,green,open,.plugins-ml-agent,1oGlUBCIRAGXLbLv27Qg8w,1,0,1,0,8kb,8kb +""" + } + ] + } + ] +} +``` + +### Example 2: Complex tool execution + +```json +POST /_plugins/_ml/tools/_execute/PPLTool +{ + "parameters": { + "question": "what's the population of Seattle in 2021?", + "index": "test-population", + "model_id": "1TuQQ5gBMJhRgCqgSV79" + } +} + +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "dataAsMap": { + "result":"{\"ppl\":\"source\=test-population | where QUERY_STRING([\'population_description\'], \'Seattle\') AND QUERY_STRING([\'population_description\'], \'2021\')\",\"executionResult\":\"{\\n \\\"schema\\\": [\\n {\\n \\\"name\\\": \\\"population_description\\\",\\n \\\"type\\\": \\\"string\\\"\\n }\\n ],\\n \\\"datarows\\\": [],\\n \\\"total\\\": 0,\\n \\\"size\\\": 0\\n}\"}" + } + } + ] + } + ] +} +``` \ No newline at end of file diff --git a/_ml-commons-plugin/api/index.md b/_ml-commons-plugin/api/index.md index 3a3d47559c6..ed7ef546a4c 100644 --- a/_ml-commons-plugin/api/index.md +++ b/_ml-commons-plugin/api/index.md @@ -21,6 +21,7 @@ OpenSearch supports the following machine learning (ML) APIs: - [Agentic Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/) - [Controller APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/controller-apis/index/) - [Execute Algorithm API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-algorithm/) +- [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/) - [Tasks APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/tasks-apis/index/) - [Profile API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/profile/) - [Stats API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/stats/) diff --git a/_ml-commons-plugin/api/profile.md b/_ml-commons-plugin/api/profile.md index dc9ec94cbe8..f281c25dcf3 100644 --- a/_ml-commons-plugin/api/profile.md +++ b/_ml-commons-plugin/api/profile.md @@ -2,7 +2,7 @@ layout: default title: Profile parent: ML Commons APIs -nav_order: 100 +nav_order: 110 --- # Profile API diff --git a/_ml-commons-plugin/api/stats.md b/_ml-commons-plugin/api/stats.md index 45b145effe6..43b31b38061 100644 --- a/_ml-commons-plugin/api/stats.md +++ b/_ml-commons-plugin/api/stats.md @@ -2,7 +2,7 @@ layout: default title: Stats parent: ML Commons APIs -nav_order: 110 +nav_order: 120 --- # Stats API From 5bec8d3c703e9cf3951eaddebf679bd2c72d2d49 Mon Sep 17 00:00:00 2001 From: Dhrubo Saha Date: Mon, 13 Oct 2025 16:42:11 -0700 Subject: [PATCH 25/27] add create-session Signed-off-by: Dhrubo Saha --- .../api/agentic-memory-apis/add-memory.md | 6 +- .../create-memory-container.md | 2 +- .../api/agentic-memory-apis/create-session.md | 91 +++++++++++++++++++ .../delete-memory-container.md | 27 ++++++ .../api/agentic-memory-apis/index.md | 1 + 5 files changed, 123 insertions(+), 4 deletions(-) create mode 100644 _ml-commons-plugin/api/agentic-memory-apis/create-session.md diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 42201029a50..71ae1567400 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -78,7 +78,7 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories ``` {% include copy-curl.html %} -## Example response: Conversation memory +## Example response: Conversation payload ```json { @@ -116,7 +116,7 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories ``` {% include copy-curl.html %} -## Example response: Data memory +## Example response: Data payload ```json { @@ -124,7 +124,7 @@ POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories } ``` -## Example request: Storing trace data +## Example request: Storing tool invocation data To store agent trace data in working memory, send the following request: diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index 13f635c8a8f..bc48d173541 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -17,7 +17,7 @@ Use this API to create a [memory container]({{site.url}}{{site.baseurl}}/ml-comm For more information, see [Integrating ML models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/integrating-ml-models/). -LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). +LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). If user use OpenAI GPT model, should configure llm_result_path as `$.choices[0].message.content` {: .note} Once a memory container is created, provide its `memory_container_id` to other APIs. diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-session.md b/_ml-commons-plugin/api/agentic-memory-apis/create-session.md new file mode 100644 index 00000000000..13623718136 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-session.md @@ -0,0 +1,91 @@ +--- +layout: default +title: Create session +parent: Agentic Memory APIs +grand_parent: ML Commons APIs +nav_order: 40 +--- + +# Create session +**Introduced 3.3** +{: .label .label-purple } + +Use this API to create a new session in a memory container. Sessions represent distinct interaction contexts between users and agents. + +## Path and HTTP methods + +```json +POST /_plugins/_ml/memory_containers//memories/sessions +``` + +## Path parameters + +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container where the session will be created. | + +## Request fields + +| Field | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `session_id` | String | Optional | Custom session ID. If provided, this ID will be used for the session. If not provided, a random ID will be generated. | +| `summary` | String | Optional | A summary or description of the session. | +| `metadata` | Object | Optional | Additional metadata for the session as key-value pairs. | +| `namespace` | Object | Optional | Namespace information for organizing the session. | + +## Example requests + +### Create session with custom ID + +```json +POST /_plugins/_ml/memory_containers/{{mem_container_id}}/memories/sessions +{ + "session_id": "abc123", + "metadata": { + "key1": "value1" + } +} +``` + +### Create session with auto-generated ID + +```json +POST /_plugins/_ml/memory_containers/{{mem_container_id}}/memories/sessions +{ + "summary": "This is a test session", + "metadata": { + "key1": "value1" + }, + "namespace": { + "user_id": "bob" + } +} +``` +{% include copy-curl.html %} + +## Example responses + +### Response for custom session ID + +```json +{ + "session_id": "abc123", + "status": "created" +} +``` + +### Response for auto-generated session ID + +```json +{ + "session_id": "jTYm35kBt8CyICnjxJl9", + "status": "created" +} +``` + +## Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `session_id` | String | The ID of the created session (either provided or auto-generated). | +| `status` | String | The status of the creation operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md index 0f5f93e4949..491fe38004a 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md @@ -18,11 +18,38 @@ Use this API to delete a memory container by its ID. DELETE /_plugins/_ml/memory_containers/ ``` +## Path parameters + +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container to delete. | + +## Query parameters + +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `delete_all_memories` | Boolean | Optional | Controls whether to delete all memory indices when deleting the container. Default is `false`. When `false`, memory indices (sessions, working, long-term, history) are preserved. | +| `delete_memories` | Array | Optional | Array of memory types to delete when deleting the container. Default is empty array. Accepts values: `sessions`, `working`, `long-term`, `history`. Example: `delete_memories=sessions,working`. | + ## Example request +### Basic deletion (preserves memory indices) + ```json DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN ``` + +### Delete container and all memory indices + +```json +DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN?delete_all_memories=true +``` + +### Delete container and specific memory types + +```json +DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN?delete_memories=sessions,working +``` {% include copy-curl.html %} ## Example response diff --git a/_ml-commons-plugin/api/agentic-memory-apis/index.md b/_ml-commons-plugin/api/agentic-memory-apis/index.md index 8529aa24a3b..c5d5698e0b5 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/index.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/index.md @@ -40,6 +40,7 @@ OpenSearch supports the following memory container APIs: OpenSearch supports the following memory APIs: - [Add memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/add-memory/) +- [Create session]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-session/) - [Get memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/) - [Update memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory/) - [Delete memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory/) From 51926fd90ed68b611bc844d317573c36610b8a55 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Tue, 14 Oct 2025 09:29:35 -0400 Subject: [PATCH 26/27] Review of create session Signed-off-by: Fanit Kolchina --- .../api/agentic-memory-apis/add-memory.md | 2 +- .../create-memory-container.md | 2 +- .../api/agentic-memory-apis/create-session.md | 48 ++++++++++--------- .../delete-memory-container.md | 14 +++--- 4 files changed, 35 insertions(+), 31 deletions(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 71ae1567400..4f6a8bf3db9 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -3,7 +3,7 @@ layout: default title: Add agentic memory parent: Agentic memory APIs grand_parent: ML Commons APIs -nav_order: 40 +nav_order: 45 --- # Add Agentic Memory API diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index bc48d173541..04ee2bd8ae1 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -17,7 +17,7 @@ Use this API to create a [memory container]({{site.url}}{{site.baseurl}}/ml-comm For more information, see [Integrating ML models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/integrating-ml-models/). -LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). If user use OpenAI GPT model, should configure llm_result_path as `$.choices[0].message.content` +LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). If using an OpenAI GPT model, set the `llm_result_path` to `$.choices[0].message.content`. {: .note} Once a memory container is created, provide its `memory_container_id` to other APIs. diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-session.md b/_ml-commons-plugin/api/agentic-memory-apis/create-session.md index 13623718136..b500df82059 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-session.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-session.md @@ -1,7 +1,7 @@ --- layout: default title: Create session -parent: Agentic Memory APIs +parent: Agentic memory APIs grand_parent: ML Commons APIs nav_order: 40 --- @@ -10,7 +10,7 @@ nav_order: 40 **Introduced 3.3** {: .label .label-purple } -Use this API to create a new session in a memory container. Sessions represent distinct interaction contexts between users and agents. +Use this API to create a new session in a memory container. Sessions represent distinct interaction contexts between users and agents. ## Path and HTTP methods @@ -20,25 +20,27 @@ POST /_plugins/_ml/memory_containers//memories/sessions ## Path parameters +The following table lists the available path parameters. + | Parameter | Data type | Required/Optional | Description | | :--- | :--- | :--- | :--- | | `memory_container_id` | String | Required | The ID of the memory container where the session will be created. | ## Request fields +The following table lists the available request body fields. + | Field | Data type | Required/Optional | Description | | :--- | :--- | :--- | :--- | -| `session_id` | String | Optional | Custom session ID. If provided, this ID will be used for the session. If not provided, a random ID will be generated. | -| `summary` | String | Optional | A summary or description of the session. | -| `metadata` | Object | Optional | Additional metadata for the session as key-value pairs. | +| `session_id` | String | Optional | A custom session ID. If provided, this ID is used for the session. If not provided, a random ID is generated. | +| `summary` | String | Optional | A session summary or description. | +| `metadata` | Object | Optional | Additional metadata for the session provided as key-value pairs. | | `namespace` | Object | Optional | Namespace information for organizing the session. | -## Example requests - -### Create session with custom ID +## Example request: Create a session with a custom ID ```json -POST /_plugins/_ml/memory_containers/{{mem_container_id}}/memories/sessions +POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/sessions { "session_id": "abc123", "metadata": { @@ -47,10 +49,19 @@ POST /_plugins/_ml/memory_containers/{{mem_container_id}}/memories/sessions } ``` -### Create session with auto-generated ID +## Example response: Custom session ID + +```json +{ + "session_id": "abc123", + "status": "created" +} +``` + +## Example request: Create a session with an autogenerated ID ```json -POST /_plugins/_ml/memory_containers/{{mem_container_id}}/memories/sessions +POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/sessions { "summary": "This is a test session", "metadata": { @@ -63,18 +74,7 @@ POST /_plugins/_ml/memory_containers/{{mem_container_id}}/memories/sessions ``` {% include copy-curl.html %} -## Example responses - -### Response for custom session ID - -```json -{ - "session_id": "abc123", - "status": "created" -} -``` - -### Response for auto-generated session ID +## Example response: Autogenerated session ID ```json { @@ -85,6 +85,8 @@ POST /_plugins/_ml/memory_containers/{{mem_container_id}}/memories/sessions ## Response fields +The following table lists all response body fields. + | Field | Data type | Description | | :--- | :--- | :--- | | `session_id` | String | The ID of the created session (either provided or auto-generated). | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md index 491fe38004a..017418a3811 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md @@ -20,32 +20,34 @@ DELETE /_plugins/_ml/memory_containers/ ## Path parameters +The following table lists the available path parameters. + | Parameter | Data type | Required/Optional | Description | | :--- | :--- | :--- | :--- | | `memory_container_id` | String | Required | The ID of the memory container to delete. | ## Query parameters +The following table lists the available query parameters. + | Parameter | Data type | Required/Optional | Description | | :--- | :--- | :--- | :--- | -| `delete_all_memories` | Boolean | Optional | Controls whether to delete all memory indices when deleting the container. Default is `false`. When `false`, memory indices (sessions, working, long-term, history) are preserved. | +| `delete_all_memories` | Boolean | Optional | Controls whether to delete all memory indexes when deleting the container. Default is `false`. When `false`, memory indices (sessions, working, long-term, history) are preserved. | | `delete_memories` | Array | Optional | Array of memory types to delete when deleting the container. Default is empty array. Accepts values: `sessions`, `working`, `long-term`, `history`. Example: `delete_memories=sessions,working`. | -## Example request - -### Basic deletion (preserves memory indices) +## Example request: Basic deletion (preserves memory indexes) ```json DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN ``` -### Delete container and all memory indices +## Example request: Delete a container and all memory indexes ```json DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN?delete_all_memories=true ``` -### Delete container and specific memory types +## Example request: Delete a container and specific memory types ```json DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN?delete_memories=sessions,working From f9e8b86300ad9c7ca5270ec3e75a02914e4bc524 Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Tue, 14 Oct 2025 09:40:08 -0400 Subject: [PATCH 27/27] Apply suggestion from @natebower Signed-off-by: Nathan Bower --- .../api/agentic-memory-apis/delete-memory-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md index 017418a3811..cea64aba36a 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md @@ -32,7 +32,7 @@ The following table lists the available query parameters. | Parameter | Data type | Required/Optional | Description | | :--- | :--- | :--- | :--- | -| `delete_all_memories` | Boolean | Optional | Controls whether to delete all memory indexes when deleting the container. Default is `false`. When `false`, memory indices (sessions, working, long-term, history) are preserved. | +| `delete_all_memories` | Boolean | Optional | Controls whether to delete all memory indexes when deleting the container. Default is `false`. When `false`, memory indexes (sessions, working, long-term, history) are preserved. | | `delete_memories` | Array | Optional | Array of memory types to delete when deleting the container. Default is empty array. Accepts values: `sessions`, `working`, `long-term`, `history`. Example: `delete_memories=sessions,working`. | ## Example request: Basic deletion (preserves memory indexes)