Create Memory Container API

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

메모리 컨테이너 생성 API

3.3부터 도입됨 {: .label .label-purple }

이 API를 사용해 에이전틱 메모리를 저장할 메모리 컨테이너를 생성하세요. 컨테이너에는 두 가지 모델 타입을 연결할 수 있어요:

메시지를 벡터화해 검색할 수 있게 해 주는 텍스트 임베딩 모델이에요. dense vector 임베딩에는 텍스트 임베딩 모델을, sparse vector 포맷에는 sparse encoding 모델을 사용하세요. 임베딩 모델을 지정하지 않으면 메시지는 저장되지만 벡터 기반 검색에는 사용할 수 없어요.
메시지를 추론해 사실 기반 또는 가공된 콘텐츠를 만들어 내는 대규모 언어 모델(LLM)이에요. LLM을 지정하지 않으면 추론을 적용하지 않은 채 메시지가 그대로 저장돼요. long-term memory를 사용하려면 LLM 모델과 임베딩 모델이 둘 다 설정되어 있어야 해요.

자세한 내용은 Integrating ML models을 참고하세요.

에이전틱 메모리 처리를 위해서는 LLM 커넥터가 system_prompt 및 user_prompt 파라미터를 지원해야 해요. 기본 llm_result_path는 Amazon Bedrock Converse API 응답 경로("$.output.message.content[0].text")예요. OpenAI GPT 모델을 사용하는 경우 llm_result_path를 $.choices[0].message.content로 설정하세요. {: .note}

메모리 컨테이너를 만들고 나면 다른 API에 memory_container_id를 제공하세요.

생성되는 인덱스

메모리 컨테이너에 생성되는 인덱스는 제공하는 configuration에 따라 달라져요. 다음 표가 이 동작을 요약해 줘요.

설정	생성되는 인덱스	기능
`configuration`이 없거나 `strategies`가 없는 경우	Working memory + session (`disable_session`이 `true`가 아닌 경우)	원본 메시지 저장 및 조회. semantic search, long-term memory, fact extraction 없음.
`strategies`를 지정하는 경우 (`llm_id`, `embedding_model_id`, `embedding_model_type` 필요)	Working memory + session + long-term memory + history (`disable_session`이 `true`가 아닌 경우)	semantic search, fact extraction, memory consolidation(ADD/UPDATE/DELETE 결정), 그리고 모든 long-term memory 변경에 대한 audit trail.

각 인덱스 타입은 고유한 용도를 가지고 있어요:

Working memory: 수신된 메시지를 원본 그대로 저장해요. 항상 생성돼요.
Session: 대화 세션과 그 메타데이터를 추적해요. 기본적으로 생성돼요. 세션 추적을 비활성화하려면 disable_session을 true로 설정하세요.
Long-term memory: 전략이 만들어 낸 추출 팩트와 지속적인 지식을 저장해요. 전략이 설정된 경우에만 생성돼요.
History: long-term memory에 대한 모든 ADD, UPDATE, DELETE 연산을 기록하는 audit trail이에요. 전략이 설정된 경우에만 생성돼요. disable_history를 true로 설정하면 생성하지 않도록 할 수 있어요.

사전 요구 사항

모델 타입 중 하나를 사용해 메모리를 처리하려면 OpenSearch에 모델을 등록하세요.

임베딩 모델

로컬 임베딩 모델이나 외부 호스팅 임베딩 모델 중 하나를 등록하세요. OpenSearch는 텍스트 임베딩 모델과 sparse encoding 모델을 지원해요.

모델을 로컬에서 사용하는 방법은 Using ML models within OpenSearch를 참고하세요. 지원되는 모델 목록은 OpenSearch-provided pretrained models을 참고하세요.

외부 호스팅 모델을 사용하는 방법은 Connecting to externally hosted models을 참고하세요. 예를 들어 외부 호스팅 Amazon Titan Embeddings 모델을 등록하려면 다음 요청을 보내세요:

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

