View a markdown version of this page

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

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

Memory

메모리가 활성화되면 하네스는 AgentCore 메모리에서 대화 상태를 유지합니다. 세션 ID가 동일한 후속 호출 시 에이전트는 저장 기록을 로드합니다.

메모리 작동 방식

  • 단기 메모리는 세션 내에서 원시 이벤트(메시지, 도구 호출)를 캡처합니다. 이는 에이전트에 차례로 연속성을 제공합니다.

  • 장기 메모리는 구성 가능한 전략(시맨틱, 요약, 사용자 기본 설정, 임시 또는 사용자 지정)을 통해 내구성 있는 지식을 추출하고 이후 세션에서 시맨틱 검색을 통해 검색할 수 있도록 합니다.

  • 액터 ID는 에이전트(사용자, 다른 에이전트 또는 시스템)와 상호 작용하는 개체를 식별합니다. 메모리 이벤트는 actorId + sessionId로 범위가 지정되므로 각 액터에는 격리된 메모리가 있습니다. 장기 검색은 구성된 메모리 전략에 매핑하여 actorId를 네임스페이스 경로(예: /summary/{actorId}/{sessionId}/)의 템플릿 변수로 사용합니다.

관리형 메모리

서비스 API를 사용하여 직접 하네스를 생성하고 메모리 구성을 생략하면 서비스가 관리형 메모리를 프로비저닝합니다. AgentCore CLI는 다른 기본값을 사용합니다. 관리형 메모리 또는 기존 메모리 리소스를 선택하지 않는 한 새 CLI 하네스에는 메모리가 비활성화되어 있습니다.

메모리 요금

하네스 자체에는 추가 요금이 부과되지 않습니다. 관리형 메모리에는 단기 이벤트, 저장된 장기 메모리 레코드 및 검색 요청에 대한 표준 AgentCore 메모리 요금이 발생합니다. 영구 메모리 요금을 방지하려면 하네스를 생성할 때 메모리를 비활성화합니다. 자세한 내용은 하네스 비용 이해 및 Amazon Bedrock AgentCore 요금을 참조하세요.

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

예
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 --project-name MyHarnessProject --no-agent
cd MyHarnessProject
agentcore add harness \
  --name myagent \
  --memory-mode managed \
  --memory-strategies SEMANTIC,SUMMARIZATION \
  --memory-event-expiry-days 30
agentcore deploy

메모리는 기본적으로 비활성화되어 있습니다. 메모리 없이 하네스를 생성하려면 이전 명령 대신 다음 agentcore add harness 명령을 실행합니다.

agentcore add harness --name myagent --no-memory
Interactive

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

  1. 메모리 단계에서 영구 메모리 없음 또는 활성화를 선택하여 하네스에 대한 영구 메모리를 생성합니다.

    메모리 단계: 영구 메모리 없음 또는 활성화됨

  2. 메모리가 활성화되면 고급 설정에 추가 메모리 튜닝 옵션이 나타납니다. 스페이스로 활성화하고 Enter 키를 눌러 검색을 조정합니다.

    고급 설정: 메모리 튜닝 옵션

  3. 선택적으로 메시지 수, 검색 상위 K 및 관련성 점수를 설정합니다(각각 건너뛸 수 있음).

    메모리 튜닝: 메시지 수, 상위 K, 관련성 점수

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

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

  • 전략 구성은를 통해 제어됩니다UpdateHarness. 메모리 APIs.

  • 관리형 메모리는 메모리 APIs를 통해 직접 삭제할 수 없습니다. 관리형 메모리를 일반 AgentCore 메모리 리소스로 전환하려면 다음 두 가지 방법으로 하네스에서 연결을 해제할 수 있습니다.

    • UpdateHarness를 사용하여 BYO(agentCoreMemoryConfiguration) 또는 비활성화로 전환합니다.

    • 삭제 deleteManagedMemory=false 시 전달하여 대신 연결 해제 - 기본적으로 관리형 메모리를 DeleteHarness 캐스케이드 삭제합니다.

사용 가능한 전략

전략 설명

SEMANTIC

의미 체계 검색을 통해 검색할 수 있는 대화에서 사실적 지식을 추출합니다.

SUMMARIZATION

액터 및 세션별로 범위가 지정된 실행 중인 대화 요약을 생성합니다.

USER_PREFERENCE

대화 중에 표현되는 사용자 기본 설정 및 설정을 캡처합니다.

EPISODIC

중요한 이벤트와 경험을 개별 에피소드로 기록합니다.

기존 메모리 추가(BYO)

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

예
AWS CLI/boto3

메모리 인스턴스 생성:

aws bedrock-agentcore-control create-memory \
  --name "MyMemory" \
  --event-expiry-duration 30 \
  --description "Memory for my harness"

하네스에 연결합니다.

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"}}}'
AgentCore CLI
agentcore create --project-name MyHarnessProject --no-agent
cd MyHarnessProject
agentcore add harness --name myagent \
  --memory-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:memory/MyMemory-abc123"
agentcore deploy

메모리 비활성화

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

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 메모리, 메모리 스토어 생성, 장기 메모리 전략.

관련 주제