Zep i Graphiti, pamięć agenta z osią czasu

Zep i Graphiti, pamięć agenta z osią czasu

Zep to warstwa pamięci dla agentów, zbudowana na grafie wiedzy, w którym każdy fakt ma przypisany okres ważności. Silnik grafowy nazywa się Graphiti, jest na licencji Apache 2.0 i można go używać osobno.

Pomysł, który odróżnia to rozwiązanie od zwykłego magazynu wektorów, jest jeden i wart zrozumienia niezależnie od tego, czy sięgniesz akurat po ten produkt. Fakty o ludziach się zmieniają, a zapis, który tego nie uwzględnia, każe agentowi wybierać między dwiema sprzecznymi prawdami bez żadnej wskazówki, która z nich jest bieżąca.

Problem, który to rozwiązuje

Weź prostą sytuację. W marcu użytkownik napisał, że pracuje w firmie A. We wrześniu napisał, że zmienił pracę i jest w firmie B.

W magazynie wektorowym leżą teraz dwa zdania. Oba są podobne do pytania „gdzie on pracuje", więc oba mogą trafić do kontekstu, a model dostaje sprzeczność bez informacji o kolejności. Odpowiedź zależy od tego, które zdanie wypadło wyżej w wynikach wyszukiwania, czyli od przypadku.

Można to obejść, dodając daty do metadanych i sortując po nich. Działa to do momentu, w którym faktów jest więcej niż kilka i zaczynają wchodzić ze sobą w relacje, bo sortowanie po dacie zapisu nie mówi nic o tym, czy nowszy fakt unieważnia starszy, czy je uzupełnia.

Rozwiązanie zastosowane tutaj polega na tym, że relacja w grafie nosi dwa znaczniki czasu: kiedy stała się prawdziwa i kiedy przestała nią być. Nowa informacja o pracy nie kasuje starej, tylko zamyka jej okres ważności. Pytanie o stan bieżący zwraca jedno, a pytanie o historię zwraca oba, w kolejności.

Jak to działa pod spodem

Wejściem jest epizod: wiadomość z rozmowy, zdarzenie z systemu albo obserwacja zapisana przez agenta.

Silnik rozkłada go na elementy grafu. Byty stają się węzłami, relacje między nimi krawędziami, a do każdej krawędzi dopisywany jest okres obowiązywania i ocena pewności. Przy okazji sprawdzane jest, czy nowa informacja koliduje z czymś, co już w grafie jest, i jeśli tak, starsza krawędź dostaje datę zamknięcia.

To rozkładanie kosztuje. Każdy epizod wymaga wywołań modelu, żeby wyciągnąć byty i relacje, więc zapis do pamięci nie jest darmowy ani natychmiastowy. Przy dużej liczbie zdarzeń warto to robić poza główną ścieżką odpowiedzi, bo inaczej użytkownik czeka na coś, co go nie dotyczy.

Odczyt jest za to szybki i to jest właściwy kompromis. Praca wykonuje się raz przy zapisie, a przy każdym pytaniu agent dostaje gotowy zestaw faktów zamiast surowych fragmentów rozmowy do przeanalizowania.

Wyszukiwanie łączy trzy drogi: podobieństwo semantyczne, dopasowanie tekstowe i przejście po krawędziach grafu. Ostatnia jest tym, czego magazyn wektorowy nie potrafi. Pytanie o zespół, w którym pracuje dana osoba, można rozwiązać przechodząc od osoby do firmy i dalej do zespołu, nawet jeśli żadne zdanie w rozmowie nie zawierało tych trzech rzeczy naraz.

Koniec edycji społecznościowej

To jest zmiana, o której trzeba wiedzieć, bo unieważnia sporą część poradników w sieci.

Do kwietnia 2025 roku istniał wariant przeznaczony do uruchomienia u siebie, w jednym pakiecie, z bazą w komplecie. Ten wariant został wycofany.

Uruchomienie własne oznacza dziś sięgnięcie po sam silnik grafowy i złożenie reszty samodzielnie: baza grafowa, warstwa wywołująca model do wyciągania bytów, kolejka na przetwarzanie epizodów w tle, obsługa błędów. Obsługiwane bazy to Neo4j, FalkorDB oraz Amazon Neptune. Sterownik do Kuzu wciąż jest w paczce, ale README oznacza go jako przestarzały i zapowiada usunięcie, bo sam projekt Kuzu jest archiwizowany przez twórców, a jego strona nie odpowiada.