Anthropic Claude 모델을 등록하려면 다음 요청을 보내세요:

POST /_plugins/_ml/models/_register
{
    "name": "Bedrock infer model",
    "function_name": "remote",
    "description": "test model",
    "connector": {
        "name": "Amazon Bedrock Connector: Chat",
        "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}/converse",
            "request_body": "{  \"anthropic_version\": \"${parameters.anthropic_version}\", \"max_tokens\": ${parameters.max_tokens}, \"temperature\": ${parameters.temperature}, \"system\": [{\"text\": \"${parameters.system_prompt}\"}], \"messages\": [ { \"role\": \"user\", \"content\": [ {\"text\": \"${parameters.user_prompt}\" }] }]}"
            }
        ]
    }
}

{% include copy-curl.html %}

Claude 모델에는 system_prompt 파라미터가 필요해요. {: .note}

외부 호스팅 모델을 사용하는 방법은 Connecting to externally hosted models을 참고하세요.

엔드포인트

POST /_plugins/_ml/memory_containers/_create

요청 본문 필드

다음 표는 사용 가능한 요청 본문 필드를 보여 줘요.

필드	데이터 타입	필수/선택	설명
`name`	String	필수	메모리 컨테이너의 이름이에요.
`memory_container_id`	String	선택	메모리 컨테이너의 고유 식별자예요. 생략하면 OpenSearch가 자동으로 생성해요.
`description`	String	선택	메모리 컨테이너의 설명이에요.
`configuration`	Object	선택	메모리 컨테이너 설정이에요. 제공하지 않으면 AI 기능 없이 working memory만 있는 컨테이너를 만드는 기본 설정이 사용돼요. semantic search와 long-term memory를 포함한 전체 기능을 사용하려면 모델 ID와 전략이 포함된 설정을 제공하세요. `configuration` 객체를 참고하세요.
`backend_roles`	Array	선택	접근 제어를 위한 backend role 목록이에요. 각 role은 최대 128자여야 하고 영숫자와 `:+=,.@-_/`만 포함할 수 있어요.

`configuration` 객체

configuration 객체는 다음 필드를 지원해요.

필드	데이터 타입	필수/선택	설명
`embedding_model_type`	String	선택	임베딩 모델 타입이에요. 지원되는 타입은 `TEXT_EMBEDDING`과 `SPARSE_ENCODING`이에요. `embedding_model_id`를 제공하면 필수예요.
`embedding_model_id`	String	선택	임베딩 모델 ID예요. `embedding_model_type`을 제공하면 필수예요.
`embedding_dimension`	Integer	선택	임베딩 모델의 차원이에요. `embedding_model_type`이 `TEXT_EMBEDDING`이면 필수이고, `SPARSE_ENCODING`이면 지정할 수 없어요.
`llm_id`	String	선택	처리와 추론에 사용할 LLM 모델 ID예요.
`index_prefix`	String	선택	메모리 인덱스에 사용할 사용자 지정 접두사예요. 지정하지 않으면 기본 접두사가 사용돼요. `use_system_index`가 `true`이면 `default`, `use_system_index`가 `false`이면 8자리 무작위 UUID가 사용돼요.
`use_system_index`	Boolean	선택	시스템 인덱스(`.plugins-ml-agentic-memory-` 접두사가 붙은 숨김 인덱스)를 사용할지 여부예요. 기본값은 `true`예요.
`disable_history`	Boolean	선택	history audit trail 인덱스를 비활성화할지 여부예요. 기본값은 `false`예요. 이 설정은 전략이 설정된 경우에만 효과가 있어요. history 인덱스는 long-term memory의 변경 사항을 기록하기 때문이에요. 전략이 없으면 이 설정과 관계없이 long-term memory 인덱스나 history 인덱스가 생성되지 않아요.
`disable_session`	Boolean	선택	세션 추적 인덱스를 비활성화할지 여부예요. 기본값은 `false`예요(세션은 기본적으로 활성화돼요). 세션 추적을 비활성화하려면 `true`로 설정하세요.
`max_infer_size`	Integer	선택	memory consolidation 중 ADD/UPDATE/DELETE 결정을 내리기 위해 조회하는 유사한 기존 메모리의 최대 개수예요. 기본값은 `5`이고 최댓값은 `10`이에요.
`index_settings`	Object	선택	이 컨테이너를 위해 생성될 메모리 저장 인덱스의 사용자 지정 OpenSearch 인덱스 설정이에요. 각 메모리 타입(`sessions`, `working`, `long_term`, `history`)은 자체 인덱스를 사용해요. `index_settings` 객체를 참고하세요.
`strategies`	Array	선택	메모리 처리 전략의 배열이에요. 전략을 지정하면 `llm_id`와 임베딩 모델 필드(`embedding_model_id`, `embedding_model_type`)가 모두 필요해요. `strategies` 배열을 참고하세요.
`parameters`	Object	선택	메모리 컨테이너의 전역 파라미터예요. `parameters` 객체를 참고하세요.

