Link Search Menu Expand Document Documentation Menu
Documentation

Add Agentic Memory API

Introduced 3.3

Use this API to add an agentic memory to a memory container. You can specify different payload types and control inference mode for how OpenSearch processes the memory.

Once an agentic memory is created, provide its memory_id to other APIs.

Endpoints

POST /_plugins/_ml/memory_containers/{memory_container_id}/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 Array Conditional A list of messages for a conversational payload. Each message must include a content field specified as an array of objects. Each object must contain the type (for example, text) and the corresponding content. Each message 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.
structured_data_blob Object Optional Structured data that is stored with the memory but not indexed, so it cannot be searched.
binary_data String Optional Binary data content encoded as a Base64 string for binary payloads.
payload_type String Optional The type of payload. Valid values are conversational or data. Default is conversational. See 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, the payload_type is conversational, the memory container has an llm_id, and disable_session is false (the default), a new session with a new session ID is created. The LLM generates the session summary from the messages.
metadata Object Optional Additional metadata for the memory (for example, status, branch, or custom fields).
tags Object Optional Tags for categorizing and organizing memories.
message_id Integer Optional The sequence number of the message in a conversation. Agents use this field to order conversation messages.
checkpoint_id String Optional A checkpoint identifier to store with the memory.
parameters Object Optional Parameters that override the memory container’s parameters for this request only.
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. Requires the memory container to have an llm_id. See Inference mode.

This API creates working memories, which cannot be pinned, so the request rejects the pinned field. To exclude a conversation from a retention policy, pin its session after you add the memory. For more information, see Pinning memories.

Example request: Conversational payload

POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories
{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "text": "I'm Bob, I really like swimming.",
          "type": "text"
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "text": "Cool, nice. Hope you enjoy your life.",
          "type": "text"
        }
      ]
    }
  ],
  "namespace": {
    "user_id": "bob"
  },
  "metadata": {
    "status": "checkpoint",
    "branch": {
      "branch_name": "high",
      "root_event_id": "228nadfs879mtgk"
    }
  },
  "tags": {
    "topic": "personal info"
  },
  "infer": true,
  "payload_type": "conversational"
}

Example response: Conversational payload

{
  "session_id": "XSEuiJkBeh2gPPwzjYVh",
  "working_memory_id": "XyEuiJkBeh2gPPwzjYWM"
}

Example request: Data payload

To store agent state in working memory, send the following request:

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

Example response: Data payload

{
  "working_memory_id": "Z8xeTpkBvwXRq366l0iA"
}

Example request: Storing tool invocation data

To store agent trace data in working memory, send the following request:

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": "data"
}

Example response: Trace data

{
  "session_id": "123",
  "working_memory_id": "Z8xeTpkBvwXRq366l0iA"
}

Response body fields

The following table lists all response body fields.

Field Data type Description
session_id String The session ID associated with the memory. Returned when a session is created or when the namespace contains a session_id.
working_memory_id String The unique identifier for the created working memory entry.
350 characters left

Have a question? .

Want to contribute? or .