Praktyczna konsekwencja jest jasna. Sam silnik jest na licencji Apache 2.0 i można go używać bez opłat, natomiast nie dostajesz gotowego produktu, tylko bibliotekę. Różnica między „uruchamiam kontener" a „składam system z czterech elementów" to zwykle kilka dni pracy plus utrzymanie.

Warto przy tym wiedzieć, że sam produkt nie zniknął z własnej infrastruktury zupełnie, tylko przeszedł za bramkę handlową. Dostawca wymienia dziś trzy warianty wdrożenia: usługa hostowana, usługa hostowana z kluczami szyfrującymi po Twojej stronie oraz BYOC, czyli instalacja wewnątrz Twojej sieci wirtualnej. Ten trzeci jest tym, czego szuka większość osób pytających o uruchomienie u siebie, i wymaga rozmowy o planie Enterprise.

Jeśli więc trafisz na tekst opisujący darmowe samodzielne uruchomienie tego produktu w całości, sprawdź jego datę. Sposób opisany przed kwietniem 2025 roku już nie istnieje.

Graphiti osobno

Warto rozważyć ten wariant, bo bywa lepszym rozwiązaniem niż cały produkt.

Silnik da się wpiąć do własnej aplikacji jako biblioteka Pythona. Dostajesz budowanie grafu z epizodów, unieważnianie czasowe i wyszukiwanie łączone, a kontrolę nad bazą i infrastrukturą zatrzymujesz u siebie.

To jest droga dla zespołów, które mają wymóg trzymania danych na własnym sprzęcie, i dla tych, które chcą zrozumieć, co się dzieje, zamiast wywoływać usługę. Cena to praca operacyjna: baza grafowa wymaga utrzymania, kopii zapasowych i przemyślenia, co się dzieje przy jej niedostępności.

Warto też wiedzieć, że biblioteka wywołuje model przy każdym zapisie, więc koszt tokenów istnieje niezależnie od tego, czy płacisz za usługę. Przy dużej liczbie epizodów ten rachunek bywa większy niż opłata za wariant hostowany, i to jest liczba, którą warto policzyć przed decyzją.

Dwie osie czasu i po co ta druga

Warto rozdzielić dwie rzeczy, bo mieszanie ich prowadzi do błędnych wniosków przy diagnozowaniu odpowiedzi.

Pierwsza oś to czas, w którym fakt obowiązywał w rzeczywistości: od kiedy ktoś pracuje w danej firmie, od kiedy obowiązuje dana cena. Druga to czas, w którym system się o tym dowiedział.

Te dwie osie rozjeżdżają się częściej, niż się zakłada. Użytkownik może we wrześniu wspomnieć, że zmienił pracę w marcu. Fakt obowiązuje od marca, a system wie o nim od września, i oba te momenty bywają potrzebne. Pytanie „co wiedzieliśmy w kwietniu" ma inną odpowiedź niż „co było prawdą w kwietniu", a przy analizie tego, dlaczego agent odpowiedział wtedy tak, a nie inaczej, liczy się ta pierwsza.

Praktyczne zastosowania są dwa. Pierwsze to odtwarzanie przebiegu przy zgłoszeniach: agent odpowiedział źle, bo w tamtym momencie nie miał jeszcze informacji, a nie dlatego, że coś jest zepsute. Drugie to zgodność z wymogami, gdzie trzeba wykazać, jaki był stan wiedzy systemu w danej chwili.

Warto natomiast pamiętać, że sam mechanizm nie zgadnie daty obowiązywania, jeśli nie ma jej w treści. Zdanie „zmieniłem pracę" bez daty daje fakt obowiązujący od chwili zapisu, i to jest zwykle dobre przybliżenie. Zdanie „zmieniłem pracę w marcu" pozwala ustawić właściwy początek, o ile model wyciągnie tę datę przy rozkładaniu epizodu.

Co to znaczy dla promptu

Warstwa pamięci jest przydatna dokładnie na tyle, na ile dobrze wpina się w prompt, i to jest część, którą łatwo zaniedbać.

Zwracany zestaw faktów trzeba czymś opisać, bo model wrzucony w listę zdań bez kontekstu potraktuje je jako równorzędne z pytaniem użytkownika. Sekcja z nagłówkiem mówiącym wprost, że to są znane fakty o rozmówcy, i osobna sekcja z bieżącym pytaniem, dają wyraźnie lepsze wyniki niż sklejenie wszystkiego w jeden blok.

