您可以使用 Agent Platform SDK 直接对记忆库进行 API 调用。如果您不希望智能体框架为您编排调用，或者您希望将记忆库与智能体开发套件 (ADK) 以外的智能体框架集成，请使用 Agent Platform SDK。
本文档介绍了如何使用 API 调用创建、上传、检索和移除记忆。
如需了解使用 ADK 的快速入门，请参阅使用 ADK的记忆库快速入门。
准备工作
如需完成本教程中演示的步骤，您必须先按照 设置记忆库 中的步骤操作。在开始本快速入门之前，请确保您已创建记忆库实例和会话实例，如以下示例所示：
import vertexai
client = vertexai.Client(
project="PROJECT_ID",
location="LOCATION"
)
memory_bank = client.agent_engines.create()
sessions = client.agent_engines.create()
使用 Agent Platform 会话生成记忆
设置 Agent Platform 会话后，您可以创建会话并向其中附加事件。然后，您可以使用记忆库根据用户与智能体的对话生成记忆，以便在未来的用户互动中使用这些记忆。如需了解详情，请参阅 生成记忆 和提取记忆。
使用不透明的用户 ID 创建会话。除非您在生成记忆时明确提供范围 ，否则从该 会话生成的任何记忆都会自动按范围
{"user_id": "USER_ID"}进行键控。import vertexai client = vertexai.Client( project="PROJECT_ID", location="LOCATION" ) session = client.agent_engines.sessions.create( # The name can be fetched using `sessions.api_resource.name`. name="SESSIONS_NAME", user_id="USER_ID" )替换以下内容：
PROJECT_ID：您的项目 ID。
LOCATION：您的区域。请参阅记忆库 支持的区域。
SESSIONS_NAME：您创建的会话实例的名称或现有会话实例的名称。名称应 采用以下格式：
projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}。USER_ID：您的用户的标识符。除非您在生成记忆时明确提供范围 ，否则从该会话生成的任何记忆都会自动按范围
{"user_id": "USER_ID"}进行键控 。
以迭代方式将事件上传到会话。事件可以包括用户、智能体和工具之间的任何互动。事件的有序列表表示会话的对话记录。此对话记录用作生成特定用户记忆的源材料。
import datetime client.agent_engines.sessions.events.append( name=session.response.name, author="user", # Required by Sessions. invocation_id="1", # Required by Sessions. timestamp=datetime.datetime.now(tz=datetime.timezone.utc), # Required by Sessions. config={ "content": { "role": "user", "parts": [{"text": "hello"}] } } )如需根据对话记录生成记忆，请为会话触发记忆生成请求：
client.agent_engines.memories.generate( name=memory_bank.api_resource.name, vertex_session_source={ # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...". "session": session.response.name }, # Optional when using Sessions. Defaults to {"user_id": session.user_id}. scope=SCOPE )
替换以下内容：
- （可选）SCOPE：一个字典，用于表示
生成的记忆的范围，最多包含 5 个键值对，且不包含
*字符。例如，{"session_id": "MY_SESSION"}。只有具有相同范围的记忆才会考虑进行整合。如果未提供，则使用{"user_id": session.user_id}。
上传记忆
除了使用原始对话生成记忆之外，您还可以上传记忆，或者让智能体使用预提取的事实直接添加记忆。GenerateMemories您无需让记忆库从内容中提取信息，而是直接提供应存储的有关用户的事实。
为确保与生成的记忆保持一致，请尝试以您为给定范围配置的
相同视角编写预提取的事实。默认情况下，记忆以第一人称视角生成（例如，I
am a software engineer）。
client.agent_engines.memories.generate(
name=memory_bank.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"}。只有具有相同范围的记忆才会考虑进行整合。
或者，您也可以使用 CreateMemory 上传记忆，而无需使用记忆库进行记忆提取或整合。
memory = client.agent_engines.memories.create(
name=memory_bank.api_resource.name,
fact="This is a fact.",
scope={"user_id": "123"}
)
"""
Returns an AgentEngineMemoryOperation containing the created Memory like:
AgentEngineMemoryOperation(
done=True,
metadata={
"@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
"genericMetadata": {
"createTime": '2025-06-26T01:15:29.027360Z',
"updateTime": '2025-06-26T01:15:29.027360Z'
}
},
name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
response=Memory(
create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
fact="This is a fact.",
name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
scope={
"user_id": "123"
},
update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
)
)
"""
检索和使用记忆
您可以检索用户的记忆，并将其纳入到系统指令中，以便让 LLM 访问您的个性化上下文。
如需详细了解如何使用基于范围的方法检索记忆，请参阅 提取记忆。
# Retrieve memories for User ID 123.
retrieved_memories = client.agent_engines.memories.retrieve(
name=memory_bank.api_resource.name,
scope={"user_id": "123"}
).page
您可以使用 jinja 将结构化的记忆转换为提示：
from jinja2 import Template
template = Template("""
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")
prompt = template.render(data=retrieved_memories)
"""
Output:
<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""
移除记忆
您可以采用多种方式从记忆库实例中删除记忆，具体取决于您希望如何选择应移除的记忆。
按资源名称移除
如果您确切知道要移除哪个记忆资源，则可以使用其资源名称删除特定记忆：
client.agent_engines.memories.delete(
name=MEMORY_NAME,
config={
# Set to false (default) if you want to delete the memory asynchronously.
"wait_for_completion": True
}
)
替换以下内容：
- MEMORY_NAME：要删除的记忆的名称。名称应采用以下格式：
projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}。您可以通过提取 记忆来查找记忆名称。
按条件移除
您可以使用基于条件的删除来移除一个或多个记忆。系统只会删除与提供的过滤条件匹配的记忆。您必须至少指定 filter（应用于系统字段）或 filter_groups（应用于
元数据字段）中的一个。
operation = client.agent_engines.memories.purge(
name=memory_bank.api_resource.name,
# Specify at least one of `filter` or `filter_groups`.
filter="FILTER_STRING",
filter_groups=FILTER_GROUPS,
# Set to false (default) if you want to stage but not execute the purge operation.
force=True,
config={
# Set to false (default) if you want to purge memories asynchronously.
"wait_for_completion": True
}
)
替换以下内容：
- FILTER_STRING：使用
EBNF语法针对系统字段进行过滤的字符串。系统字段包括
create_time、update_timefact和topics。 如需详细了解如何针对系统字段进行过滤，请参阅提取记忆页面上的Filter by metadata fields 部分。 - FILTER_GROUPS：用于针对记忆元数据进行过滤 的字典或对象列表。如需详细了解如何针对 元数据字段进行过滤，请参阅提取记忆页面上的按系统 字段 过滤部分。
该操作将返回已清除的记忆数量（如果 force=True）或如果执行该操作将清除的记忆数量（如果 force=False）。
print(operation.response.purge_count)
例如，您可以清除属于 user_id“123”范围的所有记忆：
operation = client.agent_engines.memories.purge(
name=memory_bank.api_resource.name,
filter="scope.user_id=\"123\""
force=True
)
按语义移除
在生成记忆期间，
记忆库将根据新提取的信息的内容和
现有记忆来决定是创建、更新还是删除
记忆。如果新信息与记忆相矛盾
或者提取的内容指示记忆库忘记某个
主题（对于 EXPLICIT_INSTRUCTIONS 记忆
主题），则可能会删除记忆。
例如，如果给定 scope 存在包含饮食偏好信息的现有记忆，则以下请求会删除这些记忆：
from google import genai
client.agent_engines.memories.generate(
name=memory_bank.api_resource.name,
direct_contents_source={
"events": [{
"content": genai.types.Content(
role="user",
parts=[
genai.types.Part.from_text(text="Forget my dietary preferences.")
]
)
}]
},
scope={...}
)
清理
如需清理此项目中使用的所有资源，您可以删除 Google Cloud 用于本快速入门的 项目。
否则，您可以按如下所示逐个删除在本教程中创建的资源：
使用以下代码示例删除 Agent Platform 实例，这也会删除与 Agent Platform 实例关联的任何会话或记忆。
agent_engine.delete(force=True)删除所有本地创建的文件。