메모리 생성

메모리 뱅크를 사용하면 사용자와 에이전트 간의 대화에서 장기 메모리를 생성할 수 있습니다. 이 페이지에서는 메모리 생성 방식, 메모리 추출 방식을 맞춤설정하는 방법, 메모리 생성을 트리거하는 방법을 설명합니다.

메모리 생성 이해

메모리 뱅크는 소스 데이터에서 메모리를 추출하고 일정 기간 동안 메모리를 추가, 업데이트, 삭제하여 특정 메모리 집합(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."""
      )
  )
  

  커스텀 주제를 사용할 때는 대화에서 메모리를 추출하는 방법을 보여주는 퓨샷 예시를 함께 제공하는 것이 좋습니다.

기본적으로 메모리 뱅크는 다음 관리형 주제를 모두 저장합니다.

• 개인 정보(USER_PERSONAL_INFO): 이름, 관계, 취미, 중요한 기념일 등 사용자에 관한 중요한 개인 정보입니다. ���: '나는 Google에서 일해', '내 결혼기념일은 12월 31일이야'
• 사용자 선호(USER_PREFERENCES): 명시적 또는 암시적인 기호, 불호, 선호 스타일이나 패턴입니다. 예: '중간 좌석이 좋아요'
• 주요 대화 이벤트 및 작업 결과(KEY_CONVERSATION_DETAILS): 대화 중 중요한 이정표 또는 결론입니다. 예: 'JFK에서 SFO까지 왕복 항공권을 예약했어요. 2025년 6월 1일 출발하고 2025년 6월 7일에 돌아올거에요.'
• 명시적 기억/망각 지시(EXPLICIT_INSTRUCTIONS): 사용자가 에이전트에게 명시적으로 기억하거나 잊도록 요청한 정보입니다. 예: 사용자가 '나는 주로 Python을 사용한다는 걸 기억해 줘'라고 말하면 메모리 뱅크는 '나는 주로 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 형식으로 직접 제공해야 합니다.

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": EVENTS
    },
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

[
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "I'm work with LLM agents!"}
      ]
    }
  }
]

client.agent_engines.memories.generate(
  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
  }
)

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: 기존 메모리가 업데이트되었음을 나타냅니다. 이는 새로 추출된 정보가 기존 메모리와 유사한 개념을 다룰 때 발생합니다. 메모리의 사실(fact)은 새 정보로 업데이트되거나 동일하게 유지될 수 있습니다.
• DELETED: 기존 메모리가 삭제되었음을 나타냅니다. 이는 대화에서 추출된 새로운 정보와 기존 정보가 모순될 때 발생합니다.

CREATED 또는 UPDATED 메모리의 경우 GetMemories를 사용하여 메모리의 전체 콘텐츠를 검색할 수 있습니다. DELETED 메모리를 검색하면 404 오류가 발생합니다.

백그라운드에서 메모리 생성

GenerateMemories는 장기 실행 작업입니다. 기본적으로 client.agent_engines.generate_memories는 차단 함수이며, 작업이 완료될 때까지 폴링을 계속합니다. 차단 작업으로 메모리 생성을 수행하면, 생성된 메모리를 수동으로 검사하거나 어떤 메모리가 생성되었는지 최종 사용자에게 알리고자 할 때 유용합니다.

하지만 프로덕션 에이전트의 경우 일반적으로 메모리 생성을 비동기 프로세스로 백그라운드에서 실행하는 것이 좋습니다. 대부분의 경우 클라이언트는 현재 실행에서 결과를 즉시 사용할 필요가 없으므로, 응답을 기다리면서 추가 지연을 발생시킬 필요가 없습니다. 메모리 생성을 백그라운드에서 실행하려면 wait_for_completion을 False로 설정하세요.

client.agent_engines.memories.generate(
    ...,
    config={
        "wait_for_completion": False
    }
)

사전 추출 메모리 통합

메모리 뱅크의 자동 추출 프로세스를 사용하는 대신 사전에 추출된 메모리를 직접 제공할 수도 있습니다. 직접 제공된 소스 메모리는 동일한 범위의 기존 메모리와 통합됩니다. 이는 메모리 추출을 에이전트 또는 인간 참여형 방식으로 처리하되, 메모리 뱅크의 통합 기능을 활용해 중복되거나 모순되는 메모리가 없도록 하고자 할 때 유용합니다.

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

다음을 바꿉니다.

• FACT: 기존 메모리와 통합해야 하는 사전 추출된 사실(fact)입니다. 최대 5개의 사전 추출된 사실(fact)을 목록으로 제공할 수 있습니다.

  {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
  

• SCOPE: 생성된 메모리의 범위를 나타내는 사전입니다. 예를 들면 {"session_id": "MY_SESSION"}입니다. 동일한 범위의 메모리만 통합 대상으로 간주됩니다.

다음 단계

• 생성된 메모리 가져오기
• 메모리 추출 동작 맞춤설정