Druga rzecz to liczba faktów. Kuszące jest wrzucenie wszystkiego, co pamięć zwróciła, natomiast dwadzieścia faktów rozprasza model bardziej, niż pomaga, zwłaszcza gdy część z nich nie dotyczy pytania. Ograniczenie do kilku najbardziej trafnych zwykle poprawia odpowiedzi i obniża koszt jednocześnie.

Trzecia dotyczy faktów historycznych. Jeśli pobierasz również te z zamkniętym okresem ważności, oznacz je wyraźnie jako nieaktualne. Model, który dostanie stary i nowy fakt bez tego rozróżnienia, jest w tej samej sytuacji co przy zwykłym magazynie wektorowym, czyli cała przewaga tego rozwiązania znika w ostatnim kroku.

Zep kontra alternatywy

Ostatni wiersz warto rozważyć uczciwie, zanim cokolwiek dołożysz. Przy asystencie prowadzącym rozmowy po kilkanaście wiadomości cała historia mieści się w kontekście modelu i żadna warstwa pamięci nie jest potrzebna. Problem zaczyna się przy rozmowach ciągnących się tygodniami i przy setkach użytkowników, których nie da się trzymać w kontekście naraz.

Różnica między pierwszym a drugim wierszem sprowadza się do tego, czy potrzebujesz relacji i czasu. Jeśli pamiętasz preferencje typu „lubi kawę bez cukru", prostsze rozwiązanie wystarczy. Jeśli musisz odpowiadać na pytania wymagające przejścia między bytami albo rozróżniać stan bieżący od historycznego, graf robi rzecz, której lista faktów nie zrobi.

Trzeci wiersz to inna klasa rozwiązania i mieszanie go z dwoma pierwszymi prowadzi do złych wniosków. Tam pamięcią zarządza sam model, wywołując narzędzia do zmiany własnych bloków, więc nie dokładasz warstwy do swojego agenta, tylko budujesz agenta w cudzym środowisku. Pythonowy serwer tego projektu autorzy opisali w lipcu 2026 roku jako przestarzały i utrzymywany awaryjnie, a rozwój przenieśli do pakietu z npm, więc poradniki sprzed tej daty opisują uruchomienie, którego już nie ma.

Publikowane porównania skuteczności na zbiorach testowych wypadają korzystnie dla podejścia grafowego, przy czym pochodzą od twórców i mierzą zadania dobrane do tej metody. Traktuj je jako przesłankę, nie rozstrzygnięcie, i sprawdź na własnych rozmowach.

Cennik i co policzyć

Istnieje próg darmowy oraz kilka progów płatnych, a poszczególne kwoty bywają podawane różnie w materiałach zewnętrznych, więc przed decyzją sprawdź aktualny cennik u dostawcy.

Ważniejsze od samej stawki jest zrozumienie, co generuje koszt. Zapis epizodu wymaga wywołań modelu do wyciągnięcia bytów i relacji, więc rachunek rośnie z liczbą zapisywanych zdarzeń, a nie z liczbą pytań. Aplikacja zapisująca każdą wiadomość z rozmowy kosztuje wielokrotnie więcej niż aplikacja zapisująca podsumowanie po zakończeniu wątku.

To jest dźwignia, którą warto wykorzystać. Zapisywanie wszystkiego jest kuszące i prawie zawsze niepotrzebne. Wybór, które zdarzenia trafiają do pamięci, robi dla rachunku więcej niż wybór dostawcy.

Drugą pozycją jest przechowywanie grafu, rosnące z czasem. Warto od początku wiedzieć, czy jest sposób na usuwanie danych użytkownika, bo przy wymogach dotyczących danych osobowych prośba o usunięcie musi objąć również pamięć agenta, a nie tylko bazę główną.

Wdrożenie w praktyce

Kilka rzeczy oszczędza kłopotów, jeśli warstwa pamięci ma zostać na dłużej.

Rozdziel zapisywanie od odpowiadania. Wyciąganie bytów z epizodu trwa i nie musi się zdarzyć, zanim użytkownik dostanie odpowiedź. Kolejka albo zadanie w tle rozwiązują to raz.

Ustal, co jest epizodem. Każda wiadomość osobno daje graf pełen szumu i wysoki rachunek. Podsumowanie wątku albo zdarzenie biznesowe, na przykład złożenie zamówienia, daje graf, w którym coś widać.

