claude-mem, pamiec miedzy sesjami agenta

claude-mem, pamięć agenta, która przeżywa zamknięcie terminala

Asystent kodujący zaczyna każdą sesję od zera. Nie pamięta, dlaczego wczoraj odrzuciliście jedno podejście, jak nazywa się wewnętrzna konwencja w tym repozytorium ani czego szukaliście przez godzinę. claude-mem zapisuje przebieg pracy, kompresuje go modelem i podaje istotne fragmenty przy kolejnym uruchomieniu.

Jaki problem to rozwiązuje

Kontekst rozmowy z agentem znika po zamknięciu sesji. W praktyce oznacza to trzy rzeczy, które kosztują czas codziennie.

Powtarzasz wprowadzenie. Każdego ranka tłumaczysz od nowa, że projekt używa konkretnego menedżera pakietów, że testy uruchamia się jednym poleceniem, a warstwę płatności obsługuje osobna usługa.

Powtarzasz błędy. Agent proponuje podejście, które wczoraj odrzuciliście po pół godzinie prób, bo nie ma śladu po tamtej decyzji.

Gubisz ustalenia. Wnioski z długiej sesji diagnostycznej zostają w oknie terminala i znikają razem z nim, mimo że były najcenniejszym wynikiem pracy.

Plik z instrukcjami projektu rozwiązuje część pierwszego problemu, bo opisuje stan trwały. Nie rozwiązuje dwóch pozostałych, bo nikt nie dopisuje do niego wniosków po każdej sesji.

Jak to działa

Mechanizm ma trzy etapy i warto je rozumieć, bo od nich zależy, czy narzędzie pomoże, czy będzie przeszkadzać.

Zapis przebiegu obejmuje to, co agent robił w trakcie sesji: odczytane pliki, uruchomione polecenia, wprowadzone zmiany, podjęte decyzje. Surowy zapis jest zbyt duży, żeby go później podać w całości.

Kompresja modelem zamienia ten zapis na zwięzłe notatki. To najważniejszy krok, bo decyduje, co przetrwa. Wynikiem nie jest transkrypcja, tylko zestaw stwierdzeń wartych zapamiętania.

Wstrzyknięcie kontekstu podaje przy starcie kolejnej sesji te notatki, które wyglądają na powiązane z bieżącą pracą. Agent zaczyna więc od stanu wiedzy, a nie od pustej kartki.

Kompresja ma jeszcze jedną konsekwencję, o której łatwo zapomnieć: to model decyduje, co jest istotne. Zapis sesji przechodzi przez czyjąś ocenę, a nie przez filtr, który sam ustawiłeś. W praktyce oznacza to, że część rzeczy oczywistych dla Ciebie może nie przetrwać, a część drobiazgów przetrwa. Dlatego notatki warto raz na jakiś czas przeczytać, zamiast zakładać, że wiernie oddają przebieg pracy.

Ostatni etap decyduje o odbiorze narzędzia. Zbyt szerokie dopasowanie zapycha kontekst nieistotnymi notatkami i podnosi koszt każdego wywołania. Zbyt wąskie sprawia, że narzędzie wydaje się nie działać.

Instalacja

Wtyczka instaluje się z poziomu sesji, przez wbudowany katalog rozszerzeń.

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Po restarcie kontekst z poprzednich sesji pojawia się automatycznie. Niczego nie uruchamiasz ręcznie, ale warto wiedzieć, że wtyczka utrzymuje w tle lokalną usługę roboczą na Bun. To ona przetwarza zapis sesji i wystawia lokalne API razem z podglądem notatek w przeglądarce, a przy dziwnym zachowaniu narzędzia od jej stanu zaczyna się diagnoza. Same notatki lądują w bazie SQLite w katalogu ~/.claude-mem.

Projekt rozwija się na trzech gałęziach: stabilnej, rozwojowej i społecznościowej. Do rejestru pakietów trafia wyłącznie stabilna, więc dwie pozostałe uruchamia się ze źródeł. Przy narzędziu tego typu warto zostać przy stabilnej, bo pamięć agenta psuje się w sposób trudny do zauważenia.

