生成回憶集錦

Agent Platform Memory Bank 可讓您從使用者與代理之間的對話建構長期記憶。觸發後，系統會自動執行這項程序，擷取有價值的資訊，供日後互動使用。

本文說明記憶生成功能的運作方式、如何使用主題自訂記憶擷取，以及如何觸發記憶生成要求。

如要瞭解如何設定環境，請參閱「設定 Memory Bank」。

瞭解記憶生成

Memory Bank 會從來源資料擷取記憶，並隨著時間新增、更新及移除記憶，為特定記憶集合 (由 scope 定義) 自行策劃記憶。

觸發生成記憶時，記憶庫會執行下列作業：

  • 擷取：從使用者與代理的對話中擷取使用者相關資訊。系統只會保留與至少一個執行個體記憶體主題相符的資訊。

  • 合併：根據擷取的資訊，判斷是否應刪除或更新範圍相同的現有記憶內容。Memory Bank 會先檢查新記憶是否重複或矛盾，再與現有記憶合併。如果現有記憶與新資訊不重疊，系統會建立新的記憶。

記憶生成演算法

您可以使用記憶體修訂版本檢查記憶體生成的中間步驟，並查看記憶體在多個要求中的變化。每個修訂版本都包含每個記憶體生成要求的擷取步驟 (extracted_memories) 中間輸出內容，以及最終合併步驟 (fact)。

list(client.memory_banks.memories.revisions.list(
  name="projects/.../locations/.../reasoningEngines/.../memories/.../revisions/..."))

