Add comprehensive agentic memory API documentation for OpenSearch 3.3 #11169
+1,418
−221
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
dhrubo-os
requested review from
AMoo-Miki,
dlvenable,
epugh,
kolchfa-aws,
natebower and
sumobrian
as code owners
|
Thank you for submitting your PR. The PR states are In progress (or Draft) -> Tech review -> Doc review -> Editorial review -> Merged. Before you submit your PR for doc review, make sure the content is technically accurate. If you need help finding a tech reviewer, tag a maintainer. When you're ready for doc review, tag the assignee of this PR. The doc reviewer may push edits to the PR directly or leave comments and editorial suggestions for you to address (let us know in a comment if you have a preference). The doc reviewer will arrange for an editorial review. |
- 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 <[email protected]>
|
@dhrubo-os Thank you for the PR! When you connect it to an issue, you have to leave "Closes", "Fixes", or "Resolves" so it's properly linked (in this case, |
kolchfa-aws
added
Tech review
|
Hey @dhrubo-os , let me know when this PR is ready for doc review. We have 3 days left before the release. |
- 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 <[email protected]>
- 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 <[email protected]>
- 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 opensearch-project#4283 for standardized connector format - Clarify that default is optimized for Bedrock Converse API Signed-off-by: Dhrubo Saha <[email protected]>
Yes please start reviewing the PR. Thanks |
ylwu-amzn
reviewed
Oct 10, 2025
|
|
||
| ## Path parameters | ||
|
|
||
| | Parameter | Data type | Description | |
There was a problem hiding this comment.
Currently we have a separate column Required/Optional, can we follow the same format?
ylwu-amzn
reviewed
Oct 10, 2025
| {: .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: |
There was a problem hiding this comment.
Suggested change
| 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: |
ylwu-amzn
reviewed
Oct 10, 2025
| 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. |
There was a problem hiding this comment.
Suggested change
| - **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. |
ylwu-amzn
reviewed
Oct 10, 2025
|
|
||
| - **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. |
There was a problem hiding this comment.
Suggested change
| - **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. |
ylwu-amzn
reviewed
Oct 10, 2025
|
|
||
| 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. |
There was a problem hiding this comment.
Suggested change
| - 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. | |
| - **infer=true** -- Use large language model (LLM) to extract key information or knowledge from the messages. |
ylwu-amzn
reviewed
Oct 10, 2025
|
|
||
| - 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. |
There was a problem hiding this comment.
Suggested change
| - **infer=false** -- Only store raw messages and data in working memory. |
ylwu-amzn
reviewed
Oct 10, 2025
| `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`. |
There was a problem hiding this comment.
Suggested change
| `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`. | |
| `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`. |
ylwu-amzn
reviewed
Oct 10, 2025
| `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`. |
There was a problem hiding this comment.
Suggested change
| `structured_data` | Object | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. | |
| `structured_data` | Map<String, Object> | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. |
There was a problem hiding this comment.
Add a new row for binary_data
ylwu-amzn
reviewed
Oct 10, 2025
| `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`. |
There was a problem hiding this comment.
Suggested change
| `memory_type` | String | Required | The type of memory: `conversation` or `data`. | |
| `payload_type` | String | Required | The type of payload: `conversational` or `data`. |
ylwu-amzn
reviewed
Oct 10, 2025
| `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`). |
There was a problem hiding this comment.
Suggested change
| `namespace` | Object | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). | |
| `namespace` | List<String> | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). |
There was a problem hiding this comment.
Explain more details
If session_id not exists in namespace will create a new session and use the new session's id
dhrubo-os
commented
Oct 13, 2025
| - 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. |
There was a problem hiding this comment.
For partitioning and isolating memories by context or user or agent or session
dhrubo-os
commented
Oct 13, 2025
|
|
||
| - 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. |
There was a problem hiding this comment.
For defining how memories are processed or extracted
dhrubo-os
commented
Oct 13, 2025
| - 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"`). |
There was a problem hiding this comment.
Seems repetitive at line 22?
dhrubo-os
commented
Oct 13, 2025
| 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 an agentic memory by its ID. | ||
| ## Delete a memory by type or ID |
There was a problem hiding this comment.
type or ID seems, we need either of them, but we need both of them here.
natebower
reviewed
Oct 13, 2025
| ### 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. |
There was a problem hiding this comment.
Suggested change
| - 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. |
_ml-commons-plugin/api/index.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
Suggested change
| - **[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. |
_ml-commons-plugin/api/index.md
Outdated
|
|
||
| - **[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/). |
There was a problem hiding this comment.
Suggested change
| - **[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/). | |
| - **[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/). |
|
|
||
| ## 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. |
There was a problem hiding this comment.
Suggested change
| 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. |
|
|
||
| | Field | Data type | Required/Optional | Description | | ||
| | :--- | :--- | :--- | :--- | | ||
| | `llm_id` | String | Optional | The large language model ID to use to extract facts. | |
There was a problem hiding this comment.
Suggested change
| | `llm_id` | String | Optional | The large language model ID to use to extract facts. | | |
| | `llm_id` | String | Optional | The large language model (LLM) ID to use to extract facts. | |
Signed-off-by: Nathan Bower <[email protected]>
natebower
added
Doc review
|
Please fix Jekyll build failure |
Signed-off-by: Fanit Kolchina <[email protected]>
natebower
reviewed
Oct 13, 2025
_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md
Outdated
Show resolved
Hide resolved
…iner.md Signed-off-by: Nathan Bower <[email protected]>
|
@kolchfa-aws Can you resolve conflicts as well? Thanks! |
ylwu-amzn
reviewed
Oct 13, 2025
ylwu-amzn
reviewed
Oct 13, 2025
| - [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: |
There was a problem hiding this comment.
Missed create session api ? opensearch-project/ml-commons#4246
ylwu-amzn
reviewed
Oct 13, 2025
natebower
reviewed
Oct 13, 2025
natebower
reviewed
Oct 13, 2025
Signed-off-by: Nathan Bower <[email protected]>
Co-authored-by: Yaliang Wu <[email protected]> Signed-off-by: Nathan Bower <[email protected]>
ylwu-amzn
reviewed
Oct 13, 2025
Signed-off-by: kolchfa-aws <[email protected]>
ylwu-amzn
reviewed
Oct 13, 2025
|
|
||
| ```json | ||
| DELETE /_plugins/_ml/memory_containers/{memory_container_id} | ||
| DELETE /_plugins/_ml/memory_containers/<memory_container_id> |
There was a problem hiding this comment.
This API supports two parameters
delete_all_memories: control delete all memory indices or not when delete container. Default isfalse. That means the memory index (sessions/working/long-term/history) will not be deleted when delete containerdelete_memories: array of memory types , defines deleting which memory index when delete container. Default is empty array. User can set as "delete_memories=sessions,working"
ylwu-amzn
reviewed
Oct 13, 2025
| For more information, see [Integrating ML models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/integrating-ml-models/). | ||
|
|
||
| Once a memory container is created, you'll provide its `memory_container_id` to other APIs. | ||
| 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"`). |
There was a problem hiding this comment.
If user use OpenAI GPT model, should configure llm_result_path as "$.choices[0].message.content"
ylwu-amzn
reviewed
Oct 13, 2025
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| ## Example response: Data memory |
There was a problem hiding this comment.
Suggested change
| ## Example response: Data memory | |
| ## Example response: Data payload |
ylwu-amzn
reviewed
Oct 13, 2025
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| ## Example response: Conversation memory |
There was a problem hiding this comment.
Suggested change
| ## Example response: Conversation memory | |
| ## Example response: Conversational payload |
ylwu-amzn
reviewed
Oct 13, 2025
| } | ||
| ``` | ||
|
|
||
| ## Example request: Storing trace data |
There was a problem hiding this comment.
Suggested change
| ## Example request: Storing trace data | |
| ## Example request: Storing tool invocation data |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Describe what this change achieves.
Issues Resolved
Closes #11162
Version
3.3
Frontend features
If you're submitting documentation for an OpenSearch Dashboards feature, add a video that shows how a user will interact with the UI step by step. A voiceover is optional.
Checklist
For more information on following Developer Certificate of Origin and signing off your commits, please check here.