Amazon Bedrock AgentCore Memory: 기억하는 AI 에이전트 만들기

memory_id             : 메모리 리소스의 고유 식별자 (AWS 리소스 ARN 수준)
    └─ actor_id       : 사용자의 고유 식별자 (사용자 수준)
        └─session_id  : 사용자의 대화 세션 고유 식별자 (대화 수준)

memory_id: "customer-support-bot-production"
  └─ actor_id: "customer-12345"
      ├─ session_id: "chat-2024-01-15-110000"      # 11시에 시작된 세션
      └─ session_id: "chat-2024-01-15-150000"      # 15시에 시작된 세션
  └─ actor_id: "customer-67890"
      └─ session_id: "chat-2024-01-15-120000"

USER: 오늘 뭐 먹지?
ASSISTANT: 치킨, 피자, 족발을 추천 드립니다!

USER: 오 나 치킨 좋아하긴 해.
ASSISTANT: 탁월한 선택이십니다. 치킨을 주문해드릴까요?

USER: 응.
ASSISTANT: 치킨을 주문했습니다! 30분 후에 도착 예정입니다.

/facts/{actorId}                    # 사용자별 사실 정보
/preferences/{actorId}              # 사용자별 선호도
/summaries/{actorId}/{sessionId}    # 세션별 요약

from bedrock_agentcore.memory import MemoryClient
import uuid
import time

# 1. 메모리 클라이언트 초기화
memory_client = MemoryClient(region_name='us-west-2')

#2 Short term memory 생성
# strategies 리스트를 비워두면, 단기 기억만 활성화된 메모리 리소스가 생성됩니다.
short_term_memory = client.create_memory_and_wait(
    name="test-short-term-memory",
    strategies=[],
    event_expiry_days=7 # 데이터 보관 기간 설정
)

#2.1 Long term memory 포함하여 생성하기
# Semantic, Preference, Summary 등 필요한 전략을 정의하여 장기 기억을 구성합니다.
long_term_memory = client.create_memory_and_wait(
    name="test-long-term-memory",
    strategies=[
        {
            "semanticMemoryStrategy": {
                "name": "facts",
                "namespaces": ["/facts/{actorId}"]
            }
        },
        {
            "userPreferenceMemoryStrategy": {
                "name": "preferences",
                "namespaces": ["/preferences/{actorId}"]
            }
        },
       {
            "summaryMemoryStrategy": {
                "name": "summaries",
                "namespaces": ["/summaries/{actorId}/{sessionId}"]
            }
        }
    ],
    event_expiry_days=30
)

# 대화 시나리오 예시
messages = [
    ("오늘 뭐 먹지?", "USER"),
    ("치킨, 피자, 족발을 추천 드립니다!", "ASSISTANT"),
    ("오 나 치킨 좋아하긴 해.", "USER"),
    ("탁월한 선택이십니다. 치킨을 주문해드릴까요?", "ASSISTANT"),
    ("응.", "USER"),
    ("치킨을 주문했습니다! 30분 후에 도착 예정입니다.", "ASSISTANT")
]
actor_id = "minsukim"
session_id = "test-session-123456781234567812345678"

# 3. 메모리에 이벤트(대화) 추가
# create_event 호출 한 번으로 리스트 내의 모든 대화 턴이 순서대로 저장됩니다.
memory_client.create_event(
    memory_id=long_term_memory['id'],
    actor_id=actor_id,
    session_id=session_id,
    messages=messages
)

# 4. 단기 메모리에서 최근 k 개의 턴 메세지 확인
conversation = client.get_last_k_turns(
    memory_id=long_term_memory['id'],
    actor_id=actor_id,
    session_id=session_id
    k=2
)

[
    [
        {'content': {'text': '오 나 치킨 좋아하긴 해'}, 'role': 'USER'}, 
        {'content': {'text': '탁월한 선택이십니다. 치킨을 주문해드릴까요?'}, 'role': 'ASSISTANT'}
    ], 
    [
        {'content': {'text': '응.'}, 'role': 'USER'}, 
        {'content': {'text': '치킨을 주문했습니다! 30분 후에 도착 예정입니다.'}, 'role': 'ASSISTANT'}
    ]
]