"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    extracted_memories=[
      IntermediateExtractedMemory(
        fact='This is the output of extraction for a single request.'
      ),
    ],
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    extracted_memories=[
      IntermediateExtractedMemory(
        fact='This is my original fact.'
      ),
    ],
    ...
  )
]
"""

個人化記憶主題

「記憶主題」會識別 Memory Bank 認為有意義的資訊，並將其保留為生成的回憶。Memory Bank 支援兩種記憶主題：

  • 管理主題：標籤和操作說明由 Memory Bank 定義。您只需要提供受管理主題的名稱。例如：

    字典

    memory_topic = {
    "managed_memory_topic": {
        "managed_topic_enum": "USER_PERSONAL_INFO"
    }
}

    以課程為準

    from agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

memory_topic = MemoryTopic(
    managed_memory_topic=ManagedMemoryTopic(
        managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO
    )
)

  • 自訂主題：設定 Memory Bank 執行個體時，您可以定義標籤和指令。這些值會用於 Memory Bank 擷取步驟的提示。例如：

    字典

    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 agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.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 agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.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)),
]

如要自訂 Memory Bank 保留的主題，請在設定 Memory Bank 時，於自訂設定中設定記憶體主題。

在合併期間使用中繼資料

您可以將中繼資料附加至生成的回憶集錦。中繼資料可讓您在記憶體事實旁儲存結構化資訊 (字串、雙精度浮點數、布林值或時間戳記)。這對篩選或管理記憶體生命週期很有幫助。

字典

import datetime

client.memory_banks.memories.generate(
    ...,
    config={
        "metadata": {
            "my_string_key": {"string_value": "my_string_value"},
            "my_double_key": {"double_value": 123.456},
            "my_boolean_key": {"bool_value": True},
            "my_timestamp_key": {
                "timestamp_value": datetime.datetime(
                    2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
                )
            }
        },
        "metadata_merge_strategy": "MERGE"
    },
)

以課程為準

import datetime

from agentplatform import types

client.memory_banks.memories.generate(
    ...,
    config=types.GenerateMemoriesConfig(
        metadata={
            "my_string_key": types.MemoryMetadataValue(string_value="my_string_value"),
            "my_double_key": types.MemoryMetadataValue(double_value=123.456),
            "my_boolean_key": types.MemoryMetadataValue(bool_value=True),
            "my_timestamp_key": types.MemoryMetadataValue(
                timestamp_value=datetime.datetime(
                    2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
                )
            ),
        },
        metadata_merge_strategy=types.MemoryMetadataMergeStrategy.MERGE,
    )
)

使用 metadata_merge_strategy，即可控管新中繼資料在合併期間與現有回憶內容的互動方式：

  • MERGE：(預設) 將新中繼資料與現有中繼資料合併。如果鍵已存在，新值會覆寫舊值。

  • OVERWRITE：以新中繼資料取代更新回憶集的中繼資料。

  • REQUIRE_EXACT_MATCH：將合併作業限制為與要求中繼資料完全相同的回憶集。如果回憶集錦的中繼資料不同，就不符合合併資格，也不會更新。

為部分主題生成回憶集錦

根據預設，記憶功能會擷取您設定 Memory Bank 執行個體時設定的所有記憶主題資料。針對特定 GenerateMemories 要求，您可以將擷取範圍限制在已設定主題的子集。如要設定允許的主題，請使用 allowed_topics 欄位。

字典

client.memory_banks.memories.generate(
    ...,
    config={
        "allowed_topics": [
            {"managed_memory_topic": "USER_PERSONAL_INFO"},
            {"custom_memory_topic_label": "business_feedback"}
        ]
    },
)

以課程為準

from agentplatform import types

client.memory_banks.memories.generate(
    ...,
    config=types.GenerateMemoriesConfig(
        allowed_topics=[
            types.MemoryTopicId(
                managed_memory_topic=types.ManagedTopicEnum.USER_PERSONAL_INFO
            ),
            types.MemoryTopicId(
                custom_memory_topic_label="business_feedback"
            )
        ]
    )
)

觸發記憶生成

你可以使用下列任一方法觸發記憶體生成：

  • GenerateMemories：將資料擷取至記憶庫，並立即觸發記憶生成作業。如果想在特定時間點生成記憶，例如工作階段結束時，或在工作階段中定期生成，這個方法就非常實用。
  • IngestEvents：持續將資料擷取至記憶體庫，並在符合觸發條件時，讓記憶體庫處理資料。如果事件串流持續不斷，且希望記憶庫自動處理緩衝，並根據數量或時間觸發記憶生成，這個方法就非常實用。詳情請參閱「擷取事件」。

系統會從來源對話擷取重要脈絡，並與相同範圍的現有記憶合併，舉例來說，您可以使用 {"user_id": "123", "session_id": "456"} 等範圍建立工作階段層級的記憶體。相同範圍的記憶可以合併，並一起擷取。

GenerateMemories 是長時間執行的作業。 作業完成後，GenerateMemoriesOperation 會包含產生的回憶集錦清單 (如有)：

GenerateMemoriesOperation(
  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.memory_banks.memories.generate 是封鎖函式，會輪詢作業，直到作業完成為止。如要手動檢查生成的記憶內容，或通知使用者生成了哪些記憶內容，以封鎖作業的形式執行記憶內容生成作業會很有幫助。

不過，對於正式版代理程式，您通常會希望在背景以非同步程序執行記憶體生成作業。在多數情況下，用戶端不需要使用目前執行的輸出內容，因此不必為了等待回應而產生額外延遲。如要讓記憶生成作業在背景執行，請將 wait_for_completion 設為 False：

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

除了非同步呼叫 GenerateMemories，您也可以使用 IngestEvents，將事件擷取作業與記憶體產生作業分離，並預設在背景處理事件。

資料來源

你可以透過多種方式提供記憶內容的來源資料：

直接在酬載中提供事件或使用 Sessions 時，系統會從對話中擷取資訊，並與現有記憶整合。如果只想從這些資料來源擷取資訊，可以停用合併功能：

client.memory_banks.memories.generate(
    ...
    config={
        "disable_consolidation": True
    }
)

使用酬載中的事件做為資料來源

如要使用酬載中直接提供的事件生成回憶集錦，請使用 direct_contents_source。系統會從這些事件中擷取有意義的資訊，並與相同範圍的現有資訊整合。如果您使用的工作階段儲存空間與 Agent Platform Sessions 不同，可以採用這種方法。

字典

事件應包含 Content 字典。

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

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_contents_source={
      "events": EVENTS
    },
    # For example, `scope={"user_id": "123"}`.
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

更改下列內容：

  • SCOPE：字典，代表生成的記憶範圍。例如，{"session_id": "MY_SESSION"}。只有範圍相同的記憶才會納入整合考量。

以類別為基礎

事件應包含 Content 物件。

from google import genai
from agentplatform import types

events = [
  types.GenerateMemoriesRequestDirectContentsSourceEvent(
    content=genai.types.Content(
      role="user",
      parts=[
        genai.types.Part.from_text(text="I work with LLM agents!")
      ]
    )
  )
]

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_contents_source={
      "events": events
    },
    # For example, `scope={"user_id": "123"}`.
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

更改下列內容：

  • SCOPE：字典，代表生成的記憶範圍。例如，{"session_id": "MY_SESSION"}。只有範圍相同的記憶體才會合併。

使用 Agent Platform 工作階段做為資料來源

使用 Sessions 時，Memory Bank 會將工作階段事件做為來源對話，生成記憶內容。

根據預設，Memory Bank 會從工作階段擷取並使用使用者 ID，藉此限定生成的記憶範圍。舉例來說，如果工作階段user_id為「123」，記憶的範圍會儲存為 {"user_id": "123"}。您也可以直接提供 scope，這會覆寫使用工作階段的 user_id 做為範圍。

字典

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source={
      # For example, projects/.../locations/.../reasoningEngines/.../sessions/...
      "session": "SESSION_NAME"
  },
  # Optional when using 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}。

以課程為準

from agentplatform import types

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source=types.GenerateMemoriesRequestVertexSessionSource(
      # For example, projects/.../locations/.../reasoningEngines/.../sessions/...
      session="SESSION_NAME"
  ),
  # Optional when using Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

你也可以視需要提供日期範圍，指出應納入哪些工作階段事件。如未提供，系統會納入工作階段中的所有事件。

字典

import datetime

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source={
      "session": "SESSION_NAME",
      # Extract memories from the last hour of events.
      "start_time": datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
      "end_time": datetime.datetime.now(tz=datetime.timezone.utc)
  },
  scope=SCOPE
)

以課程為準

import datetime

from agentplatform import types

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source=types.GenerateMemoriesRequestVertexSessionSource(
      session="SESSION_NAME",
      # Extract memories from the last hour of events.
      start_time=datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
      end_time=datetime.datetime.now(tz=datetime.timezone.utc)
  ),
  scope=SCOPE
)

整合預先擷取的記憶

除了使用記憶體庫的自動擷取程序，您也可以直接提供預先擷取的記憶。直接來源記憶體會與相同範圍的現有記憶體合併。如果您希望由代理程式或人工介入迴路負責擷取記憶內容，但仍想利用 Memory Bank 的整合功能，確保沒有重複或矛盾的記憶內容，這項功能就非常實用。

client.memory_banks.memories.generate(
    name=memory_bank.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"}。只有相同範圍的記憶體才會合併。

使用多模態輸入

您可以從多模態輸入內容中擷取記憶內容。不過，系統只會從來源內容中的文字、內嵌檔案和檔案資料擷取記憶。生成回憶時，系統會忽略所有其他內容，包括函式呼叫和回覆。

系統可從使用者提供的圖片、影片和音訊中擷取記憶內容。如果 Memory Bank 判斷多模態輸入內容提供的脈絡對日後互動有意義，系統可能會建立文字記憶，包括從輸入內容擷取的資訊。舉例來說，如果使用者提供黃金獵犬的圖片和「這是我的狗」文字，記憶庫就會生成「我的狗是黃金獵犬」等記憶。

舉例來說，您可以在酬載中提供圖片和圖片情境：

字典

with open(file_name, "rb") as f:
    inline_data = f.read()

events =  [
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "This is my dog"},
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": inline_data
          }
        },
        {
          "file_data": {
            "file_uri": "gs://cloud-samples-data/generative-ai/image/dog.jpg",
            "mime_type": "image/jpeg"
          }
        },
      ]
    }
  }
]

以課程為準

from google import genai
from agentplatform import types

with open(file_name, "rb") as f:
    inline_data = f.read()

events = [
  types.GenerateMemoriesRequestDirectContentsSourceEvent(
    content=genai.types.Content(
      role="user",
      parts=[
        genai.types.Part.from_text(text="This is my dog"),
        genai.types.Part.from_bytes(
          data=inline_data,
          mime_type="image/jpeg",
        ),
        genai.types.Part.from_uri(
          file_uri="gs://cloud-samples-data/generative-ai/image/dog.jpg",
          mime_type="image/jpeg",
        )
      ]
    )
  )
]

後續步驟

指南

瞭解如何擷取生成和上傳的回憶集錦。

指南

瞭解如何設定 Memory Bank。

指南

瞭解如何檢查記憶體修訂版本。