메모리 작동 방식 관리형 메모리(기본값)기존 메모리 추가(BYO)메모리 비활성화 액터 ID를 사용한 사용자당 메모리 범위 지정 장기 메모리 검색 컨텍스트 잘림

Memory

하네스는 AgentCore 메모리에서 대화 상태를 자동으로 유지합니다. 호출할 때마다 대화가 저장되고 세션 ID(제공된 경우 추가로 액터 ID)에 따라 범위가 지정됩니다. 세션 ID가 동일한 후속 호출 시 에이전트의 기록은 이유 전에 메모리에서 로드됩니다. 기본 microVM 세션이 만료된 후에도 이전 턴에서 발생한 일을 기억합니다. 이전 메시지를 직접 전달할 필요는 없으며 새 메시지만 보내면 됩니다.

메모리 작동 방식

단기 메모리는 세션 내에서 원시 이벤트(메시지, 도구 호출)를 캡처합니다. 이는 에이전트에 차례로 연속성을 제공합니다.
장기 메모리는 구성 가능한 전략(시맨틱, 요약, 사용자 기본 설정, 임시 또는 사용자 지정)을 통해 내구성 있는 지식을 추출하고 이후 세션에서 시맨틱 검색을 통해 검색할 수 있도록 합니다.
액터 ID는 에이전트(사용자, 다른 에이전트 또는 시스템)와 상호 작용하는 개체를 식별합니다. 메모리 이벤트는 actorId + sessionId로 범위가 지정되므로 각 액터에는 격리된 메모리가 있습니다. 장기 검색은 구성된 메모리 전략에 매핑하여 actorId를 네임스페이스 경로(예: /summary/{actorId}/{sessionId}/)의 템플릿 변수로 사용합니다.

관리형 메모리(기본값)

기본적으로 하네스는 AgentCore 메모리 인스턴스를 합리적인 기본값(시맨틱 + 요약 전략, 30일 이벤트 만료)으로 자동으로 프로비저닝합니다. 아무 것도 생성하거나 구성할 필요가 없습니다. 메모리만 작동합니다.

생성 시 관리형 메모리를 사용자 지정하려면:

예

AWS CLI/boto3


aws bedrock-agentcore-control create-harness \
  --harness-name "MyHarness" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --memory '{"managedMemoryConfiguration": {"strategies": ["SEMANTIC", "SUMMARIZATION", "USER_PREFERENCE"], "eventExpiryDuration": 60}}'

기존 하네스에 대한 전략을 업데이트하려면:


aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --memory '{"optionalValue": {"managedMemoryConfiguration": {"strategies": ["SEMANTIC", "SUMMARIZATION", "USER_PREFERENCE", "EPISODIC"]}}}'

AgentCore CLI

하네스를 생성할 때 메모리가 기본적으로 활성화됩니다.


agentcore create --name myagent
agentcore deploy

관리형 메모리를 건너뛰려면:


agentcore create --name myagent --no-harness-memory

Interactive

프로젝트 디렉터리agentcore에서를 실행하고 추가를 선택한 다음 하네스를 선택합니다. 마법사에는 메모리 단계가 포함되어 있습니다.

메모리 단계에서 영구 메모리 없음 또는 활성화를 선택하여 하네스에 대한 영구 메모리를 생성합니다.
메모리가 활성화되면 고급 설정에 추가 메모리 튜닝 옵션이 나타납니다. 스페이스로 활성화하고 Enter 키를 눌러 검색을 조정합니다.
선택적으로 메시지 수, 검색 상위 K 및 관련성 점수를 설정합니다(각각 건너뛸 수 있음).

마법사를 확인한 다음를 실행agentcore deploy하여 적용합니다.

관리형 메모리는 하네스에 의해 완전히 관리됩니다.

전략 구성은를 통해 제어됩니다UpdateHarness. 메모리 APIs.
관리형 메모리는 메모리 APIs를 통해 직접 삭제할 수 없습니다. 관리형 메모리를 일반 AgentCore 메모리 리소스로 전환하려면 다음 두 가지 방법으로 하네스에서 연결을 해제할 수 있습니다.
- UpdateHarness를 사용하여 BYO(agentCoreMemoryConfiguration) 또는 비활성화로 전환합니다.
- 삭제 deleteManagedMemory=false 시 전달하여 대신 연결 해제 - 기본적으로 관리형 메모리를 DeleteHarness 캐스케이드 삭제합니다.

