Agentic memory retention

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

에이전틱 메모리 보존

3.8에 도입됨 {: .label .label-purple }

이 기능은 실험적인 기능이므로 프로덕션 환경에서 사용하는 것은 권장하지 않아요. 기능 진행 상황에 대한 업데이트를 받아보거나 피드백을 남기고 싶다면 OpenSearch forum에서 진행 중인 토론에 참여해 보세요. {: .warning}

기본적으로 에이전틱 메모리는 무한히 쌓이기 때문에 스토리지 사용량이 늘어나고, 에이전트가 오래된 메모리를 가져오게 될 수 있어요. 오래되거나 불필요하게 많은 메모리를 자동으로 삭제하려면 메모리 컨테이너에 _보존 정책(retention policy)_을 정의하세요. 보존 정책은 메모리 타입별로 보존 기간 제한, 개수 제한, 또는 둘 다를 지정해요. 백그라운드 작업이 정해진 스케줄에 따라 이 정책을 적용해요. 개수 제한을 초과한 sessions, long-term, history 메모리와, 보존 기간 제한을 초과한 sessions, long-term 메모리를 삭제하죠. 반면 working 메모리는 보존 정책의 적용 대상이 아니며, 부모 세션이 더 이상 존재하지 않을 때 삭제돼요. working 메모리의 보존 기간을 조절하려면 sessions에 대한 보존을 구성하세요.

sessions와 long-term 메모리를 고정(pinning)하면 보존 정책에서 제외할 수 있어요. 자세한 내용은 메모리 고정을 참고하세요.

메모리 보존 활성화하기

보존은 기본적으로 비활성화되어 있어요. 클러스터 전체에서 활성화하려면 다음 동적 클러스터 설정을 구성하세요:

PUT /_cluster/settings
{
  "persistent": {
    "plugins.ml_commons.memory.retention_enabled": true
  }
}

{% include copy-curl.html %}

보존 정책 정의하기

retention_policy 객체는 컨테이너의 configuration 객체 안에 지정하며, 각 메모리 타입을 해당 타입의 보존 제한에 매핑해요. {memory_type}은 sessions, long-term, history 중 하나로 바꿔 주세요:

"configuration": {
  "retention_policy": {
    "{memory_type}": {
      "retention_days": 90,
      "max_count": 5000
    }
  }
}

각 {memory_type} 객체는 다음 선택적 필드를 받아들여요. 두 필드를 모두 설정하면, 두 규칙 중 하나라도 위반한 메모리는 삭제돼요.

필드	데이터 타입	지원되는 메모리 타입	설명
`retention_days`	Integer	`sessions`, `long-term`	메모리의 `last_updated_time`을 기준으로 이 일수보다 오래된 메모리를 삭제해요.
`max_count`	Integer	`sessions`, `long-term`, `history`	최대 이 개수만큼의 메모리만 유지하며, 오래된 것부터 삭제해요. 세션과 long-term 메모리는 `last_updated_time` 기준으로 정렬되고, history는 `created_time` 기준으로 정렬돼요.

보존 규칙은 컨테이너가 해당 메모리 타입을 실제로 저장할 때만 효과가 있어요. long-term과 history 메모리가 저장되려면 strategies를 설정해야 해요. 그렇지 않으면 해당 타입의 보존 규칙은 아무 효과가 없죠. 자세한 내용은 생성된 인덱스를 참고하세요. {: .note}

보존 정책 구성하기

메모리 컨테이너를 생성할 때 정책을 구성하려면 생성 요청에 retention_policy 필드를 포함하세요. 다음 예제는 세션 추적과 전략을 갖추고, 세션을 최대 5,000개까지 90일 동안 보존하며 long-term 메모리는 2,000개로 제한하는 보존 정책을 가진 컨테이너를 생성해요:

POST /_plugins/_ml/memory_containers/_create
{
  "name": "my-agent-memory",
  "configuration": {
    "embedding_model_type": "TEXT_EMBEDDING",
    "embedding_model_id": "your-embedding-model-id",
    "embedding_dimension": 1024,
    "llm_id": "your-llm-model-id",
    "strategies": [
      {
        "type": "SEMANTIC",
        "namespace": ["user_id"]
      }
    ],
    "retention_policy": {
      "sessions": {
        "retention_days": 90,
        "max_count": 5000
      },
      "long-term": {
        "max_count": 2000
      }
    }
  }
}