`index_settings` 객체

메모리 데이터를 저장하기 위해 생성될 저장 인덱스의 OpenSearch 인덱스 설정을 사용자 지정할 수 있어요. 각 메모리 타입은 전용 인덱스를 사용하며, 성능 최적화를 위해 샤드 수와 레플리카 수 같은 설정을 구성할 수 있어요.

다음 예제는 configuration 객체에서 사용자 지정 인덱스 설정을 지정하는 방법을 보여 줘요:

POST /_plugins/_ml/memory_containers/_create
{
  "name": "my-memory-container",
  "configuration": {
    "embedding_model_id": "your-model-id",
    "index_settings": {
      "session_index": {
        "index": {
          "number_of_shards": "2",
          "number_of_replicas": "2"
        }
      },
      "working_memory_index": {
        "index": {
          "number_of_shards": "2",
          "number_of_replicas": "2"
        }
      },
      "long_term_memory_index": {
        "index": {
          "number_of_shards": "2",
          "number_of_replicas": "2"
        }
      },
      "long_term_memory_history_index": {
        "index": {
          "number_of_shards": "2",
          "number_of_replicas": "2"
        }
      }
    }
  }
}

{% include copy-curl.html %}

`strategies` 배열

strategies 배열의 각 전략은 다음 필드를 지원해요.

필드	데이터 타입	필수/선택	설명
`type`	String	필수	전략 타입이에요. 유효한 값은 `SEMANTIC`, `USER_PREFERENCE`, `SUMMARY`예요.
`namespace`	Array	필수	메모리를 구성하기 위한 namespace 차원의 배열이에요(예: `["user_id"]` 또는 `["agent_id", "session_id"]`).
`configuration`	Object	선택	전략별 설정이에요. `strategies.configuration` 객체를 참고하세요.
`enabled`	Boolean	선택	메모리 컨테이너에서 이 전략을 활성화할지 여부예요. 기본값은 `true`예요.

`strategies.configuration` 객체

strategies.configuration 객체는 다음 필드를 지원해요.

필드	데이터 타입	필수/선택	설명
`llm_result_path`	String	선택	응답에서 LLM 결과를 추출하는 JSONPath 표현식이에요. 기본값은 Amazon Bedrock Converse API 응답 경로(`"$.output.message.content[0].text"`)예요.
`system_prompt`	String	선택	기본 전략 프롬프트를 대체하는 데 사용하는 사용자 지정 system prompt예요.
`llm_id`	String	선택	이 전략에서 사용할 LLM 모델 ID예요. 전역 LLM 설정을 재정의해요.

`parameters` 객체

parameters 객체는 다음 필드를 지원해요.

필드	데이터 타입	필수/선택	설명
`llm_result_path`	String	선택	응답에서 LLM 결과를 추출하는 전역 JSONPath 표현식이에요. 기본값은 Amazon Bedrock Converse API 응답 경로(`"$.output.message.content[0].text"`)예요.

