גרסאות של זיכרונות

‫Memory Bank שומר באופן אוטומטי את היסטוריית הגרסאות של הזיכרונות באמצעות משאבים לעריכת זיכרונות. בכל פעם שנוצר או משתנה זיכרון, נשמרת גרסה חדשה שלא ניתן לשנות, וכך אפשר לראות איך המידע מתפתח ומה נשלף בכל שלב.

במאמר הזה מוסבר על מחזור החיים של הזיכרונות והשינויים שלהם, ומתוארות פעולות כמו הצגה, קבלת וביטול של שינויים.

מידע נוסף על יצירת זיכרונות זמין במאמר בנושא יצירת זיכרונות.

מחזור החיים של זיכרון והגרסאות שלו

אפשר ליצור, לעדכן או למחוק זיכרונות ישירות (באמצעות CreateMemory, UpdateMemory או DeleteMemory, בהתאמה) או באופן דינמי (באמצעות GenerateMemories). משאבי תיקון הזיכרון מספקים היסטוריית גרסאות מלאה של משאב זיכרון בכל פעולות השינוי. בכל פעם שיוצרים או משנים את הזיכרון, נשמרת אוטומטית גרסה חדשה ובלתי ניתנת לשינוי. כך תוכלו לראות איך הזיכרון התפתח, ובמקרה של תהליך יצירת זיכרון, איזה מידע ספציפי חולץ ורוכז בכל שלב.

לכל משאב זיכרון יש משאב אחד או יותר של גרסת זיכרון משנית שמשויכת אליו:

• המשאבים ב-Memory תמיד משקפים את המצב הנוכחי והמאוחד של המידע. זיכרון אחד יכול לשקף נתונים נגזרים מכמה בקשות וממקורות נתונים שונים.

  Memory(
      create_time=datetime.datetime(...),
      fact='This is my current memory content after consolidation',
      name='projects/.../locations/.../reasoningEngines/../memories/...',
      scope={
        'my_scope_key': 'my_scope_value'
      },
      topics=[
        MemoryTopicId(
          managed_memory_topic=<ManagedTopicEnum.USER_PERSONAL_INFO: 'USER_PERSONAL_INFO'>
        ),
      ],
      update_time=datetime.datetime(...)
  )
  

• משאבי MemoryRevisions מייצגים את המצבים ההיסטוריים של הזיכרון של ההורה. כל גרסה היא תמונת מצב של הזיכרון באירוע Mutation. אם בוצע שינוי בזיכרון באמצעות GenerateMemories, הגרסה כוללת גם את המידע שחולץ ממקור הנתונים (extracted_memories) לפני שהוא אוחד עם התוכן הקיים בזיכרון.

  MemoryRevision(
      create_time=datetime.datetime(...),
      expire_time=datetime.datetime(...),
      extracted_memories=[
        IntermediateExtractedMemory(
          fact='This information was extracted from my data source'
        ),
      ],
      fact='This is my current memory content after consolidation',
      name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...'
  )
  

  הגרסאות הקודמות של הזיכרונות מופעלות כברירת מחדל. כדי להשבית את העריכות של הזיכרונות, אפשר לקרוא את המאמר בנושא השבתת העריכות של הזיכרונות.

יצירת זיכרון

אפשר ליצור זיכרונות ישירות באמצעות CreateMemory או באופן דינמי באמצעות GenerateMemories. בתהליך יצירת זיכרון, זיכרון נוצר אם אין זיכרונות קיימים שכוללים מידע דומה באותו היקף:

# Direct creation using CreateMemory
client.memory_banks.memories.create(name=memory_bank_name, ...)

# Dynamic creation using GenerateMemory
client.memory_banks.memories.generate(name=memory_bank_name, ...)

כשנוצר זיכרון, נוצר משאב Memory יחיד ומשאב צאצא MemoryRevision:

client.memory_banks.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my original fact.",
  ...
)
"""

list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

עדכון הזיכרון

אפשר לעדכן את הזיכרונות ישירות באמצעות UpdateMemory או באופן דינמי באמצעות GenerateMemories. בזיכרונות שנוצרו, הזיכרונות מתעדכנים באופן דינמי כשהתהליך האיחוד קובע שהמידע החדש הוא כפילויות, משלים או סותר את כל הזיכרונות הקיימים באותו היקף.

# Direct update using UpdateMemory
client.memory_banks.memories.update(name=memory_name, ...)

# Dynamic update using GenerateMemories
client.memory_banks.memories.generate(name=memory_bank_name, ...)

כשמעדכנים זיכרון, המשאב הקיים Memory מתעדכן ונוצר משאב צאצא חדש MemoryRevision.

client.memory_banks.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my updated fact.",
  ...
)
"""

list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

מחיקת הזיכרון

אפשר להשתמש בזיכרונות ישירות באמצעות DeleteMemory או באופן דינמי באמצעות GenerateMemories. כשמשתמשים ביצירת זיכרון, הזיכרונות נמחקים באופן דינמי כשתהליך האיחוד קובע שהמידע החדש מבטל את המידע הקיים באותו היקף.

# Direct deletion using UpdateMemory
client.memory_banks.memories.delete(name=memory_name, ...)

# Dynamic delete using GenerateMemories
client.memory_banks.memories.generate(name=memory_bank_name, ...)

כשמוחקים זיכרון, משאב Memory הקיים נמחק ונוצר MemoryRevision צאצא חדש. ה-fact בגרסת הזיכרון האחרונה ריק כי הוא משקף מוטציה של מחיקה.

client.memory_banks.memories.get(name=memory_name)
"""
404 Not Found.
"""

list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/789",
    fact="",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

אפשר לגשת לגרסאות הקודמות של הזיכרון של הילד או הילדה רק למשך 48 שעות אחרי מחיקת הזיכרון של ההורה. במהלך חלון השחזור הזה, תוכלו להמשיך לבדוק את הגרסאות של הזיכרון ולשחזר אותו על ידי חזרה לגרסה קודמת.

פעולות שקשורות לגרסת זיכרון

בקטע הזה מוסבר איך אפשר לבדוק גרסאות של זיכרונות ולחזור לגרסה קודמת של זיכרון.

הצגת הגרסאות

משתמשים בפקודה ListMemoryRevisions כדי להחזיר את כל הגרסאות של הזיכרון ששייכות לזיכרון.

list(client.memory_banks.memories.revisions.list(name=MEMORY_NAME))

מחליפים את מה שכתוב בשדות הבאים:

• ‫MEMORY_NAME: שם המשאב של הזיכרון בפורמט: projects/.../locations/.../reasoningEngines/.../memories/...

כשיוצרים זיכרונות, אפשר לספק תוויות של גרסאות שיוחלו על הגרסאות המשויכות. תוויות הן צמדי מפתח/ערך שרירותיים. לדוגמה, אפשר להוסיף תווית לגרסאות עם מזהה של מקור הנתונים ששימש ליצירת הזיכרון, ואז לסנן את הגרסאות לפי התווית הזו:

response = client.memory_banks.memories.generate(
    ...,
    config={
        "revision_labels": {
            "data_source": "321"
        }
    }
)