Nie wkładaj do pamięci wszystkiego, co użytkownik napisał. Dane wrażliwe zapisane w grafie zostają tam i wracają w kontekście przy kolejnych rozmowach, więc filtr przed zapisem jest tańszy niż czyszczenie później.

Sprawdzaj, co faktycznie trafia do promptu. Warstwa pamięci zwraca zestaw faktów, a jakość odpowiedzi zależy od tego, czy są to właściwe fakty. Bez wglądu w to, co zostało pobrane, diagnozowanie złych odpowiedzi jest zgadywaniem, więc warto od razu wpiąć narzędzie śledzące, na przykład Arize Phoenix.

Ostatnia rzecz to zachowanie przy pustej pamięci. Nowy użytkownik nie ma historii, a agent zbudowany przy założeniu, że coś w pamięci jest, zachowuje się przy pierwszej rozmowie dziwnie. Ten przypadek warto przetestować osobno.

Typowe błędy

Pierwszy to opieranie się na poradnikach sprzed kwietnia 2025 roku przy uruchomieniu własnym. Opisywany tam wariant w jednym pakiecie już nie istnieje.

Drugi to zapisywanie każdej wiadomości jako osobnego epizodu. Rachunek rośnie liniowo, a graf zapełnia się faktami bez znaczenia.

Trzeci to wykonywanie zapisu na ścieżce odpowiedzi. Użytkownik czeka wtedy na przetwarzanie, które go nie dotyczy.

Czwarty to traktowanie pamięci jak wyszukiwania w dokumentach. To są dwie różne rzeczy: pamięć trzyma fakty o rozmówcy, wyszukiwanie znajduje fragmenty w bazie wiedzy, i mieszanie ich daje kontekst, w którym model gubi jedno w drugim.

Piąty to brak sposobu na usunięcie danych użytkownika. Prośba o usunięcie musi objąć graf, a nie tylko bazę główną.

Szósty to ufanie publikowanym wynikom bez sprawdzenia na własnych rozmowach. Zbiory testowe mierzą zadania dobrane do metody, a Twoje rozmowy wyglądają inaczej.

FAQ

Czym Zep różni się od zwykłego magazynu wektorów?

Modelem danych. Magazyn wektorowy trzyma fragmenty tekstu i zwraca podobne do pytania, więc dwa sprzeczne fakty wracają razem bez wskazówki, który jest aktualny. Tutaj fakt jest krawędzią w grafie z okresem ważności, więc pytanie o stan bieżący zwraca jedną odpowiedź.

Czy da się uruchomić Zep u siebie?

Nie w postaci darmowego pakietu. Wariant społecznościowy został wycofany w kwietniu 2025 roku, więc bezpłatnie oznacza to dziś użycie samego silnika Graphiti razem z własną bazą grafową, na przykład Neo4j, FalkorDB albo Amazon Neptune. Osobno istnieje płatna droga: na planie Enterprise dostawca wymienia wariant BYOC, czyli usługę postawioną wewnątrz Twojej sieci wirtualnej, obok wersji hostowanej i wersji z własnymi kluczami szyfrującymi.

Czym jest Graphiti?

Silnikiem grafu wiedzy z osią czasu, który stoi pod tym produktem, dostępnym osobno na licencji Apache 2.0. Buduje graf z epizodów, zamyka okresy ważności faktów wypartych przez nowsze i obsługuje wyszukiwanie łączące podobieństwo semantyczne z przejściem po krawędziach.

Czym różni się od Mem0?

Bogactwem modelu danych. Mem0 trzyma fakty i wyszukuje je po podobieństwie, co wystarcza przy preferencjach użytkownika. Podejście grafowe dokłada relacje i czas, więc obsługuje pytania wymagające przejścia między bytami oraz rozróżnienie stanu bieżącego od historycznego, kosztem większej złożoności.

Ile to kosztuje?

Jest próg darmowy i progi płatne, a kwoty warto sprawdzić w aktualnym cenniku, bo źródła zewnętrzne podają różne. Ważniejsze jest to, że koszt rośnie z liczbą zapisywanych epizodów, nie pytań, więc wybór, co trafia do pamięci, wpływa na rachunek bardziej niż wybór dostawcy.

Dokumentacja stoi na stronie produktu, a kod silnika w repozytorium Graphiti.