Aktualizacje wtyczki warto robić świadomie, a nie automatycznie. Zmiana w warstwie kompresji potrafi zmienić to, co trafia do notatek, a efekt zobaczysz dopiero za kilka sesji.

/plugin list
/plugin update claude-mem

Przed aktualizacją warto zrobić kopię katalogu z notatkami. Odtworzenie ich z historii sesji nie jest możliwe, więc jedyne, co masz, to plik na dysku.

Narzędzie nie ogranicza się do jednego asystenta. Obsługuje kilka środowisk agentowych, więc notatki zebrane w jednym z nich są dostępne w kolejnym, o ile pracujesz nad tym samym projektem.

Jak to zmienia codzienną pracę

Największa różnica pojawia się przy pracy rozłożonej na dni. Sesja po weekendzie zaczyna się od przypomnienia, na czym stanęło, zamiast od rekonstrukcji stanu z historii gita.

Druga różnica dotyczy decyzji negatywnych. Informacja o tym, czego nie robić i dlaczego, jest zwykle cenniejsza niż opis rozwiązania, bo rozwiązanie widać w kodzie, a odrzucone warianty nie zostawiają śladu. Zapisana notatka o tym, że dana biblioteka nie zadziałała z Waszą wersją środowiska, oszczędza pół dnia przy następnym podejściu.

Trzecia dotyczy przekazywania pracy. Osoba wchodząca w projekt dostaje razem z repozytorium zestaw notatek z poprzednich sesji, co bywa czytelniejsze niż komunikaty commitów.

Warto ustawić oczekiwania. To nie jest zamiennik dokumentacji ani pliku z konwencjami projektu. To warstwa uzupełniająca, która zbiera to, co i tak dzieje się w trakcie pracy, a czego nikt nie spisuje ręcznie.

Prywatność i bezpieczeństwo

Narzędzie zapisuje przebieg sesji, więc trzeba wiedzieć, co dokładnie ląduje w notatkach i gdzie te notatki leżą.

Domyślnie dane trzymane są lokalnie, a najnowsze wersje dokładają synchronizację z usługą chmurową producenta. To jest właśnie moment, w którym warto się zatrzymać: przy repozytorium klienta albo przy danych objętych umową poufności synchronizacja poza własną maszynę wymaga świadomej decyzji, nie domyślnego ustawienia.

Druga rzecz to sekrety. Sesja, w której agent odczytał plik ze zmiennymi środowiskowymi, może zostawić ten fragment w notatkach. Zanim wdrożysz narzędzie w zespole, sprawdź, co trafia do zapisu, i wyklucz katalogi z konfiguracją. Narzędzie daje tu jawną furtkę: treść otoczoną znacznikiem <private> model widzi w bieżącej sesji, ale nie zapisuje jej jako obserwacji. To najprostszy sposób na wklejenie zrzutu logów z produkcji bez zostawiania go w pamięci na stałe.

sqlite3 ~/.claude-mem/claude-mem.db .dump 2>/dev/null \
  | grep -nE "(sk|pk)_(live|test)_[A-Za-z0-9]{10,}|PRIVATE KEY|AKIA[0-9A-Z]{16}" | head

To polecenie warto uruchomić raz po tygodniu używania, zanim ktokolwiek włączy synchronizację. Jeśli cokolwiek się znajdzie, sam klucz trzeba zrotować, a nie tylko wyczyścić notatki: wartość, która raz trafiła do zapisu, mogła już zostać przesłana dalej.

Osobno warto sprawdzić, co dzieje się przy usuwaniu danych. Jeśli notatki są synchronizowane, skasowanie ich lokalnie nie musi oznaczać usunięcia kopii po drugiej stronie, a przy żądaniu usunięcia danych osobowych to różnica istotna prawnie, nie techniczna.

Trzecia to porządek. Notatki narastają, a stare bywają mylące, bo opisują stan kodu sprzed refaktoru. Przegląd raz na kwartał i usunięcie tych nieaktualnych jest tanią czynnością, która utrzymuje jakość podpowiedzi.