# 단기 기억은 저장 즉시 활용 가능하지만 장기 기억은 추출에 시간이 소요됩니다.
time.sleep(120)

# 5.1 Semantic memory 검색
facts = client.retrieve_memories(
    memory_id=memory['id'],
    namespace=f"/facts/{actor_id}",
    query="사용자 정보",
    top_k=5
)

print(facts)
"""
출력 결과:
[{
    'memoryRecordId': 'mem-89577cc8-a405-4cf9-bd27-396abba385e4', 
    'content': {'text': '사용자는 치킨을 주문했다.'}, 
    'memoryStrategyId': 'facts-Sgv0KdDPV7', 
    'namespaces': ['/facts/minsukim'], 
    'createdAt': datetime.datetime(2025, 12, 4, 18, 3, 46, 135000, tzinfo=tzlocal()), 
    'score': 0.37856376, 
    'metadata': {'x-amz-agentcore-memory-recordType': {'stringValue': 'BASE'}}
}]
"""

#5.2 User preference memory 검색
prefs = client.retrieve_memories(
    memory_id=memory['id'],
    namespace=f"/preferences/{actor_id}",
    query="선호도",
    top_k=5
)

print(prefs)
# 단순히 "치킨"이라는 단어만 저장하는 것이 아니라, 문맥(Context)과 선호 대상(Preference), 카테고리 등을 구조화하여 저장한 것을 확인할 수 있습니다.
"""
출력 결과:
[{
    'memoryRecordId': 'mem-4299bc45-bb97-4a93-bdd2-64c009981b78', 
    'content': {
        'text': '{"context":"사용자가 치킨을 좋아한다고 명시적으로 언급함", "preference":"치킨을 좋아함","categories":["음식"]}'
    }, 
    'memoryStrategyId': 'preferences-LIsEey8Dj6', 
    'namespaces': ['/preferences/minsukim'], 
    'createdAt': datetime.datetime(2025, 12, 4, 18, 3, 46, 135000, tzinfo=tzlocal()), 
    'score': 0.36258087, 
    'metadata': {'x-amz-agentcore-memory-recordType': {'stringValue': 'BASE'}}
}]
"""

#5.3 Summary memory 검색
summaries = client.retrieve_memories(
    memory_id=memory['id'],
    namespace=f"/summaries/{actor_id}/{session_id}",
    query="요약",
    top_k=5
)

