Add Agentic Memory APIs

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

@@ -0,0 +1,84 @@
+---
+layout: default
+title: Add agentic memory
+parent: Agentic Memory APIs
+grand_parent: ML Commons APIs
+nav_order: 40
+---
+
+# Add 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 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):
+
+- 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.
+
+Once an agentic memory is created, you'll provide its `memory_id` to other APIs.
+
+## Endpoint
+
+```json
+POST /_plugins/_ml/memory_containers/{memory_container_id}/memories
+```
+
+## Request body fields
+
+The following table lists the available request body fields.
+
+Field | Data type | Required/Optional | Description
+:--- | :--- | :--- | :---
+`messages` | List | Required | A list of messages.
+`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.
+
+## Example request
+
+```json
+POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories
+{
+    "messages": [
+        {"role": "assistant", "content": "Machine learning is a subset of artificial intelligence"}
+    ],
+    "session_id": "sess_789",
+    "agent_id": "agent_123",
+    "tags": {
+        "topic": "personal info"
+    }
+}
+```
+{% include copy-curl.html %}
+
+## Example response
+
+```json
+{
+    "results": [
+        {
+            "id": "T9jtmpgBOh0h20Y91WtZ",
+            "text": "Machine learning is a subset of artificial intelligence",
+            "event": "ADD"
+        }
+    ],
+    "session_id": "sess_789"
+}
+```
+
+## Response body fields
+
+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.                                    |

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

@@ -0,0 +1,184 @@
+---
+layout: default
+title: Create memory container
+parent: Agentic Memory APIs
+grand_parent: ML Commons APIs
+nav_order: 10
+---
+
+# Create Memory Container 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 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.
+
+Once a memory container is created, you'll 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 
+
+Register either a local or externally hosted embedding model. OpenSearch supports text embedding and sparse encoding models. 
+
+For more information about using models locally, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/using-ml-models/). For a list of supported models, see [OpenSearch-provided pretrained models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/pretrained-models/#supported-pretrained-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/). For example, to register an externally hosted Amazon Titan Embeddings model, send the following request:
+
+```json
+POST /_plugins/_ml/models/_register
+{
+    "name": "Bedrock embedding model",
+    "function_name": "remote",
+    "description": "test model",
+    "connector": {
+        "name": "Amazon Bedrock Connector: embedding",
+        "description": "The connector to bedrock Titan embedding model",
+        "version": 1,
+        "protocol": "aws_sigv4",
+        "parameters": {
+              "region": "us-east-1",
+              "service_name": "bedrock",
+              "model": "amazon.titan-embed-text-v2:0",
+              "dimensions": 1024,
+             "normalize": true,
+             "embeddingTypes": [
+              "float"
+            ]
+        },
+        "credential": {
+             "access_key": "...",
+             "secret_key": "...",
+             "session_token": "..."
+        },
+        "actions": [
+            {
+                "action_type": "predict",
+                "method": "POST",
+                "url": "https://bedrock-runtime.${parameters.region}.amazonaws.com/model/${parameters.model}/invoke",
+                "headers": {
+                    "content-type": "application/json",
+                    "x-amz-content-sha256": "required"
+                },
+                "request_body": """{ "inputText": "${parameters.inputText}", "dimensions": ${parameters.dimensions}, "normalize": ${parameters.normalize}, "embeddingTypes": ${parameters.embeddingTypes} }""",
+                "pre_process_function": "connector.pre_process.bedrock.embedding",
+                "post_process_function": "connector.post_process.bedrock.embedding"
+            }
+        ]
+    }
+}
+```
+{% include copy-curl.html %}
+
+### LLM 
+
+OpenSearch supports the Anthropic Claude model for LLM capabilities. To register a Claude model, send the following request:
+
+```json
+POST /_plugins/_ml/models/_register
+{
+    "name": "Bedrock infer model",
+    "function_name": "remote",
+    "description": "test model",
+    "connector": {
+        "name": "Amazon Bedrock Connector: embedding",
+        "description": "The connector to bedrock Claude 3.7 sonnet model",
+        "version": 1,
+        "protocol": "aws_sigv4",
+        "parameters": {
+            "region": "us-east-1",
+            "service_name": "bedrock",
+            "max_tokens": 8000,
+            "temperature": 1,
+            "anthropic_version": "bedrock-2023-05-31",
+            "model": "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
+        },
+        "credential": {
+            "access_key": "...",
+            "secret_key": "...",
+            "session_token": "..."
+            },
+        "actions": [
+            {
+            "action_type": "predict",
+            "method": "POST",
+            "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} }"""
+            }
+        ]
+    }
+}
+```
+{% include copy-curl.html %}
+
+The `system_prompt` parameter is required for Claude models.
+{: .note}
+
+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
+
+```json
+POST /_plugins/_ml/memory_containers/_create
+```
+
+## Request body fields
+
+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.
+`memory_storage_config` | Object | Optional | The memory storage configuration. See [the `memory_storage_config` object](#the-memory_storage_config-object).
+
+### The memory_storage_config object
+
+The `memory_storage_config` 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.
+
+## Example request
+
+```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"
+    }
+}
+```
+{% include copy-curl.html %}
+
+## Example response
+
+The response contains the `memory_container_id` that you can use to retrieve or delete the container:
+
+```json
+{
+    "memory_container_id": "SdjmmpgBOh0h20Y9kWuN",
+    "status": "created"
+}
+```

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

@@ -0,0 +1,48 @@
+---
+layout: default
+title: Delete memory container
+parent: Agentic Memory APIs
+grand_parent: ML Commons APIs
+nav_order: 30
+---
+
+# Delete Memory Container 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 a memory container by its ID.
+
+## Endpoint
+
+```json
+DELETE /_plugins/_ml/memory_containers/{memory_container_id}
+```
+
+## Example request
+
+```json
+DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN
+```
+{% include copy-curl.html %}
+
+## Example response
+
+```json
+{
+    "_index": ".plugins-ml-memory-container",
+    "_id": "SdjmmpgBOh0h20Y9kWuN",
+    "_version": 3,
+    "result": "deleted",
+    "forced_refresh": true,
+    "_shards": {
+        "total": 2,
+        "successful": 2,
+        "failed": 0
+    },
+    "_seq_no": 6,
+    "_primary_term": 1
+}
+```

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

@@ -0,0 +1,47 @@
+---
+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
+}
+```