예제 요청: 최소 메모리 컨테이너

다음 요청은 working memory(원본 메시지 저장)만 있는 최소 메모리 컨테이너를 만들어요. AI 모델이나 전략은 설정하지 않아요:

POST /_plugins/_ml/memory_containers/_create
{
  "name": "simple-message-store"
}

{% include copy-curl.html %}

이 요청은 working memory 인덱스 하나만 있는 컨테이너를 만들어요. 메시지를 ID로 저장하고 조회할 수 있지만, semantic search와 long-term memory 기능은 사용할 수 없어요.

예제 요청: 전략이 있는 기본 메모리 컨테이너

POST /_plugins/_ml/memory_containers/_create
{
  "name": "agentic memory test",
  "description": "Store conversations with semantic search and summarization",
  "configuration": {
    "embedding_model_type": "TEXT_EMBEDDING",
    "embedding_model_id": "{{embedding_model_id}}",
    "embedding_dimension": 1024,
    "llm_id": "{{llm_id}}",
    "strategies": [
      {
        "type": "SEMANTIC",
        "namespace": ["user_id"]
      }
    ]
  }
}

{% include copy-curl.html %}

이 요청은 working memory, long-term memory, history 인덱스를 갖춘 컨테이너를 만들어요. SEMANTIC 전략은 LLM으로 메시지에서 팩트를 추출하고, 임베딩 모델로 그 팩트들에 대한 벡터 기반 semantic search를 가능하게 해요.

예제 요청: 여러 전략이 있는 고급 메모리 컨테이너

POST /_plugins/_ml/memory_containers/_create
{
  "name": "agentic memory test",
  "description": "Store conversations with semantic search and summarization",
  "configuration": {
    "embedding_model_type": "TEXT_EMBEDDING",
    "embedding_model_id": "{{embedding_model_id}}",
    "embedding_dimension": 1024,
    "llm_id": "{{llm_id}}",
    "index_prefix": "my_custom_prefix",
    "use_system_index": false,
    "strategies": [
      {
        "type": "SEMANTIC",
        "namespace": ["agent_id"],
        "configuration": {
          "llm_result_path": "$.output.message.content[0].text",
          "system_prompt": "Extract semantic information from user conversations",
          "llm_id": "{{custom_llm_id}}"
        }
      },
      {
        "type": "USER_PREFERENCE",
        "namespace": ["agent_id"],
        "configuration": {
          "llm_result_path": "$.output.message.content[0].text"
        }
      },
      {
        "type": "SUMMARY",
        "namespace": ["agent_id"],
        "configuration": {
          "llm_result_path": "$.output.message.content[0].text"
        }
      }
    ],
    "parameters": {
      "llm_result_path": "$.output.message.content[0].text"
    }
  }
}

{% include copy-curl.html %}

예제 응답

응답에는 컨테이너를 조회하거나 삭제할 때 사용할 수 있는 memory_container_id가 들어 있어요:

{
    "memory_container_id": "SdjmmpgBOh0h20Y9kWuN",
    "status": "created"
}

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/ml-commons-plugin/api/agentic-memory-apis/create-memory-container/

Create Memory Container API

본문

메모리 컨테이너 생성 API

생성되는 인덱스

사전 요구 사항

임베딩 모델

LLM

엔드포인트

요청 본문 필드

configuration 객체

index_settings 객체

strategies 배열

strategies.configuration 객체

parameters 객체

예제 요청: 최소 메모리 컨테이너

예제 요청: 전략이 있는 기본 메모리 컨테이너

예제 요청: 여러 전략이 있는 고급 메모리 컨테이너

예제 응답

더 알아보기 (Learn more)

함께 읽는 실무 이야기

`configuration` 객체

`index_settings` 객체

`strategies` 배열

`strategies.configuration` 객체

`parameters` 객체