AWS Bedrock AgentCore Memory: odczyt zwraca pusty lub nieaktualny kontekst

Ten runbook dotyczy błędów odczytu AgentCore Memory. Gdzie Memory mieści się w platformie, opisaliśmy w artykule Amazon Bedrock AgentCore: architektura i cennik. W sprawie bieżącego utrzymania agentów umów konsultację.

Objawy

Błąd przyjmuje jedną z dwóch postaci. Najpierw ustal, którą, bo naprawa się różni.

# 1. Pusty odczyt - zapytanie nie zwraca nic
retrieveMemoryRecords -> { "memoryRecords": [] }
# ...mimo że zdarzenia zapisano wcześniej w tej samej lub poprzedniej sesji.

# 2. Nieaktualny odczyt - zapytanie zwraca stary kontekst
# Agent odpowiada faktami z poprzedniej sesji i pomija to, co użytkownik
# powiedział przed chwilą, albo preferencje długoterminowe nigdy się nie pojawiają.

Widoczny wpływ:

• Agent “zapomina” fakt podany przez użytkownika sekundy temu (ścieżka krótkoterminowa)
• Preferencje lub streszczenia długoterminowe nigdy się nie pojawiają, nawet między sesjami (ścieżka długoterminowa)
• Odczyt działa w jednej sesji, ale zwraca pusto dla tego samego użytkownika w innej

Przyczyna

AgentCore Memory ma dwie odrębne warstwy, a większość błędów odczytu bierze się z ich pomylenia albo z zapisania rekordów pod niewłaściwymi kluczami.

1. Pamięć krótkoterminowa jest natychmiastowa, długoterminowa nie. Surowe zdarzenia, które zapisujesz, są dostępne od razu dla bieżącej sesji. Pamięć długoterminowa (fakty, preferencje, streszczenia sesji) powstaje w kroku asynchronicznej konsolidacji, który uruchamia się po zapisaniu zdarzeń. Odpytasz rekord długoterminowy natychmiast i dostaniesz pusty wynik - nie dlatego, że zapis się nie powiódł, lecz dlatego, że konsolidacja jeszcze się nie zakończyła.
2. Odczyt jest przypisany do actor, session i namespace. Rekordy zapisywane są pod actorId i sessionId oraz organizowane w namespace’y według strategii. Jeśli odczytujesz z innym actorId (na przykład identyfikatorem per żądanie zamiast stabilnym id użytkownika), innym sessionId niż oczekujesz albo z namespace, który nie odpowiada strategii tworzącej rekordy, dostajesz pusty lub nieaktualny wynik, mimo że dane istnieją.

Częste przyczyny:

• Odczyt pamięci długoterminowej tuż po zapisie - zapytanie, zanim zadziała asynchroniczna konsolidacja
• Niestabilny actor id - nowy actorId per żądanie zamiast stabilnego id per użytkownik, przez co historia nigdy się nie zgadza
• Mylenie sesji z pamięcią długoterminową - oczekiwanie pamięci międzysesyjnej z odczytu krótkoterminowego (zakresowanego do sesji)
• Niedopasowanie namespace / strategii - odczyt z namespace, do którego skonfigurowana strategia nigdy nie pisała

Naprawa

Krok 1: Ustal, który to przypadek

Najpierw sprawdź, czy zdarzenia w ogóle zapisano, a potem czy istnieją już rekordy długoterminowe.

# Czy surowe zdarzenia są obecne dla tego actor + session? (ścieżka krótkoterminowa)
aws bedrock-agentcore list-events \
  --memory-id your-memory-id \
  --actor-id user-123 \
  --session-id session-abc \
  --region us-west-2

# Czy istnieją skonsolidowane rekordy długoterminowe dla tego actor? (ścieżka długoterminowa)
aws bedrock-agentcore retrieve-memory-records \
  --memory-id your-memory-id \
  --namespace "/strategies/your-strategy/actor/user-123" \
  --search-criteria '{"searchQuery":"user preferences"}' \
  --region us-west-2

Jeśli zdarzenia istnieją, ale rekordy długoterminowe są puste, to opóźnienie konsolidacji (krok 2). Jeśli same zdarzenia są nieobecne pod oczekiwanym id, to problem z zakresowaniem (krok 3).

