このドキュメントでは、Agent Platform SDK を使用してこれらのフェッチ オペレーションを使用する方法について説明します。
Agent Development Kit（ADK）を使用すると、エージェントがこれらの呼び出しを自動的にオーケストレートできます。ADK のクイックスタートをご覧ください。
始める前に
このページの手順を完了するには、まず メモリバンクの設定の手順を完了する必要があります。
フェッチ オペレーション
生成されたメモリを取得するには、次のオプションがあります。
メモリを取得する: Agent Platform SDK を使用して、単一のメモリのコンテンツ全体を取得します。
メモリを取得する: Agent Platform SDK を使用して、スコープベースのメモリ取得を使用してメモリを取得します。類似性検索またはスコープ内のすべてのメモリを使用して、メモリを取得します。
メモリを一覧表示する: Agent Platform SDK を使用してメモリを一覧表示します。
メモリを取得する
GetMemories を使用して、単一のメモリのコンテンツ全体を取得します。
memory = client.memory_banks.memories.get(
name="MEMORY_NAME")
次のように置き換えます。
MEMORY_NAME: 「projects/.../locations/.../reasoningEngines/.../memories...」形式の完全修飾メモリ名。
スコープベースの取得を使用してメモリを取得する
RetrieveMemories を使用して、特定のスコープのメモリを取得できます。取得リクエストと同じスコープ（順序は関係ありません）を持つメモリのみが返されます。たとえば、{"user_id": "123"} を使用して、特定のユーザーにスコープ設定されたすべてのメモリを取得できます。メモリが返されない場合、メモリバンクには指定されたスコープのメモリがありません。
メモリのスコープは、メモリの生成時または作成時に定義され、変更できません。
RetrieveMemories を使用して、特定のスコープに対して次のオペレーションを実行できます。
類似性検索を使用してメモリを取得する
特定のスコープに多くのメモリがある場合は、類似性検索パラメータを指定して類似性検索を使用すると、最も類似したメモリのみを取得できます。Memory Bank は、類似性検索を実行する際に、リクエストとまったく同じスコープを持つメモリのみを考慮します。類似性検索では、メモリの事実とリクエストの検索クエリのエンベディング ベクトルを比較します。
返されたメモリは、最も類似している（ユークリッド距離が最も短い）ものから最も類似していない（ユークリッド距離が最も長い）ものの順に並べ替えられます。
results = client.memory_banks.memories.retrieve(
name=memory_bank.name,
scope=SCOPE,
similarity_search_params={
"search_query": "QUERY",
# Optional. Defaults to 3.
"top_k": 3
}
)
# RetrieveMemories returns a pager. You can use `page` to retrieve memories.
results.page
"""
Returns:
[
RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
name="projects/.../locations/.../reasoningEngines/.../memories/...",
...
fact="This is a fact."
},
distance=0.5
),
RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
name="projects/.../locations/.../reasoningEngines/.../memories/...",
...
fact="This is another fact."
},
distance=0.7
),
]
"""
次のように置き換えます。
QUERY: 類似検索を実行するクエリ。たとえば、会話の最後のユーザーターンをクエリとして使用できます。SCOPE: 類似検索のスコープを表す辞書。例:{"user_id": "123"}リクエストと同じスコープのメモリのみが考慮されます。
すべてのメモリを取得する
類似性検索パラメータが指定されていない場合、RetrieveMemories は、現在の会話との類似性に関係なく、指定されたスコープを持つすべてのメモリを返します。
results = client.memory_banks.memories.retrieve(
name=memory_bank.name,
scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `page` to retrieve up to 100 memories per page.
results.page
"""
Returns:
[
RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
name="projects/.../locations/.../reasoningEngines/.../memories/...",
...
fact="This is a fact."
}
),
RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
name="projects/.../locations/.../reasoningEngines/.../memories/...",
...
fact="This is another fact."
}
),
]
"""
次のように置き換えます。
SCOPE: 取得のスコープを表す辞書。例:{"user_id": "123"}リクエストと同じスコープのメモリのみが返されます。
メモリの一覧表示
ListMemories を使用して、スコープベースのフィルタリングなしでメモリバンクからメモリを取得します。スコープベースの取得には、代わりに RetrieveMemories を使用します。ListMemories は低レイテンシの取得にはおすすめしません。
pager = client.memory_banks.memories.list(name=memory_bank.name)
for page in pager:
print(page)
思い出をフィルタする
このセクションでは、フィルタを使用して取得するメモリを制限する方法について説明します。以下に基づいてフィルタできます。
スコープベースの取得に
filter_groups属性を使用するメタデータ。filterを使用するシステム フィールド。システム フィールドには、メモリーのtopics、create_time、update_time、factが含まれます。
メタデータとシステム フィールドのフィルタリングは、同じリクエストで使用できます。
メタデータでフィルタする
思い出の作成、更新、生成時に、保存された思い出に構造化メタデータを適用できます。
import datetime
from agentplatform import types
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
)
),
}
client.memory_banks.memories.create(
...,
config={"metadata": metadata}
)
client.memory_banks.memories.update(
...,
config={"metadata": metadata}
)
client.memory_banks.memories.generate(
...,
config={"metadata": metadata}
)
filter_groups 属性を使用してメモリーを取得する際に、このメタデータでフィルタできます。メタデータ フィルタは、論理和標準形（DNF）で定義されます。これは、AND の OR の論理式です。
たとえば、次のリクエストは、メタデータ（{"my_string_key": {"string_value": "my_value"}} AND {"my_double_key": {"double": 1.23}}）または {"my_string_key": {"string_value":
"other"}} を含む思い出を取得します。
辞書
results = client.memory_banks.memories.retrieve(
...,
config={
# Each element of `filter_groups` is combined using OR logic.
"filter_groups": [
{
# Each element of `filters` is combined using AND logic.
"filters": [
{
"key": "my_string_key",
"value": {"string_value": "my_value"}
},
{
"key": "my_double_key",
"value": {"double_value": 1.23}
}
]
},
{
"filters": [
{
"key": "my_string_key",
"value": {"string_value": "other"}
}
]
}
]
}
)
クラスベース
from agentplatform import types
results = client.memory_banks.memories.retrieve(
...,
config=types.RetrieveMemoriesConfig(
# Each element of `filter_groups` is combined using OR logic.
filter_groups=[
types.MemoryConjunctionFilter(
# Each element of `filters` is combined using AND logic.
filters=[
types.MemoryFilter(
key="my_string_key",
value=types.MemoryMetadataValue(string_value="my_value")
),
types.MemoryFilter(
key="my_double_key",
value=types.MemoryMetadataValue(double_value=1.23)
)
]
),
types.MemoryConjunctionFilter(
filters=[
types.MemoryFilter(
key="my_string_key",
value=types.MemoryMetadataValue(string_value="other")
)
]
)
]
)
)
システム フィールドでフィルタする
filter 属性を使用してシステム フィールドをフィルタできます。この属性では、EBNF 構文を使用した文字列値が想定されます。システム フィールドには、create_time、update_time、fact、topics があります。
EBNF 構文には、フィルタ文字列を構築する際に次の要件があります。
- フィルタを組み合わせるには、
ANDとORを使用します。 - 文字列には二重引用符
"を使用します。 - 日時フィールド（
create_timeなど）は、ISO 8601 日時を表す二重引用符付き文字列、または Unix エポックからのマイクロ秒を表す数値フィールドのいずれかを使用します。
たとえば、次のフィルタを使用して、fact に「allergies」という部分文字列が含まれており、update_time が 2026 年 1 月 1 日以降のメモを取得できます。
filter_string = 'fact=~".*allergies.*" AND update_time>="2026-01-01T00:00:00Z"'
client.memory_banks.memories.retrieve(
...,
config={"filter": filter_string}
)
client.memory_banks.memories.list(
...,
config={"filter": filter_string}
)
トピックでフィルタする
生成された思い出には、関連する思い出のトピックのラベルが自動的に付けられます。
マネージド トピックでフィルタするには、フィールド名として topics.managed_memory_topic を使用し、値として想定される ManagedTopicEnum を使用します（例: topics.managed_memory_topic: USER_PREFERENCES）。
カスタム トピックでフィルタリングするには、フィールド名として topics.custom_memory_topic_label を使用し、値として目的のトピックのラベル（topics.custom_memory_topic_label: custom-label など）を使用します。
filter_string = "topics.managed_memory_topic: USER_PREFERENCES " + \
"OR topics.custom_memory_topic_label: custom-label"
client.memory_banks.memories.retrieve(
...,
config={"filter": filter_string}
)
client.memory_banks.memories.list(
...,
config={"filter": filter_string}
)