메모리 뱅크를 사용하면 사용자와 에이전트 간의 대화에서 장기 메모리를 구성할 수 있습니다. 이 페이지에서는 기억 생성의 작동 방식, 기억 추출 방식을 맞춤설정하는 방법, 기억 생성을 트리거하는 방법을 설명합니다.
메모리 생성 이해하기
Memory Bank는 소스 데이터에서 기억을 추출하고 시간이 지남에 따라 기억을 추가, 업데이트, 삭제하여 특정 기억 모음 (scope로 정의됨)의 기억을 자체 선별합니다.
메모리 생성을 트리거하면 메모리 뱅크가 다음 작업을 실행합니다.
추출: 상담사와의 대화에서 사용자에 관한 정보를 추출합니다. 인스턴스의 메모리 주제 중 하나 이상과 일치하는 정보만 유지됩니다.
통합: 추출된 정보를 기반으로 동일한 범위의 기존 추억을 삭제하거나 업데이트해야 하는지 식별합니다. 메모리 뱅크는 새 추억을 기존 추억과 병합하기 전에 중복되거나 모순되지 않는지 확인합니다. 기존 메모리가 새 정보와 중복되지 않으면 새 메모리가 생성됩니다.
메모리는 소스 콘텐츠의 텍스트, 인라인 파일, 파일 데이터에서만 추출할 수 있습니다. 추억을 생성할 때는 함수 호출 및 응답을 비롯한 다른 모든 콘텐츠가 무시됩니다.
추억은 사용자가 제공한 이미지, 동영상, 오디오에서 추출할 수 있습니다. 멀티모달 입력에서 제공된 컨텍스트가 메모리 뱅크에서 향후 상호작용에 유의미하다고 판단되면 입력에서 추출한 정보를 포함한 텍스트 메모리가 생성될 수 있습니다. 예를 들어 사용자가 '이것은 내 강아지야'라는 텍스트와 함께 골든 리트리버 이미지를 제공하면 메모리 은행에서 '내 강아지는 골든 리트리버야'와 같은 메모리를 생성합니다.
추억 주제
'메모리 주제'는 메모리 뱅크에서 의미가 있다고 간주하여 생성된 메모리로 유지해야 하는 정보를 식별합니다. 메모리 뱅크는 두 가지 유형의 메모리 주제를 지원합니다.
관리형 주제: 라벨과 안내는 메모리 뱅크에 의해 정의됩니다. 관리 주제의 이름만 제공하면 됩니다. 예를 들면 다음과 같습니다.
딕셔너리
memory_topic = { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } }클래스 기반
from vertexai.types import ManagedTopicEnum from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic memory_topic = MemoryTopic( managed_memory_topic=ManagedMemoryTopic( managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO ) )맞춤 주제: 메모리 뱅크 인스턴스를 설정할 때 라벨과 안내가 정의됩니다. 이러한 정보는 메모리 뱅크의 추출 단계 프롬프트에 사용됩니다. 예를 들면 다음과 같습니다.
딕셔너리
memory_topic = { "custom_memory_topic": { "label": "business_feedback", "description": """Specific user feedback about their experience at the coffee shop. This includes opinions on drinks, food, pastries, ambiance, staff friendliness, service speed, cleanliness, and any suggestions for improvement.""" } }클래스 기반
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic memory_topic = MemoryTopic( custom_memory_topic=CustomMemoryTopic( label="business_feedback", description="""Specific user feedback about their experience at the coffee shop. This includes opinions on drinks, food, pastries, ambiance, staff friendliness, service speed, cleanliness, and any suggestions for improvement.""" ) )맞춤 주제를 사용하는 경우 대화에서 추억을 추출하는 방법을 보여주는 퓨샷 예시도 제공하는 것이 좋습니다.
기본적으로 Memory Bank는 다음 관리 주제를 모두 유지합니다.
- 개인 정보 (
USER_PERSONAL_INFO): 이름, 관계, 취미, 중요한 날짜 등 사용자에 관한 중요한 개인 정보입니다. 예를 들어 '나는 Google에서 일해' 또는 '내 결혼기념일은 12월 31일이야'라고 말하면 됩니다. - 사용자 선호도 (
USER_PREFERENCES): 명시적 또는 암시적 좋아요, 싫어요, 선호하는 스타일 또는 패턴입니다. 예를 들어 '중간 좌석을 선호합니다'라고 말할 수 있습니다. - 주요 대화 이벤트 및 작업 결과 (
KEY_CONVERSATION_DETAILS): 대화 내의 중요한 단계 또는 결론입니다. 예를 들어 'JFK와 SFO 간 왕복 항공권을 예약했어. 2025년 6월 1일에 출발하여 2025년 6월 7일에 돌아옵니다.' - 명시적 기억 / 잊기 요청 (
EXPLICIT_INSTRUCTIONS): 사용자가 에이전트에게 기억하거나 잊도록 명시적으로 요청한 정보입니다. 예를 들어 사용자가 '주로 Python을 사용한다고 기억해 줘'라고 말하면 Memory Bank는 '주로 Python을 사용합니다'와 같은 메모리를 생성합니다.
이는 다음 관리 메모리 주제를 사용하는 것과 같습니다.
딕셔너리
memory_topics = [
{"managed_memory_topic": {"managed_topic_enum": "USER_PERSONAL_INFO"}},
{"managed_memory_topic": {"managed_topic_enum": "USER_PREFERENCES"}},
{"managed_memory_topic": {"managed_topic_enum": "KEY_CONVERSATION_DETAILS"}},
{"managed_memory_topic": {"managed_topic_enum": "EXPLICIT_INSTRUCTIONS"}},
]
클래스 기반
from vertexai.types import ManagedTopicEnum
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
memory_topics = [
MemoryTopic(
managed_memory_topic=ManagedMemoryTopic(
managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)),
MemoryTopic(
managed_memory_topic=ManagedMemoryTopic(
managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)),
MemoryTopic(
managed_memory_topic=ManagedMemoryTopic(
managed_topic_enum=ManagedTopicEnum.KEY_CONVERSATION_DETAILS)),
MemoryTopic(
managed_memory_topic=ManagedMemoryTopic(
managed_topic_enum=ManagedTopicEnum.EXPLICIT_INSTRUCTIONS)),
]
메모리 뱅크에서 유지할 주제를 맞춤설정하려면 메모리 뱅크를 설정할 때 맞춤설정 구성에서 메모리 주제를 설정하세요.
추억 생성
이 가이드에 설명된 단계를 완료하려면 먼저 메모리 뱅크 설정의 단계를 따라야 합니다.
세션이 끝날 때 또는 세션 내에서 정기적으로 GenerateMemories를 사용하여 메모리 생성을 트리거할 수 있습니다. 기억 생성은 소스 대화에서 핵심 컨텍스트를 추출하여 동일한 범위의 기존 기억과 결합합니다. 예를 들어 {"user_id": "123", "session_id": "456"}와 같은 범위를 사용하여 세션 수준 기억을 만들 수 있습니다. 범위가 동일한 기억은 통합하여 함께 검색할 수 있습니다.
GenerateMemories를 호출할 때는 Agent Engine 세션을 통해 또는 JSON 형식을 통해 직접 소스 대화를 제공해야 합니다.
JSON 형식
Agent Engine 세션과 다른 세션 스토리지를 사용하는 경우 소스 대화를 JSON 형식으로 직접 제공합니다.
client.agent_engines.generate_memories(
name=agent_engine.api_resource.name,
direct_contents_source={
"events": EVENTS
},
scope=SCOPE,
config={
"wait_for_completion": True
}
)
다음을 바꿉니다.
- EVENTS: 콘텐츠 사전 목록입니다. 예를 들면 다음과 같습니다.
[
{
"content": {
"role": "user",
"parts": [
{"text": "I'm work with LLM agents!"}
]
}
}
]
- SCOPE: 생성된 기억의 범위를 나타내는 사전. 예를 들면
{"session_id": "MY_SESSION"}입니다. 동일한 범위의 기억만 통합 대상으로 간주됩니다.
Agent Engine 세션
Agent Engine 세션을 사용하면 메모리 뱅크에서 세션 이벤트를 기억 생성의 소스 대화로 사용합니다.
생성된 기억의 범위를 지정하기 위해 메모리 뱅크는 기본적으로 세션에서 사용자 ID를 추출하여 사용합니다. 예를 들어 세션의 user_id이 '123'이면 메모리의 범위가 {"user_id": "123"}로 저장됩니다. 세션의 user_id를 범위로 사용하는 것을 재정의하는 scope를 직접 제공할 수도 있습니다.
client.agent_engines.generate_memories(
name=agent_engine.api_resource.name,
vertex_session_source={
"session": "SESSION_NAME"
},
# Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
scope=SCOPE,
config={
"wait_for_completion": True
}
)
다음을 바꿉니다.
SESSION_NAME: 세션 이름입니다.
(선택사항) SCOPE: 생성된 기억의 범위를 나타내는 사전입니다. 예를 들면
{"session_id": "MY_SESSION"}입니다. 동일한 범위의 기억만 통합 대상으로 간주됩니다. 입력하지 않으면{"user_id": session.user_id}이 사용됩니다.
GenerateMemories는 장기 실행 작업입니다. 작업이 완료되면 AgentEngineGenerateMemoriesOperation에 생성된 추억 목록이 포함됩니다(생성된 추억이 있는 경우).
AgentEngineGenerateMemoriesOperation(
name="projects/.../locations/.../reasoningEngines/.../operations/...",
done=True,
response=GenerateMemoriesResponse(
generatedMemories=[
GenerateMemoriesResponseGeneratedMemory(
memory=Memory(
"name": "projects/.../locations/.../reasoningEngines/.../memories/..."
),
action="CREATED",
),
GenerateMemoriesResponseGeneratedMemory(
memory=Memory(
"name": "projects/.../locations/.../reasoningEngines/.../memories/..."
),
action="UPDATED",
),
GenerateMemoriesResponseGeneratedMemory(
memory=Memory(
"name": "projects/.../locations/.../reasoningEngines/.../memories/..."
),
action="DELETED",
),
]
)
)
생성된 각 메모리에는 해당 메모리에서 실행된 action가 포함됩니다.
CREATED: 기존 추억에서 포착되지 않은 새로운 개념을 나타내는 새 추억이 추가되었음을 나타냅니다.UPDATED: 기존 메모리가 업데이트되었음을 나타냅니다. 이는 메모리가 새로 추출된 정보와 유사한 개념을 다룬 경우에 발생합니다. 메모리의 사실은 새로운 정보로 업데이트되거나 동일하게 유지될 수 있습니다.DELETED: 기존 메모리가 삭제되었음을 나타냅니다. 이는 메모리의 정보가 대화에서 추출된 새 정보와 모순되기 때문입니다.
CREATED 또는 UPDATED 기억의 경우 GetMemories를 사용하여 기억의 전체 콘텐츠를 검색할 수 있습니다. DELETED 추억을 가져오면 404 오류가 발생합니다.
백그라운드에서 추억 생성
GenerateMemories는 장기 실행 작업입니다. 기본적으로 client.agent_engines.generate_memories은 차단 함수이며 작업이 완료될 때까지 계속 폴링합니다. 차단 작업으로 메모리 생성을 실행하는 것은 생성된 메모리를 수동으로 검사하거나 생성된 메모리에 관해 최종 사용자에게 알리려는 경우에 유용합니다.
하지만 프로덕션 에이전트의 경우 일반적으로 비동기 프로세스로 백그라운드에서 기억 생성을 실행하는 것이 좋습니다. 대부분의 경우 클라이언트는 현재 실행의 출력을 사용할 필요가 없으므로 응답을 기다리는 추가 지연 시간을 발생시킬 필요가 없습니다. 기억 생성이 백그라운드에서 실행되도록 하려면 wait_for_completion을 False로 설정합니다.
client.agent_engines.generate_memories(
...,
config={
"wait_for_completion": False
}
)
사전 추출된 메모리 통합
메모리 뱅크의 자동 추출 프로세스를 사용하는 대신 미리 추출된 메모리를 직접 제공할 수 있습니다. 직접 소스 기억은 동일한 범위의 기존 기억과 통합됩니다. 이는 에이전트 또는 사람-인-더-루프가 메모리 추출을 담당하도록 하되 중복되거나 모순되는 메모리가 없도록 메모리 뱅크의 통합 기능을 활용하려는 경우에 유용합니다.
client.agent_engines.generate_memories(
name=agent_engine.api_resource.name,
direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
scope=SCOPE
)
다음을 바꿉니다.
FACT: 기존 메모리와 통합해야 하는 사전 추출된 사실입니다. 다음과 같은 목록에 최대 5개의 사전 추출된 사실을 제공할 수 있습니다.
{"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}SCOPE: 생성된 기억의 범위를 나타내는 사전. 예를 들면
{"session_id": "MY_SESSION"}입니다. 동일한 범위의 기억만 통합 대상으로 간주됩니다.