{% include copy-curl.html %}

업데이트 요청에 retention_policy 객체를 담아 보내면, 기존 컨테이너에도 언제든 보존 정책을 추가할 수 있어요:

PUT /_plugins/_ml/memory_containers/{memory_container_id}
{
  "configuration": {
    "retention_policy": {
      "sessions": {
        "retention_days": 90,
        "max_count": 5000
      },
      "long-term": {
        "max_count": 2000
      }
    }
  }
}

{% include copy-curl.html %}

정책은 정책을 추가하기 전에 생성된 메모리를 포함해 컨테이너의 모든 메모리에 적용돼요. 예를 들어 세션을 10,000개 보유한 컨테이너에 max_count 100을 추가하면, 가장 오래전에 업데이트된 9,900개의 세션이 삭제돼요. 특정 메모리를 보존하고 싶다면 정책을 추가하기 전에 고정하세요. {: .warning}

보존 정책 조회하기

저장된 정책을 보려면 Get Memory Container API를 사용해 컨테이너를 조회하세요:

GET /_plugins/_ml/memory_containers/{memory_container_id}

{% include copy-curl.html %}

보존 정책 업데이트하기

retention_policy를 업데이트하면 기존 정책을 대체하는 게 아니라 변경 사항이 기존 정책에 병합돼요. 생략한 메모리 타입과 필드는 변경되지 않은 채 유지돼요.

필드 하나를 제거하려면 그 필드를 null로 설정하세요. 예를 들어 다음 요청은 보존 정책 구성하기 예제의 정책에서 sessions의 retention_days를 제거하되 max_count 5,000은 유지하는 방식으로 정책을 업데이트해요:

PUT /_plugins/_ml/memory_containers/{memory_container_id}
{
  "configuration": {
    "retention_policy": {
      "sessions": {
        "retention_days": null
      }
    }
  }
}

{% include copy-curl.html %}

컨테이너의 보존 비활성화하기

컨테이너 전체의 보존을 비활성화하려면 retention_policy를 null로 설정하세요:

PUT /_plugins/_ml/memory_containers/{memory_container_id}
{
  "configuration": {
    "retention_policy": null
  }
}

{% include copy-curl.html %}

retention_policy를 null로 설정하는 것은 아예 생략하는 것과 다른 결과를 가져와요. 정책을 생략하면 컨테이너가 클러스터 수준 기본 설정의 적용 대상으로 남지만, null로 설정하면 그 기본 설정이 적용되지 않아요. 이 요청은 클러스터 전체에서 보존이 비활성화된 상태에서도 보낼 수 있어요.

메모리 고정하기

메모리를 고정하면 컨테이너의 보존 정책에 따른 삭제 대상에서 제외돼요. 고정할 수 있는 메모리는 sessions와 long-term이에요. sessions를 고정하면 그 세션들의 working 메모리도 모두 함께 유지돼요. 고정된 메모리는 절대 삭제되지 않기 때문에 시간이 지나면 계속 쌓일 수 있어요. 컨테이너 크기를 줄이려면 더 이상 보호가 필요 없는 sessions는 고정을 해제하세요.

고정은 메모리를 삭제로부터 보호할 뿐, 메모리의 나이를 바꾸지는 않아요. 메모리의 나이는 last_updated_time부터 계산되며, 이 값은 세션에 working 메모리가 추가되거나 long-term 메모리가 업데이트되는 등 내용이 변경될 때만 갱신돼요. 고정은 이 타임스탬프를 갱신하지 않기 때문에, 나중에 고정을 해제하면 메모리의 나이는 여전히 마지막 내용 변경 시점을 반영하며, 즉시 삭제 대상이 될 수도 있어요.

메모리를 고정할 때는 다음 요청 필드를 사용하세요.

필드	데이터 타입	설명
`pinned`	Boolean	메모리를 고정하려면 `true`, 고정을 해제하려면 `false`로 설정하세요. `sessions`와 `long-term` 메모리에 유효해요.

다음 예제는 메모리를 고정해요 (memory_type에는 sessions 또는 long-term을 지정하세요):

PUT /_plugins/_ml/memory_containers/{memory_container_id}/memories/{memory_type}/{memory_id}
{
  "pinned": true
}