list(client.memory_banks.memories.revisions.list(
    name=MEMORY_NAME,
    config={
      "filter": "labels.data_source=\"321\""
    }
))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    labels={
      "data_source": "123"
    }
    ...
  )
]
"""

קבלת שינוי

משתמשים בפקודה GetMemoryRevision כדי לאחזר גרסת זיכרון ספציפית.

client.memory_banks.memories.revisions.get(name=MEMORY_REVISION_NAME)

מחליפים את מה שכתוב בשדות הבאים:

• ‫MEMORY_REVISION_NAME: שם המשאב של עדכון הזיכרון לאחזור בפורמט: projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...

איך מחזירים זיכרון למצב קודם

אפשר להשתמש ב-RollbackMemory כדי להחזיר זיכרון לגרסה קודמת.

client.memory_banks.memories.rollback(
    name="MEMORY_NAME",
    target_revision_id="REVISION_ID"
)

מחליפים את מה שכתוב בשדות הבאים:

• ‫MEMORY_NAME: שם המשאב של הזיכרון לעדכון בפורמט: projects/.../locations/.../reasoningEngines/.../memories/...

• ‫REVISION_ID: המזהה של הגרסה שאליה רוצים לחזור. זהו הפלח האחרון של שם המשאב של גרסת הזיכרון, כמו 789 ב-projects/MyProject/locations/us-central1/reasoningEngines/123/memories/456/revisions/789.

אם רוצים לבטל שינוי בזיכרון שבוצע על ידי GenerateMemories, צריך לחזור לגרסה הקודמת של הזיכרון לפני השינוי. תגובת תהליך יצירת הזיכרון כוללת הפניה לגרסה הקודמת (previous_revision) לכל זיכרון שעודכן או נמחק:

operation = client.memory_banks.memories.generate(
  ...
)

# Rollback the first generated memory to the previous revision.
client.memory_banks.memories.rollback(
    name=operation.response.generated_memories[0].memory.name,
    target_revision_id=operation.response.generated_memories[0].previous_revision
)

השבתת שינויים בזיכרון

הגרסאות הקודמות של הזיכרונות מופעלות כברירת מחדל. אפשר להשבית את גרסאות הזיכרון לכל הבקשות למופע של Memory Bank או לכל בקשה בנפרד. אם גרסאות הזיכרון מושבתות, לא נוצרת גרסת זיכרון כשהזיכרון משתנה.

אתם יכולים להשבית את השינויים בזיכרון לכל הבקשות למופע של Memory Bank כשאתם מגדירים את המופע:

memory_bank = client.memory_banks.create(
  managed_semantic_memory_config={
    "disable_memory_revisions": True
  }
)

אפשר להשבית את השינויים בזיכרון ברמת הבקשה כששולחים את הבקשה:

client.memory_banks.memories.generate(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

client.memory_banks.memories.create(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

client.memory_banks.memories.update(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

תפוגה של גרסה

הגרסאות הקודמות של הזיכרונות לא נשמרות לתמיד. צריך להגדיר את התפוגה של הגרסאות או להשתמש בתפוגה שמוגדרת כברירת מחדל. ברירת המחדל של אורך החיים (TTL) היא 365 ימים. אפשר להגדיר את התפוגה לכל הבקשות למופע של Memory Bank או לכל בקשה בנפרד. אחרי שפג התוקף של גרסת זיכרון, היא לא זמינה לבדיקה או להחזרה למצב קודם.

כשמגדירים את מופע Memory Bank, אפשר לקבוע את ה-TTL לכל הבקשות למופע:

client.memory_banks.create(
  managed_semantic_memory_config={
    "ttl_config": {
      # Persist memory revisions for 30 days after they're created.
      "revision_ttl": f"{30 * 60 * 60 * 24}s"
    }
  }
)

כדי להגדיר TTL לכל גרסת זיכרון ברמת הבקשה, צריך לכלול את revision_expire_time או revision_ttl בבקשה:

config = {
    # Persist memory revisions for 30 days after they're created.
    "revision_ttl": f"{30 * 60 * 60 * 24}s"
}

client.memory_banks.memories.create(
  ...,
  config=config
)

client.memory_banks.memories.update(
  ...,
  config=config
)

client.memory_banks.memories.generate(
  ...,
  config=config
)

import datetime

config = {
    "revision_expire_time": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(weeks=3)
}

client.memory_banks.memories.create(
  ...,
  config=config
)

client.memory_banks.memories.update(
  ...,
  config=config
)

client.memory_banks.memories.generate(
  ...,
  config=config
)