Agentic memory

Introduced 3.3

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:

• 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

Currently, agentic memory is designed for integration with external agent frameworks like LangChain and LangGraph. OpenSearch’s internal agents cannot interact with agentic memory.

Important:

The agentic memory capability in OpenSearch is provided as a framework that enables you to build and manage memory for AI agents. As the administrator or owner of a memory container, you are responsible for the configuration, management, and security of your implementation. You are responsible for the following:

• Data access control: Implement and enforce all necessary data access controls for the conversation data stored within the memory container. This includes, but is not limited to, configuring appropriate index-level permissions, document-level security (DLS), or other mechanisms to restrict access. This responsibility is especially critical when the use_system_index option is set to false, because data will be stored in a standard index that requires explicit permission management.
• Custom system prompt management: If you choose to use a customized system prompt instead of the default, you are responsible for the content, management, and behavior of that prompt. OpenSearch is not responsible for the outputs or interactions resulting from user-defined system prompts. Failure to properly configure and secure your agentic memory implementation may result in unauthorized data access, data leakage, or unintended agent behavior.

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: For defining how memories are processed or extracted.
• 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:

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

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

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 conversation memory with inference, send the following request:

POST /_plugins/_ml/memory_containers/<container_id>/memories
{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "text": "I prefer email notifications over SMS",
          "type": "text"
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "text": "I've noted your preference for email notifications",
          "type": "text"
        }
      ]
    }
  ],
  "namespace": {
    "user_id": "user123",
    "session_id": "session456"
  },
  "payload_type": "conversational",
  "infer": true
}

To add agent state data, send the following request:

POST /_plugins/_ml/memory_containers/<container_id>/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
}

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 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:

GET /_plugins/_ml/memory_containers/<container_id>/memories/long-term/_search
{
  "query": {
    "bool": {
      "must": [
        {
          "term": {
            "namespace.user_id": "user123"
          }
        }
      ]
    }
  }
}

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 with appropriate models and strategies.
2. Add memories during agent interactions.
3. Search and retrieve relevant memories to inform agent responses.
4. Update memories as conversations evolve.

For detailed API documentation, see Agentic Memory APIs.

Next steps

• Explore memory container configuration options.
• Review the complete Agentic Memory API reference.