print(summaries)
# 긴 대화의 흐름을 파악하기 위해 summaries 네임스페이스를 조회합니다. actor_id와 session_id를 모두 네임스페이스에 포함하여 특정 세션의 요약본을 가져올 수 있습니다.
"""
출력 결과:
[{
    'memoryRecordId': 'mem-d15ac09916fb2f81e85d94f06f7f5954771a', 
    'content': {
        'text': '<topic name="식사 선택">\n사용자가 무엇을 먹을지 질문하자 치킨, 피자, 족발이 추천됨\n사용자는 치킨을 좋아한다고 하여 치킨을 선택함\n치킨이 주문되었고 30분 후에 도착 예정임\n</topic>'
    }, 
    'memoryStrategyId': 'summaries-Sd40MlEqlw', 
    'namespaces': ['/summaries/minsukim/test-session-123456781234567812345678'], 
    'createdAt': datetime.datetime(2025, 12, 4, 18, 3, 46, 135000, tzinfo=tzlocal()), 
    'score': 0.33990282, 'metadata': {'x-amz-agentcore-memory-recordType': {'stringValue': 'BASE'}}
}]

from bedrock_agentcore.memory import MemoryClient
from bedrock_agentcore.memory.integrations.strands.config import (
    AgentCoreMemoryConfig,
    RetrievalConfig
)
from bedrock_agentcore.memory.integrations.strands.session_manager import (
    AgentCoreMemorySessionManager
)
from strands import Agent
import logging
import time

# Bedrock AgentCore Memory 연동 로그를 확인하기 위한 로그 구성
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)


# Bedrock AgentCore Memory를 활용하는 Strands Agents 구성
def create_strands_agent(memory_id, actor_id, session_id):
    # 1. 메모리 설정 구성 (Retrieval Config) 
    # 에이전트가 대화 시 참고할 장기 기억의 임계값(Threshold)을 설정합니다.    
    config = AgentCoreMemoryConfig(
        memory_id=memory_id,
        session_id=session_id,
        actor_id=actor_id,
        retrieval_config={
            "/preferences/{actorId}": RetrievalConfig(
                top_k=5,
                relevance_score=0.6 # 활용할 memory의 최소 유사도 컷오프 점수
            ),
            "/facts/{actorId}": RetrievalConfig(
                top_k=10,
                relevance_score=0.3
            )
        }
    )
    
    # 2. 세션 매니저 초기화 
    # 위에서 정의한 설정을 바탕으로 세션 관리자를 생성합니다.
    session_manager = AgentCoreMemorySessionManager(
        agentcore_memory_config=config,
        region_name="us-west-2"
    )
    
    # 3. Strands Agent 생성 
    # session_manager를 주입하면 메모리 연동이 완료됩니다.
    agent = Agent(
        session_manager=session_manager
    )
    
    return agent

INFO: bedrock_agentcore.memory.client: Initialized MemoryClient for control plane: us-west-2
INFO: bedrock_agentcore.memory.client: Retrieved total of 1 events

# 기존에 생성한 메모리 ID 사용
memory_id = "test-long-term-memory-..." 
actor_id = "chanhosoh"
session_id = "session-1"

agent = create_strands_agent(memory_id, actor_id, session_id)

# 대화 진행
agent("안녕 내 이름은 찬호야")
agent("나는 서울에서 일하는 개발자야")
agent("나는 Python이랑 Rust를 좋아해")

# 동일 세션 내 질문: 단기 기억(Short-term Memory)을 활용하여 답변합니다.
agent("내 직업이 뭐라고 그랬지?")

INFO: bedrock_agentcore.memory.client: Created event: 0000001764903427355#5d6b9f20
INFO: bedrock_agentcore.memory.integrations.strands.session_manager: Created agent: default

# Long-term memory 생성을 위해 잠시 대기 (비동기 처리)
time.sleep(120)

# 새로운 세션 ID로 에이전트 재생성 (마치 며칠 뒤 다시 접속한 상황)
new_session_id = "session-2"
agent = create_strands_agent(memory_id, actor_id, new_session_id)

# 에이전트가 나를 기억하는지 테스트
agent("내 이름이 뭐야?")
agent("나는 무슨 프로그래밍 언어를 좋아해?")

INFO: bedrock_agentcore.memory.client: Retrieved memories from namespace: /preferences
INFO: bedrock_agentcore.memory.client: Retrieved memories from namespace: /facts/chanhosoh

[{
    'role': 'user', 
    'content': [{'text': '내 이름이 뭐야?'}]
}, 
{
    'role': 'assistant', 
    'content': [{'text': '<user_context>{"context":"사용자가 자신의 이름을 찬호라고 소개했습니다.","preference":"이름은 찬호","categories":["개인 정보"]}\n{"context":"사용자가 자신을 서울에서 일하는 개발자라고 직접 소개했습니다.","preference":"서울에서 개발자로 일함","categories":["직업","위치"]}\n{"context":"사용자가 Python과 Rust를 좋아한다고 명확히 표현했습니다.","preference":"Python과 Rust 프로그래밍 언어를 선호함","categories":["프로그래밍","기술","개발"]}\n사용자의 이름은 찬호이다.\n찬호는 Python과 Rust 프로그래밍 언어를 좋아한다.\n찬호는 서울에서 일하는 개발자이다.</user_context>'}]
}, 
{
    'role': 'assistant', 
    'content': [{'text': '\n\n찬호님이에요! 찬호님이 처음에 자기소개해 주실 때 말씀해 주셨죠 😊'}]
}]

# 1. 초기 대화 진행 (Main Branch)
# 사용자가 "오늘 날씨"를 묻고 답변을 받은 상태입니다.
event1 = memory_client.create_event(
    memory_id=memory['id'],
    actor_id=actor_id,
    session_id=session_id,
    messages=[
        ("오늘 날씨가 어때?", "USER"),
        ("오늘은 맑고 화창합니다.", "ASSISTANT")
    ]
)
root_event_id = event1.get('eventId') # 분기점이 될 이벤트 ID

# 2. 메인 대화 계속 진행
# 원래 흐름대로 "내일 날씨"를 묻습니다.
memory_client.create_event(
    memory_id=memory['id'],
    actor_id=actor_id,
    session_id=session_id,
    messages=[("내일은?", "USER"), ("내일은 비가 옵니다.", "ASSISTANT")]
)

# 3. Memory Forking: 다른 가능성 탐색
# "만약 사용자가 내일 날씨 대신 다음 주 날씨를 물어봤다면?"
forked_event = memory_client.fork_conversation(
    memory_id=memory['id'],
    actor_id=actor_id,
    session_id=session_id,
    root_event_id=root_event_id,       # 1번 이벤트 시점으로 돌아가서
    branch_name="weather-alternative", # 새로운 브랜치 이름 지정
    new_messages=[                     # 새로운 대화 흐름 주입
        ("다음 주는 어떨까?", "USER"),
        ("다음 주는 대체로 흐릴 것으로 예상됩니다.", "ASSISTANT")
    ]
)

print(f"✅ 분기 생성 완료: {forked_event.get('eventId')}")

# 전체 대화 트리 구조 조회
conversation_tree = memory_client.get_conversation_tree(
    memory_id=memory['id'],
    actor_id=actor_id,
    session_id=session_id
)

print(json.dumps(conversation_tree, indent=2, ensure_ascii=False))
"""
출력 예시:
{
    'session_id': 'session-003', 
    'actor_id': 'user-003', 
    'main_branch': {
        'events': [], 
        'branches': {
            'main': {
                'root_event_id': None, 
                'events': [{
                    'eventId': '0000001764919136838#8a280402', 
                    'timestamp': datetime.datetime(2025, 12, 5, 16, 18, 56, 838000, tzinfo=tzlocal()), 
                    'messages': [{
                        'role': 'USER', 
                        'text': '내일은?...'
                    }, 
                    {
                        'role': 'ASSISTANT', 
                        'text': '내일은 비가 올 예정입니다....'
                    }]}, 
                {
                    'eventId': '0000001764919135945#d33bf2e2', 
                    'timestamp': datetime.datetime(2025, 12, 5, 16, 18, 55, 945000, tzinfo=tzlocal()), 
                    'messages': [{
                        'role': 'USER', 
                        'text': '오늘 날씨가 어때?...'
                    }, 
                    {
                        'role': 'ASSISTANT', 'text': '오늘은 맑고 화창합니다....'
                    }]}, 
                {
                    'eventId': '0000001764907280746#04daf8d3', 
                    'timestamp': datetime.datetime(2025, 12, 5, 13, 1, 20, 746000, tzinfo=tzlocal()), 
                    'messages': [{
                        'role': 'USER', 'text': '내일은?...'
                    },
                    {
                        'role': 'ASSISTANT', 
                        'text': '내일은 비가 올 예정입니다....'
                    }]
                }, 
                {
                    'eventId': '0000001764907279934#e93a24ea', 
                    'timestamp': datetime.datetime(2025, 12, 5, 13, 1, 19, 934000, tzinfo=tzlocal()), 
                    'messages': [{
                        'role': 'USER', 'text': '오늘 날씨가 어때?...'
                    },
                    {
                        'role': 'ASSISTANT', 
                        'text': '오늘은 맑고 화창합니다....'
                    }]
                }
            ]}, 
            'weather-alternative': {
                'root_event_id': '0000001764907279934#e93a24ea', 
                'events': [{
                    'eventId': '0000001764907281044#087b9218', 
                    'timestamp': datetime.datetime(2025, 12, 5, 13, 1, 21, 44000, tzinfo=tzlocal()), 
                    'messages': [{'role': 'USER', 'text': '다음 주는 어떨까?...'}, 
                    {'role': 'ASSISTANT', 'text': '다음 주는 대체로 흐릴 것으로 예상됩니다....'}]
                }
            ]}
        }
    }
}
"""