사용 가능한 전략

전략	설명
`SEMANTIC`	의미 체계 검색을 통해 검색할 수 있는 대화에서 사실적 지식을 추출합니다.
`SUMMARIZATION`	액터 및 세션별로 범위가 지정된 실행 중인 대화 요약을 생성합니다.
`USER_PREFERENCE`	대화 중에 표현되는 사용자 기본 설정 및 설정을 캡처합니다.
`EPISODIC`	중요한 이벤트와 경험을 개별 에피소드로 기록합니다.

기존 메모리 추가(BYO)

사용자 지정 네임스페이스 템플릿, KMS 암호화 또는 여러 하네스의 공유 메모리 등 관리형 메모리가 제공하는 것 이상의 고급 구성이 필요한 경우 기존 AgentCore 메모리 인스턴스를 대신 연결합니다.

예

메모리 비활성화

메모리를 완전히 비활성화하려면:


aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --memory '{"optionalValue": {"disabled": {}}}'

액터 ID를 사용한 사용자당 메모리 범위 지정

호출 actorId 시를 전달하여 메모리 범위를 특정 사용자에게 지정합니다. 각 액터는 격리된 단기 및 장기 메모리를 얻습니다.


response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    actorId="user-123",
    messages=[{"role": "user", "content": [{"text": "What do you remember about my preferences?"}]}],
)

장기 메모리 검색

하네스에 활성 메모리 전략(관리형 또는 BYO)이 있는 경우 검색이 자동으로 작동합니다. 하네스는 메모리 인스턴스의 활성 전략에서 검색 구성을 도출합니다. 에이전트는 각 간접 호출 시 관련 장기 메모리를 쿼리하고 추론하기 전에 대화 컨텍스트에 주입합니다.

기본 동작:

검색은 각 활성 전략의 네임스페이스에 대한 기본 파라미터(topK=10, relevanceScore=0.2)로 자동으로 구성됩니다.
관리형 메모리 또는 BYO 메모리에는 수동 구성이 필요하지 않습니다.

기본값 재정의: BYO 메모리 구성retrievalConfig에를 명시적으로 제공하는 경우 값이 우선하며 자동 파생이 발생하지 않습니다. 이를 통해 쿼리할 네임스페이스를 사용자 지정하거나, topK 또는를 조정하거나relevanceScore, 특정 전략에 대한 검색을 비활성화할 수 있습니다.


aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --memory '{"optionalValue": {"agentCoreMemoryConfiguration": {"arn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:memory/MyMemory-abc123", "retrievalConfig": {"/facts/{actorId}/": {"topK": 5, "relevanceScore": 0.5, "strategyId": "FactExtractor-abc123"}}}}}'

중요

하네스에 연결한 후 BYO 메모리 인스턴스의 전략을 업데이트(추가 또는 제거)하는 경우를 호출UpdateHarness하여 검색 구성을 새로 고칩니다. 관리형 메모리의 경우 구성 UpdateHarness 새로 고침을 통해 전략이 자동으로 변경됩니다.

컨텍스트 잘림

대화 기록이 모델의 컨텍스트 기간 이상으로 증가하면 하네스는 잘라내기 전략을 적용합니다. 호출당 하네스 또는 재정의에서 이를 구성합니다.

sliding_window (기본값) - 최신 N 메시지를 유지합니다. 간단하고 예측 가능합니다.
summarization - 이전 메시지를 요약으로 압축하여 더 적은 토큰으로 더 많은 컨텍스트를 보존합니다.
none - 잘리지 않습니다. 컨텍스트 크기를 직접 관리하는 경우에만를 사용합니다.


aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --truncation '{"strategy": "sliding_window", "slidingWindowConfig": {"numMessages": 30}}'

자세히 알아보기: AgentCore 메모리, 메모리 스토어 생성, 장기 메모리 전략.