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

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

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

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

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

אפשר ליצור, לעדכן או למחוק זיכרונות ישירות (באמצעות 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.agent_engines.memories.create(name=memory_bank_name, ...)

# Dynamic creation using GenerateMemory
client.agent_engines.memories.generate_memories(name=memory_bank_name, ...)

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

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

list(client.agent_engines.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.agent_engines.memories.update(name=memory_name, ...)

# Dynamic update using GenerateMemories
client.agent_engines.memories.generate_memories(name=memory_bank_name, ...)

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

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

list(client.agent_engines.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.agent_engines.memories.delete(name=memory_name, ...)

# Dynamic delete using GenerateMemories
client.agent_engines.memories.generate_memories(name=memory_bank_name, ...)

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

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

list(client.agent_engines.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.agent_engines.memories.revisions.list(name=MEMORY_NAME))

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

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

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

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

list(client.agent_engines.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.agent_engines.memories.revisions.get(name=MEMORY_REVISION_NAME)

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

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

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

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

client.agent_engines.memories.rollback(
    name=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.agent_engines.memories.generate(
  ...
)

# Rollback the first generated memory to the previous revision.
client.agent_engines.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.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": {
        "disable_memory_revisions": True
      }
    }
  }
)

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

יצירה

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

יצירה

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

עדכון

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

תפוגה של גרסה

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

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

client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_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 בבקשה:

TTL

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

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

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

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

תפוגה

import datetime

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

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

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

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