Skip to content

Add comprehensive agentic memory API documentation for OpenSearch 3.3 #11169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

Add comprehensive agentic memory API documentation for OpenSearch 3.3 #11169

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
7428307
Add comprehensive agentic memory API documentation for OpenSearch 3.3
dhrubo-os Oct 1, 2025
ab7fd46
Consolidate agentic memory APIs and update with real response examples
dhrubo-os Oct 10, 2025
c5a4cc8
Complete agentic memory API documentation with missing container APIs
dhrubo-os Oct 10, 2025
ee90e24
Document default llm_result_path and LLM connector requirements
dhrubo-os Oct 10, 2025
e82965d
Address ylwu-amzn review comments
dhrubo-os Oct 10, 2025
56a10a2
Add agentic memory cluster setting
dhrubo-os Oct 10, 2025
f4d4bbf
update path parameters
dhrubo-os Oct 10, 2025
1340f34
addressed comments
dhrubo-os Oct 11, 2025
b18236c
addressed comments
dhrubo-os Oct 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 122 additions & 34 deletions _ml-commons-plugin/api/agentic-memory-apis/add-memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,12 @@
**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 provide memory payload in two types:

- 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.
- **conversational** -- Stores conversational messages between users and assistants.

- Raw message memory -- The unprocessed message content.
- **data** -- Stores extra messages, structured, non-conversational data such as agent state, checkpoints, or reference information.

Copy link
Contributor

@ylwu-amzn ylwu-amzn Oct 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add some description before showing infer=true/false ? For example add this

User can use infer to choose to extract key information from raw messages or not.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done.

Copy link
Contributor

@ylwu-amzn ylwu-amzn Oct 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems misunderstood my comments. Check the preview of this doc, it shows

provide memory payload in two types:

  • conversational: ...
  • data: ...
  • infer: ...

Let's keep it simple, just remove this infer line, just merge this infer parameter description to the infer row in the fields table ?

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

Expand All @@ -31,43 +29,136 @@

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.
`tags` | Object | Optional | Custom metadata for the agentic 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<String, Object> | 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<String> | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). If `session_id` not exists in `namespace` will create a new session and use the new session's id.
`metadata` | Map<String, Object> | Optional | Additional metadata for the memory (e.g., `status`, `branch`, custom fields).
`tags` | List<String, String> | 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 request
## Example requests

### Conversational payload

Check failure on line 45 in _ml-commons-plugin/api/agentic-memory-apis/add-memory.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.StackedHeadings] Do not stack headings. Insert an introductory sentence between headings.

Raw Output:
{"message": "[OpenSearch.StackedHeadings] Do not stack headings. Insert an introductory sentence between headings.", "location": {"path": "_ml-commons-plugin/api/agentic-memory-apis/add-memory.md", "range": {"start": {"line": 45, "column": 1}}}, "severity": "ERROR"}

```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"
},
"metadata": {
"status": "checkpoint",
"branch": {
"branch_name": "high",
"root_event_id": "228nadfs879mtgk"
}
},
"tags": {
"topic": "personal info"
},
"infer": true,
"payload_type": "conversational"
}
```

### Data payload

Store agent state in working 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"
},
"metadata": {
"status": "checkpoint",
"anyobject": "abc"
},
"tags": {
"topic": "agent_state"
},
"infer": false,
"payload_type": "data"
}
```

Store agent trace data in working 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"
},
"metadata": {
"status": "checkpoint",
"branch": {
"branch_name": "high",
"root_event_id": "228nadfs879mtgk"
},
"anyobject": "abc"
},
"tags": {
"topic": "personal info",
"parent_memory_id": "o4-WWJkBFT7urc7Ed9hM",
"data_type": "trace"
},
"infer": false,
"payload_type": "conversational"
}
```
{% include copy-curl.html %}

## Example response
## Example responses

### Conversation memory response

Check failure on line 148 in _ml-commons-plugin/api/agentic-memory-apis/add-memory.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.StackedHeadings] Do not stack headings. Insert an introductory sentence between headings.

Raw Output:
{"message": "[OpenSearch.StackedHeadings] Do not stack headings. Insert an introductory sentence between headings.", "location": {"path": "_ml-commons-plugin/api/agentic-memory-apis/add-memory.md", "range": {"start": {"line": 148, "column": 1}}}, "severity": "ERROR"}

```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"
}
```

Expand All @@ -77,8 +168,5 @@

| 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. |
Loading
Loading