Co warto zapamiętywać, a co jest szumem

Jakość tego narzędzia sprowadza się do jakości notatek, a te zależą od tego, co w ogóle dzieje się w sesji. Kilka nawyków wyraźnie poprawia wynik.

Nazywaj decyzje wprost. To samo ustalenie wynikające milcząco z serii poleceń nie przetrwa kompresji, bo nie ma czego streścić.

Slabo:  zmien kolejke na tabele w bazie

Lepiej: zostajemy przy kolejce w bazie zamiast brokera, bo przy stu
        zadaniach dziennie broker to dodatkowa usluga do utrzymania
        bez zysku. Wracamy do tematu, gdy przekroczymy tysiac dziennie.

Drugi zapis zawiera powód i warunek zmiany decyzji, więc po miesiącu notatka nadal coś znaczy. Pierwszy zostawia po sobie fakt bez kontekstu, a to jest dokładnie ten rodzaj wpisu, który przy kolejnej sesji wprowadza w błąd.

Zamykaj sesje podsumowaniem. Dwa zdania o tym, co zostało zrobione i co jest następne, dają modelowi materiał do zapisania. Sesja urwana w połowie zostawia notatki opisujące stan przejściowy, który przy kolejnym uruchomieniu wprowadza w błąd.

Rozdzielaj projekty. Praca nad dwoma repozytoriami w jednej sesji miesza konteksty, a wstrzykiwane później notatki dotyczą po części nie tego projektu, co trzeba.

Nie licz na zapamiętanie tego, co i tak jest w kodzie. Struktura katalogów, nazwy funkcji i zależności są widoczne dla agenta bez pamięci. Wartościowe jest to, czego w kodzie nie widać: powody, odrzucone warianty, ograniczenia zewnętrzne.

Warto też wiedzieć, że część tej roli pełnią umiejętności agenta, opisane w agent-skills. Umiejętność zawiera instrukcję postępowania przy określonym zadaniu, pamięć zawiera historię konkretnego projektu. Razem pokrywają dwie różne luki i nie zastępują się nawzajem.

Wdrożenie w zespole

Instalacja u jednej osoby to kwestia minuty, wdrożenie u dziesięciu wymaga trzech ustaleń, których lepiej nie odkładać.

Pierwsze dotyczy zakresu danych. Ustalcie, czy notatki zostają lokalnie, czy są synchronizowane, i czy dotyczy to wszystkich repozytoriów, czy tylko wewnętrznych. Przy projektach klienckich to zwykle kończy się wyłączeniem synchronizacji dla wybranych katalogów.

Drugie dotyczy współdzielenia. Notatki jednej osoby bywają cenne dla reszty zespołu, ale zawierają też jej sposób pracy i ślepe zaułki. Rozsądny punkt wyjścia to pamięć indywidualna, a wnioski warte współdzielenia przenoszone świadomie do pliku w repozytorium.

Trzecie dotyczy przeglądu. Wyznaczcie moment, w którym ktoś przegląda notatki i usuwa nieaktualne, na przykład przy zamykaniu większego etapu. Bez tego po kwartale połowa zapisów opisuje kod sprzed refaktoru.

Przy większych konfiguracjach agenta warto trzymać całość ustawień w repozytorium, podobnie jak robi się to z szablonami z claude-code-templates. Nowa osoba dostaje wtedy komplet wraz z projektem, zamiast konfigurować środowisko od zera.

claude-mem kontra alternatywy

Te podejścia się nie wykluczają. Najlepiej sprawdza się układ, w którym stan trwały opisuje plik w repozytorium, a warstwa automatyczna zbiera to, co powstaje w trakcie pracy.

Kiedy pamięć agenta faktycznie się opłaca

Nie każdy sposób pracy zyskuje na tej warstwie, a instalowanie jej na wszelki wypadek kończy się dokładaniem kosztu bez widocznego zwrotu.