{% include copy-curl.html %}

보존 작업

백그라운드 작업이 스케줄에 따라 보존 정책을 적용해요 (기본적으로 24시간마다). 적용이 지속적으로 이뤄지는 게 아니라 스케줄에 따라 이뤄지기 때문에, 보존 기간이나 개수 제한을 넘은 메모리라도 작업이 다음으로 실행되어 삭제하기 전까지는 검색 결과에 그대로 반환돼요.

메모리는 다음 제한을 기준으로 평가돼요:

retention_days는 메모리의 last_updated_time을 기준으로 계산돼요. 세션에 working 메모리를 추가하면 세션의 타임스탬프가 갱신되므로 활발히 진행 중인 대화는 유지돼요. 메모리를 고정해도 타임스탬프는 갱신되지 않아요.
max_count는 나이와 관계없이 적용돼요. 컨테이너에 한 타입의 고정되지 않은 메모리가 max_count보다 많으면, retention_days보다 최신이더라도 max_count개만 남을 때까지 가장 오래된 것부터 삭제돼요.
한 메모리 타입에 두 제한이 모두 설정된 경우에는 둘 중 하나라도 초과하면 메모리가 삭제돼요.

max_count를 적용할 때는 실행 한 번당 컨테이너 하나에서 메모리 타입별로 최대 50,000개까지 삭제해요. 백로그가 더 크면 여러 번의 실행에 걸쳐 점진적으로 줄어들기 때문에, max_count를 크게 초과한 컨테이너는 한계에 도달하려면 여러 번의 실행이 필요할 수 있어요. retention_days에 따른 삭제에는 이런 상한이 없어요.

작업이 sessions 메모리를 삭제할 때는 고아가 생기지 않도록 그 세션의 working 메모리를 먼저 삭제해요. 반면 sessions 메모리를 수동으로 삭제하면 working 메모리는 삭제되지 않고 고아로 남아요. 정책 적용을 마친 후 작업은 created_time이 orphan_ttl_days보다 오래된 고아 working 메모리를 제거해요. 작업이 컨테이너의 고아를 처음 확인할 때는 기준선(baseline)을 기록만 하고 아무것도 삭제하지 않기 때문에, 해당 컨테이너의 고아 삭제는 기준선으로부터 orphan_ttl_days가 지난 후에 시작돼요.

고아 정리는 보존 정책을 갖고 있고 disable_session이 false(기본값)인 상태로 생성된 컨테이너에서만 실행돼요. 보존 정책이 없는 컨테이너에서는 고아가 된 working 메모리가 무기한 유지돼요.

disable_session을 true로 설정해 생성한 컨테이너는 sessions 메모리를 저장하지 않기 때문에, 앞서 설명한 어느 메커니즘도 적용되지 않아요. 이런 컨테이너의 working 메모리는 기본적으로 비활성화되어 있는 plugins.ml_commons.memory.working_memory_ttl_days 설정에 의해서만 삭제돼요. 이 값을 양수로 설정하기 전까지는 이런 컨테이너가 working 메모리를 무기한 유지해요. 자세한 내용은 메모리 보존 설정을 참고하세요.

멀티 테넌시가 활성화되어 있으면 이 작업은 비활성화돼요. 이 경우에는 정책이 있는 컨테이너라도 보존이 전혀 적용되지 않아요.

보존 일시 중지하기

구성해 둔 보존 정책을 그대로 유지하면서 보존을 일시 중지하려면 plugins.ml_commons.memory.retention_enabled를 false로 설정하세요. 다시 true로 설정하면 적용이 재개돼요.

메모리 보존 설정

다음 동적 클러스터 설정을 사용해 보존 동작을 커스터마이즈할 수 있어요:

plugins.ml_commons.memory.retention_enabled (Boolean): 클러스터 전체에서 보존을 활성화해요. 이 설정이 false인 동안에는 보존 작업이 아무것도 삭제하지 않고, 컨테이너 API는 retention_policy를 거부해요. 기본값은 false예요.
plugins.ml_commons.memory.retention_job_throttle_seconds (Integer): 메모리를 삭제한 컨테이너를 처리한 후, 보존 작업이 다음 컨테이너로 넘어가기 전까지 멈춰 있는 시간을 지정해요. 클러스터 부하를 줄이려면 이 값을 늘리세요. 유효 값 범위는 [1, 60]이고, 기본값은 5예요.
plugins.ml_commons.memory.working_memory_ttl_days (Integer): working 메모리가 생성된 지 이 일수가 지나면 삭제해요. disable_session을 true로 설정해 생성한 컨테이너에만 적용돼요. 이런 컨테이너는 sessions 메모리를 저장하지 않기 때문에, 이 설정이 working 메모리를 삭제하는 유일한 메커니즘이에요. 유효 값 범위는 [1, 365]이고, 기본값은 -1(비활성화)이에요.
plugins.ml_commons.memory.orphan_ttl_days (Integer): 부모 sessions 메모리가 더 이상 존재하지 않는 working 메모리를, working 메모리의 created_time을 기준으로 삭제해요. 자세한 내용은 보존 작업을 참고하세요. 유효 값 범위는 [1, 365]이고, 기본값은 7이에요.

기본 설정

기본 설정은 자체 보존 정책을 설정하지 않은 모든 컨테이너에 적용돼요. 이 설정은 클러스터에서 보존을 활성화한 후에야 효력이 발생하고, 그 전까지는 저장만 되고 아무 효과가 없어요. 보존이 활성화되면 다음 예정된 작업이 정책이 없는 컨테이너에 기본 설정을 적용하고, 기본값을 초과하는 메모리를 삭제해요. 이때 기본값을 설정하기 전에 생성된 메모리도 삭제 대상에 포함돼요.

기본 설정은 컨테이너에 한 번만 적용돼요. 나중에 이 설정을 바꿔도 이미 적용된 컨테이너는 업데이트되지 않아요. 컨테이너를 기본 설정의 적용 대상에서 제외하려면 해당 컨테이너의 retention_policy를 null로 설정하세요. 기본 설정이 적용된 후 컨테이너의 정책을 업데이트하려면 Update Memory Container API를 사용하세요.

다음 동적 설정은 각각 보존 정책의 한 필드에 대한 기본값을 제공해요. 기본값인 -1은 해당 필드에 기본값을 적용하지 않는다는 뜻이에요:

plugins.ml_commons.memory.default_session_retention_days (Integer): sessions 메모리의 기본 retention_days를 설정해요. 유효 값 범위는 [1, 3650]이고, 기본값은 -1이에요.
plugins.ml_commons.memory.default_session_max_count (Integer): sessions 메모리의 기본 max_count를 설정해요. 유효 값 범위는 [1, 1000000]이고, 기본값은 -1이에요.
plugins.ml_commons.memory.default_long_term_max_count (Integer): long-term 메모리의 기본 max_count를 설정해요. 유효 값 범위는 [1, 1000000]이고, 기본값은 -1이에요.
plugins.ml_commons.memory.default_history_max_count (Integer): history 메모리의 기본 max_count를 설정해요. 유효 값 범위는 [1, 10000000]이고, 기본값은 -1이에요.

보존 작업 스케줄

다음 설정이 보존 작업 스케줄을 제어해요. 클러스터를 시작하기 전에 opensearch.yml에 설정하세요. 작업은 시작 시 처음 스케줄링될 때 이 값을 한 번만 읽기 때문에, 실행 중인 클러스터에서 Cluster Settings API로 이 값을 바꿔도 효과가 없어요:

plugins.ml_commons.memory.retention_job_interval_hours (Integer): 보존 작업의 실행 주기를 시간 단위로 지정해요. 유효 값 범위는 [1, 168]이고, 기본값은 24예요.

다음 단계

메모리 컨테이너와 에이전틱 메모리에 대한 자세한 내용은 Agentic memory를 참조하세요.
컨테이너 생성 API 레퍼런스는 Create Memory Container API를 참조하세요.

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/ml-commons-plugin/agentic-memory-retention/

Agentic memory retention

본문

에이전틱 메모리 보존

메모리 보존 활성화하기

보존 정책 정의하기

보존 정책 구성하기

보존 정책 조회하기

보존 정책 업데이트하기

컨테이너의 보존 비활성화하기

메모리 고정하기

보존 작업

보존 일시 중지하기

메모리 보존 설정

기본 설정

보존 작업 스케줄

다음 단계

더 알아보기 (Learn more)

함께 읽는 실무 이야기