שליפת זיכרונות

במאמר הזה מוסבר איך להשתמש בפעולות האלה של אחזור נתונים באמצעות Agent Platform SDK.

אם אתם משתמשים בערכה לפיתוח סוכנים (ADK), הסוכן יכול לתזמן את השיחות האלה באופן אוטומטי. מדריך למתחילים ב-ADK

לפני שמתחילים

כדי לבצע את השלבים בדף הזה, צריך קודם לבצע את השלבים במאמר הגדרה של Memory Bank.

אחזור פעולות

אלה האפשרויות שלכם לאחזור זיכרונות שנוצרו:

• קבלת זיכרון: קבלת התוכן המלא של זיכרון יחיד באמצעות 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"}. אם לא מוחזרים זיכרונות, ל-Memory Bank אין זיכרונות עבור ההיקף שצוין.

ההיקף של הזיכרון מוגדר כשהוא נוצר אוטומטית או ידנית, והוא קבוע.

אתם יכולים להשתמש ב-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 כדי להציג זיכרונות מ-Memory Bank בלי סינון לפי היקף. לשליפה לפי היקף, משתמשים במקום זאת ב-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), שהיא ביטוי לוגי של ORs של ANDs.

לדוגמה, הבקשה הבאה תחזיר זיכרונות שכוללים את המטא-נתונים ({"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, או בשדה מספרי שמייצג מיקרו-שניות מאז ראשית זמן יוניקס.

לדוגמה, אפשר להשתמש במסנן הבא כדי לאחזר זיכרונות שבהם fact כולל את מחרוזת המשנה 'אלרגיות' ו-update_time היה אחרי 1 בינואר 2026.

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}
)