Krok 2: Uwzględnij asynchroniczne opóźnienie konsolidacji długoterminowej

Pamięć długoterminowa powstaje asynchronicznie po zapisaniu zdarzeń. Nie odczytuj rekordu długoterminowego w tej samej turze, w której zapisałeś źródłowe zdarzenie, oczekując, że już tam będzie.

• Dla bieżącej tury odczytuj z pamięci krótkoterminowej (ostatnie zdarzenia / kontekst sesji), która jest natychmiastowa
• Pozwól konsolidacji długoterminowej zadziałać między turami; rekordy długoterminowe odczytuj w kolejnych turach lub sesjach
• Nie blokuj odpowiedzi dla użytkownika, czekając na rekord długoterminowy, który jeszcze się nie skonsolidował

# Antywzorzec: zapisz zdarzenie, a potem od razu oczekuj rekordu długoterminowego
client.create_event(memoryId=mid, actorId=uid, sessionId=sid, payload=turn)
prefs = client.retrieve_memory_records(...)   # w tej turze pewnie wciąż pusto

# Lepiej: użyj ostatnich zdarzeń w bieżącej turze; długoterminowe czytaj w następnej
recent = client.list_events(memoryId=mid, actorId=uid, sessionId=sid)
# preferencje długoterminowe czytamy w późniejszej turze, po konsolidacji

Krok 3: Ujednolić zakres actor, session i namespace

Zapisuj i odczytuj z tym samym stabilnym actorId, zamierzonym sessionId oraz namespace, który odpowiada strategii tworzącej rekordy.

• Używaj stabilnego actorId per użytkownik (np. wewnętrznego id użytkownika), nigdy wartości per żądanie ani zmiennej losowej
• Odczyt krótkoterminowy przypnij do właściwego sessionId; odczyt międzysesyjny do długoterminowego namespace tego actora
• Potwierdź, że ścieżka namespace odpowiada skonfigurowanej strategii pamięci - zapytanie do namespace, do którego żadna strategia nie pisze, zawsze zwraca pustą dopowiedź

Krok 4: Sprawdź, czy strategia pamięci jest skonfigurowana pod to, co odczytujesz

Jeśli oczekujesz streszczeń lub wyekstrahowanych preferencji, a zapisywałeś tylko surowe zdarzenia, sprawdź, czy na zasobie pamięci faktycznie włączono strategię długoterminową (np. streszczanie lub ekstrakcję preferencji). Bez pasującej strategii nie ma czego konsolidować i odczyt długoterminowy z założenia pozostaje pusty.

aws bedrock-agentcore get-memory \
  --memory-id your-memory-id \
  --region us-west-2
# Potwierdź, że oczekiwana strategia długoterminowa jest obecna i ENABLED.

Weryfikacja

Potwierdź, że zamierzona ścieżka pamięci zwraca to, czego oczekujesz.

# Krótkoterminowa: ostatnie zdarzenia sesji wracają natychmiast
aws bedrock-agentcore list-events \
  --memory-id your-memory-id --actor-id user-123 --session-id session-abc \
  --region us-west-2

# Długoterminowa: po konsolidacji odczyt dla tego samego actora zwraca rekordy
aws bedrock-agentcore retrieve-memory-records \
  --memory-id your-memory-id \
  --namespace "/strategies/your-strategy/actor/user-123" \
  --search-criteria '{"searchQuery":"user preferences"}' \
  --region us-west-2

Oczekiwane: zdarzenia krótkoterminowe wracają w bieżącej turze; rekordy długoterminowe wracają niepuste w kolejnej turze dla tego samego stabilnego actorId. Jeśli długoterminowa wciąż jest pusta po konsolidacji, strategia lub namespace są niedopasowane (kroki 3-4).

Powiązane

• Amazon Bedrock AgentCore: architektura, komponenty i cennik - gdzie Memory mieści się wśród komponentów
• AWS Loom: nadzór nad agentami AI na AWS - szersza platforma, w której działa Memory
• Dokumentacja AWS Bedrock AgentCore Memory