AgentCore Memory

AgentCore Memory

에이전트의 대화 기억을 저장·추출·검색하는 관리형 서비스

세션과 함께 끝나는 기억

"지난주에 추천받은 식당 어디였지?" — 세션 안의 기억만으로는 답할 수 없는 질문

Strands Memory 계층과의 관계

같은 목표(장기 기억), 다른 운영 주체 — 직접 운영과 관리형의 갈림길

Memory 하나, 기억 두 층

하나의 Memory 리소스 안에서 함께 동작하는 단기 기억(STM)과 장기 기억(LTM)

이벤트에서 레코드까지 — 기억 파이프라인

대화 원본은 STM에 쌓이고, 전략이 정제해 LTM 레코드로

1. 1
   대화 턴

   사용자와 에이전트가 메시지를 주고받습니다. 도구 결과도 기억 대상이 될 수 있습니다.

2. 2
   Event 저장 — STM

   대화 턴이 이벤트로 기록됩니다. actor_id와 session_id로 분류되어 세션 이력이 됩니다.

3. 3
   전략 실행

   등록된 추출 전략이 이벤트를 백그라운드에서 처리합니다. 전략마다 각자 자기 방식으로 정제합니다.

4. 4
   Record 생성 — LTM

   요약·사실·선호·에피소드가 레코드로 저장됩니다. 전략별 네임스페이스에 분리되어 쌓입니다.

5. 5
   검색·주입

   다음 세션에서 시맨틱 검색으로 관련 레코드만 꺼내 컨텍스트에 주입합니다.

STM vs LTM

원본을 그대로 담는 단기 기억과, 정제된 결과만 남기는 장기 기억

STM 더 깊이 — 조회 · 메타데이터 · 브랜치

원본 이력은 쌓기만 하는 게 아니라 — 찾고, 걸러내고, 갈래를 내는 대상

ListSessions · ListEvents · GetEvent

지난 세션을 찾아 이력을 다시 로드 — 편의 메서드 get_last_k_turns로 최근 k턴만

이벤트 메타데이터

키-값을 붙여 ListEvents 필터로 조회 — 민감정보 저장 금지(CMK 암호화 제외 대상)

branch

name + rootEventId로 특정 이벤트에서 갈래 생성 — 메시지 수정·대안 대화 경로, 원 대화는 보존

이벤트 유형 2종

Conversational(USER·ASSISTANT·TOOL·OTHER)과 blob(체크포인트 등 바이너리) — LTM 추출은 Conversational만

네임스페이스 — 기억의 주소 체계

레코드가 저장되는 경로가 곧 검색 범위와 격리 경계

/strategies/{memoryStrategyId}

전략별 분리 — 요약은 요약끼리, 선호도는 선호도끼리 검색

/actors/{actorId}

액터(사용자)별 격리 — 사용자 A의 기억에 사용자 B가 접근 불가

/sessions/{sessionId}

세션별 그룹 — 특정 세션의 이력만 좁혀서 조회 가능

추출 전략

전략 = 이벤트를 레코드로 바꾸는 변환기 — 같은 대화라도 등록한 전략에 따라 달라지는 기억

전략 4종 비교

무엇을 남기고, 어떻게 찾고, 어디에 쓰는가 — 전략 선택의 세 질문

같은 대화, 다른 기억

같은 대화도 전략마다 다른 레코드로 — 요약·사실·선호·에피소드, 전략별 변환 결과 비교

전략 조합 패턴

워크로드별로 검증된 2개 조합에서 출발

코드로 보는 사용 여정

컨트롤 플레인으로 생성, SessionManager로 연결, MemoryClient로 검색

Memory 생성 — 전략 등록

전략과 이벤트 만료만 선언 — 나머지 인프라는 서비스가 준비

핵심 포인트

bedrock-agentcore-control

컨트롤 플레인 — 리소스 생성·수정은 boto3로

eventExpiryDuration

STM 이벤트 만료 7~365일

memoryStrategies

전략 등록 — summary·semantic·userPreference·episodic 키, name 필수

response['memory']['id']

이후 모든 호출에 쓰는 memory_id — ARN이 아니라 ID

코드

import boto3

# 컨트롤 플레인 — Memory 리소스 생성은 boto3
control = boto3.client('bedrock-agentcore-control')

# Memory 생성 — 전략 2종 등록 (요약 + 선호도)
response = control.create_memory(
    name="restaurant_bot_memory",
    eventExpiryDuration=90,
    memoryStrategies=[
        {"summaryMemoryStrategy": {"name": "SessionSummary"}},
        {"userPreferenceMemoryStrategy": {"name": "Preferences"}},
    ],
)

# 이후 모든 호출의 식별자 — ARN이 아니라 ID
memory_id = response["memory"]["id"]

Strands 연동 — SessionManager 한 줄

에이전트 코드에 Memory 로직 없음 — 장착하면 저장과 검색이 자동

핵심 포인트

AgentCoreMemoryConfig

memory_id + actor_id(사용자 격리) + session_id(이력 단위)

AgentCoreMemorySessionManager

Strands Agent에 Memory를 투명하게 연결하는 어댑터

세션 시작

해당 액터의 관련 기억을 검색해 컨텍스트에 자동 주입

대화 중

각 턴을 Event로 저장 — 등록된 전략이 백그라운드 처리

코드

from strands import Agent
from bedrock_agentcore.memory.integrations.strands.config import AgentCoreMemoryConfig
from bedrock_agentcore.memory.integrations.strands.session_manager import AgentCoreMemorySessionManager

# 연결 정보 — memory_id는 생성 응답의 ID
config = AgentCoreMemoryConfig(
    memory_id=memory_id,
    actor_id="user-42",
    session_id="session-0722",
)
# 장착 — 이후 이벤트 저장·기억 검색은 자동
agent = Agent(
    model="us.anthropic.claude-sonnet-4-6",
    session_manager=AgentCoreMemorySessionManager(
        agentcore_memory_config=config, region_name="us-east-1"),
)
result = agent("이번에도 이탈리안으로 추천해줘")

LTM Metadata — 명시적 경계 긋기

시맨틱 유사도만으로는 못 가르는, 섞이면 안 되는 기억

기억 검색 — MemoryClient

Agent 없이도 데이터 플레인 API로 직접 다루는 기억

핵심 포인트

retrieve_memories

자연어 쿼리로 시맨틱 검색 — 레코드의 content는 dict, 본문은 content["text"]

create_event

SessionManager 없이 대화 턴을 STM에 직접 저장

namespace

전략·액터 경로로 좁히기 — 선호도는 선호도 네임스페이스에서

score

유사도 점수 — 컨텍스트에 주입할 레코드를 선별하는 기준

코드

from bedrock_agentcore.memory import MemoryClient

# 데이터 플레인 클라이언트 — 저장·검색 API 직접 호출
client = MemoryClient(region_name="us-east-1")

# 시맨틱 검색 — 선호도 전략의 액터 네임스페이스에서
# strategy_id — 등록한 전략의 ID (콘솔 또는 GetMemory로 확인)
memories = client.retrieve_memories(
    memory_id=memory_id,
    namespace=f"/strategies/{strategy_id}/actors/user-42/",
    query="이탈리안 식당 선호",
)

# 점수와 함께 확인 — content는 dict, 본문은 content["text"]
for mem in memories:
    print(f"[{mem['score']:.2f}] {mem['content']['text'][:80]}")