Zyskuje praca ciągła nad jednym projektem przez tygodnie, zwłaszcza gdy sesje są krótkie i rozproszone w czasie. Tu koszt rekonstrukcji stanu przy każdym starcie jest realny i powtarzalny, więc jego usunięcie widać od razu.

Zyskuje też praca diagnostyczna. Szukanie przyczyny błędu, który pojawia się raz na kilka dni, rozciąga się na wiele sesji, a wnioski z każdej są warte więcej niż kod, który przy okazji powstał.

Nie zyskuje praca zadaniowa: pojedyncza poprawka, wygenerowanie komponentu, jednorazowa migracja pliku. Tam sesja zaczyna się i kończy w tym samym kontekście, więc pamięć nie ma czego przenieść.

Nie zyskuje też praca na wielu niepowiązanych repozytoriach naprzemiennie. Notatki z jednego projektu podane w drugim to szum, który zajmuje kontekst i kosztuje przy każdym starcie.

Prosty test przed wdrożeniem: policz, ile minut dziennie schodzi na wprowadzanie asystenta w kontekst projektu. Jeśli to kilka minut przy dwóch sesjach, narzędzie się zwróci. Jeśli sekundy, bo pracujesz w jednym długim oknie, korzyść będzie trudna do zauważenia.

Typowe błędy

Pierwszy to traktowanie narzędzia jak dokumentacji. Notatki są zapisem tego, co się wydarzyło, a nie opisem tego, jak system ma działać. Konwencje i architekturę nadal trzymaj w repozytorium.

Drugi to włączenie synchronizacji bez sprawdzenia, co synchronizujesz. Przy projekcie klienta to decyzja do uzgodnienia, nie ustawienie do zaakceptowania w biegu.

Trzeci to brak przeglądu notatek. Po kilku miesiącach część z nich opisuje kod, którego już nie ma, a agent traktuje je jako obowiązujące.

Czwarty to instalowanie gałęzi rozwojowej na maszynie roboczej. Błąd w warstwie pamięci objawia się jako dziwne zachowanie asystenta, a nie jako komunikat błędu, więc diagnoza zajmuje nieproporcjonalnie dużo czasu.

FAQ

Czy claude-mem jest darmowy?

Kod jest otwarty i dostępny w repozytorium, a wtyczkę instalujesz bez opłaty. Koszt pojawia się pośrednio: kompresja zapisu sesji to wywołania modelu, więc rachunek u dostawcy rośnie proporcjonalnie do liczby sesji. Osobno rozliczana bywa opcjonalna synchronizacja z chmurą producenta.

Czy dane wychodzą poza mój komputer?

Domyślny tryb pracy jest lokalny, natomiast nowsze wersje oferują synchronizację z usługą chmurową. Przed wdrożeniem w projekcie objętym poufnością sprawdź, która opcja jest aktywna, i podejmij decyzję świadomie.

Czy to zastępuje plik z instrukcjami projektu?

Nie. Plik opisuje stan trwały: konwencje, polecenia, architekturę. claude-mem zbiera przebieg pracy i wnioski z sesji. Te dwie warstwy uzupełniają się, a próba zastąpienia jednej drugą kończy się gorszym wynikiem niż użycie obu.

Czy działa z innymi asystentami niż Claude?

Tak, narzędzie obsługuje kilka środowisk agentowych, więc notatki zebrane w jednym są widoczne w drugim przy pracy nad tym samym projektem. To odróżnia je od pamięci wbudowanej w konkretne narzędzie, na przykład w Cursorze.

Czy spowalnia sesję?

Zapis i kompresja odbywają się w tle, więc praca nie zatrzymuje się na tym kroku. Zauważalny może być natomiast rozmiar wstrzykiwanego kontekstu: zbyt wiele notatek na starcie wydłuża pierwszą odpowiedź i podnosi koszt, dlatego warto ograniczyć zakres do bieżącego projektu.

Kod źródłowy i instrukcja instalacji stoją w repozytorium na GitHubie, a pakiet w rejestrze npm.