Cztery zasady kodowania pamięci agenta, które zapewniają jej uczciwość
Przechowywanie większej liczby notatek nie naprawi pamięci agenta do kodowania. Cztery zasady zapewniają jej wierność: widoczna przestarzałość, automatyczna cenzura w przypadku błędów, głośne skracanie oraz zachowane ograniczenia.
Źródła: Your Coding Agent Has a Memory Problem. Storing More Won’t Fix It.
Otwórz drugie okno czatu, a twój agent programistyczny nic o tym nie będzie wiedział. Nie mniej niż wcześniej, ale po prostu nic. Decyzja podjęta czterdzieści minut temu dotycząca odrzucenia podejścia opartego na kolejce zniknęła. Zniknęła również ograniczenie, że zespół bezpieczeństwa klienta nigdy nie zatwierdzi nowej bazy danych, a także trzy ślepe zaułki, które już sprawdziłeś, aby nikt nie musiał ich ponownie przemierzać. Kontekst nie przetrwa zmiany okna.
Dlatego rutyna jest taka: wklej stare rozmowy, wpisz to, co pamiętasz, i ponownie wyjaśnij to, czego nie możesz odtworzyć. To zajmuje łatwo od dziesięciu do piętnastu minut na każdą zmianę, a prośby premium tracą sens z powodu wniosków, które już raz zostały sformułowane.
Na żadnej z tych platform nie ma rozwiązania, które mogłoby zamknąć tę lukę, ponieważ każda funkcja pamięci jest dostosowana dokładnie do tego, czego próbujemy uniknąć. Jednym z rozwiązań zaproponowanych przez jednego z programistów było stworzenie własnej warstwy pamięci: około 2600 linii kodu w Node, bez zależności od środowiska uruchomieniowego, obsługującej GitHub Copilot, Claude Code i Codex. Niemal natychmiast pojawił się problem, o którym nikt nie ostrzega.
Zachowywanie większej ilości danych pogarsza sytuację
Prawdziwym problemem systemu pamięci nie jest zapominanie. To błędne zapamiętywanie, przy tym z przekonaniem.
Załóżmy notatkę z napisem „auth uses JWT”, napisaną wtedy, gdy to było prawdą, a później odzyskaną cztery miesiące po przeniesieniu bazy kodu na sesje po stronie serwera. Ta informacja nie znika w niepewności – jest odzyskiwana, uznawana za wiarygodną i wykorzystywana dalej, w rezultacie powstaje agent, który błędnie działający w sposób wyraźny i pewny potrafi nawet podać źródło. To znacznie gorsze niż sytuacja, gdy agent mówi „Nie wiem, jak tutaj działa autoryzacja”, ponieważ wtedy agent pyta użytkownika, natomiast ten pewny siebie agent wprowadza błędy do systemu.
Zatem przechowywanie danych nie stanowi elementu inteligentnego projektowania, skoro sprowadza się do foldera i schematu. Trudnym zadaniem jest zapewnienie, by przechowywana wiedza pozostawała prawdziwa, mimo zmian w kodzie, który ją obsługuje. Rozwiązanie opiera się na czterech gwarancjach, z których każda wymaga niewielkiej ilości kodu oraz dużej samokontroli.
Kto pisze notatki
Autor to model językowy, i niemal każda decyzja projektowa wynika z tego faktu. Jego dane wejściowe nie można uważać za wiarygodne, choć nie z powodu złośliwości kogokolwiek – pochodzą one z rozmowy, która mogła zawierać klucz API, ciąg połączenia lub adres e-mail kogoś innego. Format jego wyników również nie jest czymś oczywistym, a każda runda korekty zużywa rzeczywisty żądanie.
Ostatni punkt pojawia się w nieoczekiwanym miejscu: walidator zgłasza wszystkie problemy jednocześnie, zamiast zatrzymać się przy pierwszym.
export function validateNode(input) {
const e = [];
// ...every check pushes onto e instead of throwing...
if (e.length) throw new ValidationError(e);
return n;
}
Szybkie ponoszenie porażki jest odruchem, ale w tym przypadku jest to błędne. Model, który poprawia swój własny wynik, może naprawić wszystko za jedną próbę, zamiast szukać błędów pojedynczo, co wiąże się z dodatkowymi kosztami za każdą próbę. To niewielka zmiana, ale odróżnia jedną próbę od pięciu.
Notatki dzielą się na cztery typy, co wkrótce się okazuje ważne: system, decision, convention oraz constraint.
Reguła 1: uwidaczniaj przestarzałość, gdy notatka jest używana
Nie można uniknąć problemu związанego z JWT w porównaniu z sesjami. Notatka może być dokładna w poniedziałek, a błędna już w marcu, niezależnie od projektu. To, co jest w zasięgu ręki, to wyświetlanie wieku notatki w momencie, gdy ktoś zamierza na nią polegać – to jedyny moment, w którym ktoś może podjąć działanie.
Każda notatka rejestruje stan repozytorium HEAD, w którym została utworzona:
id: auth-service
type: system
title: Auth uses server sessions
scope: repo
confidence: observed
captured_sha: a1b2c3d # repo HEAD at capture
repos: [orders-api]
edges:
- rel: depends-on
dst: postgres-primary
Przy pobieraniu liczba ta przekształca się w liczbę komitów:
captured 47 commits ago — verify before trusting
Nie ma żadnego modelu, żadnej zadania zaplanowanego ani tła skanującego, które oceniałoby świeżość. Wystarczy pojedyncze polecenie git rev-list --count ..HEAD, które jest deterministyczne i na tyle tanie, że można je wykonać bezpośrednio.
Okazało się, że trzy małe szczegóły mają większe znaczenie niż sama główna idea.
Zmieniona historia to inna odpowiedź. Gdy do komitów nie da się już uzyskać dostępu z powodu rebase’a lub prune’a, wyświetlenie zera komitów byłoby kłamstwem w celu dania poczucia bezpieczeństwa. Narzędzie zamiast tego podaje „historia została zmieniona, sprawdź”. „Nieznane” i „świeże” to różne odpowiedzi i muszą pozostać oddzielone.
Uwagi są adnotowane tylko w repozytorium, do którego się odnoszą. Liczba komitów mierzona w odniesieniu do niepowiązanej historii to szum przebrany za sygnał. Uwaga skierowana na orders-api i pobrana podczas pracy w billing-api pozostaje nietknięta i nie jest oznaczana jako przepisana.
if (Array.isArray(node.repos) && node.repos.length &&
!node.repos.includes(here)) return null;
Istnieje pewien próg. Poniżej dziesięciu komitów problem starzenia się w ogóle nie jest wspominany, ponieważ ciągłe wyświetlanie ostrzeżeń jest jedynie dekoracją, a nie prawdziwym ostrzeżeniem. Ten próg można skonfigurować. Wyższy próg na poziomie 100 komitów uruchamia polecenie doctor, które wyświetla notatki wymagające dokładnej analizy, dzięki czemu możesz samodzielnie je sprawdzać, zamiast otrzymywać informacje o każdej notatce osobno.
Reguła 2: nieudana redakcja – zamknięte
Plik z danymi sklepu znajduje się w postaci tekstowej na biurku roboczym firmy, a model zapisał jego zawartość na podstawie rozmów, które mogły zawierać cokolwiek. Dlatego żaden dane nie trafia na dysk bez uprzedniego skanowania. Czternaście rodzin wzorców wykrywa takie elementy jak klucze AWS, tokeny GitHub i Slack, klucze prywatne, JWT, tokeny nośnikowe, łańcuchy połączeń do bazy danych, pliki cookie sesji, IP-y z prywatnego zakresu oraz nazwy hostów wewnętrznych, a także adresy e-mail; każdy tak wykryty element jest zastępowany wartością <redacted:kind> przed zapisaniem.
„Fail-closed” wykonuje określone zadania, co widać w pierwszych liniach funkcji:
export function redact(text, opts = {}) {
if (typeof text !== 'string') {
throw new TypeError('redact() requires a string; refusing to write unscanned content');
}
Podaj mu coś, czego nie może skanować, a nie pominie skanowania i nie będzie kontynuował. Zatrzyma proces zapisu. Proces redakcji musi zakończyć się sytuacją, w której „nic nie zostanie zapisane”, a nigdy taką, w której „to jedno przeszło niezauważone”. Nie ma też flagi omijania, ponieważ flaga ta służyłaby ostatecznie do użycia w piątkowy wieczór o szóstej.
Dwie opcje wewnątrz niej są warte obrony.
Łańcuchy połączeń pozostają nienaruszone. URI takie jak postgres://user:hunter2@db.internal:5432/orders zawierają dane uwierzytelniające bezpośrednio w sobie, więc zastępowany jest cały URI, a nie tylko hasło. Nawet częściowo zredagowane URI nadal przekazują czytelnikowi adres hosta, port, nazwę bazy danych oraz nazwę użytkownika.
Tajemnice w formularzu zadań muszą się sprawdzić. Naiwna zasada password: <coś> pochłonęłaby również zdanie takie jak „polityka rotacji haseł to 90 dni”, dlatego zasada wymaga użycia cudzysłowów lub długiego ciągu bez cudzysłowów:
{
kind: 'assigned-secret',
re: /\b(?:api[_-]?key|secret|password|token|client[_-]?secret|
access[_-]?key)\b\s*[:=]\s*(?:"[^"\n]{6,}"|'[^'\n]{6,}'|[^\s"'`,;)]{12,})/gi,
}
Edycja, która psuje zwykły tekst prozatorski, przestaje działać, a wtedy już nic nie chroni. Cały moduł ma dokładnie jedną wyjątkową sytuację: twoja własna tożsamość gitowa pozostaje nienaruszona, ponieważ jest już zapisana w każdym commitie, który wysłałeś, a jej ukrycie tylko utrudniłoby czytanie notatek.
Reguła 3: skracanie nigdy nie odbywa się bez echa
Zapytanie drugiego poziomu głębokości na dobrze połączonym węźle może zwrócić pięćdziesiąt notatek, przekraczając w ten sposób sam okno kontekstowe, które ma chronić projekt. Dlatego istnieje limit liczby bajtów – 8 KB jako standard – oraz mechanizm przycinania po jego przekroczeniu. Nic z tego nie jest zaskakujące. Najważniejsze jest to, co dzieje się po przycięciu:
3 nodes omitted for budget: legacy-batch-job, vendor-sftp-quirk,
old-retry-policy
Każdy pominięty identyfikator jest wyświetlany, bez żadnych wyjątków. To zasada ma największą siłę przekonywania, ponieważ ciche skracanie jest błędem, który wygląda jak sukces. Gdy dostępnych jest osiem z jedenastu notatek i nie ma żadnych oznak braku trzech, agent zakłada, że widzi wszystko, i odpowiada z taką samą pewnością, jaką to sugeruje. Brakujące trzy to prawdopodobnie te, których potrzebował: zostały pominięte jako drugorzędne wobec zapytania, a zaskakujące ograniczenia często znajdują się na obrzeżach.
Proces eliminacji odbywa się najpierw od najgłębszych elementów, a następnie od tych najmniej powiązanych:
.sort((a, b) => b.depth - a.depth || a.degree - b.degree || ...)
Depth means distance from what was actually asked, and a low degree suggests a node nobody needed as a hub. Breaking final ties by id gives identical bytes for the same query every time, so the reindex determinism test checks something real.
Rule 4: constraints are never dropped
Not at any cap, in either tier, with no exceptions.
const removable = nodes.filter((n) => n.depth > 0 && n.type !== 'constraint');
Dwie rzeczy unikają usuwania: prośbiona nuta podstawowa oraz każda ograniczenie. Logika ta opiera się na koszcie, a nie na gustach. Ograniczenie może dotyczyć na przykład faktu, że klient nie zatwierdzi nowej bazy danych, usługa nie może uzyskać dostępu do publicznej sieci internetowej lub zespół platformy już odrzucił rozwiązanie Kafka. To właśnie takie ograniczenia powstrzymują agenta przed wysyłaniem dziesiątek zapytań w kierunku podejścia skazanego na niepowodzenie od samego początku. Usunięcie jednego zapytania w celu zaoszczędzenia czterystu bajtów oznacza zamianę taniego kosztu na droższy: bajty są tanie, natomiast nieudana implementacja nie jest.
To stwarza sytuację, o której kod musi jasno informować. Jeśli suma nuty podstawowej i ograniczeń już przekracza budżet, budżet musi ustąpić:
Note: 9,412 bytes returned, over the 8,192 budget, because constraints
are never dropped.
Zgłoszono to, ale nie naprawiono, ponieważ naprawa oznaczałaby usunięcie tego, co warto zachować.
Sklep jest w formacie Markdown, a indeks jest tymczasowy
Jedna decyzja strukturalna spełnia wszystkie cztery zasady: notatki to zwykłe pliki Markdown z metadanymi w formacie YAML, a index.db to cache, który można usunąć w dowolnym momencie.
~/.agents/memory/
notes/<type>/<id>.md the source of truth
notes/archive/ superseded and decayed notes; never deleted
index.db disposable SQLite cache
ROUTING.md generated map of everything known
Jedno polecenie index regeneruje bazę danych na podstawie notatek, bajt po bajcie. Baza danych istnieje dlatego, że przemieszczanie się po grafie w SQL jest szybkie, podczas gdy przeglądanie katalogu plików jest powolne. Silnik to rekurencyjne CTE z ograniczeniem głębokości oraz UNION zamiast UNION ALL, dzięki czemu pętla contradicts nie może się rekurencyjnie rozwijać, dopóki SQLite się nie zakończy. Nad SQLite nie istnieje oddzielna warstwa grafowa; to CTE pełni tę funkcję.
Nic cennego nie jest przechowywane wyłącznie w indeksie. Uszkodzony SQLite oznacza utratę cache’u. Usunąwszy narzędzie, pozostaje folder z czytelnym plikiem markdown, który jest przydatny, gdy nic nie jest zainstalowane. Wiedza powinna przetrwać dłużej niż jakiekolwiek indeksy, a proprietarna baza binarna zawodzi już od pierwszego dnia.
To właśnie umożliwia jego instalację w środowisku z ograniczonym dostępem, co było pierwotnym celem. Od wersji 22.5 Node dostarcza node:sqlite w swoim jądrze, więc indeks nie wymaga żadnego pakietu, żadnej usługi ani połączenia sieciowego. Na zarządzanym komputerze osobistym proponowanie skryptu Node oraz nowej bazy danych prowadzi do zupełnie innych rozmów i wyników.
Co zostało celowo pominęte
Nic nie jest rejestrowane automatycznie: musisz to uruchomić osobiście lub to zrobi specjalna funkcja przekazywania danych. To celowe ograniczenie. Proces w tle, który obserwuje twoją sesję i decyduje, co zachować, to funkcja, o którą wszyscy proszą, ale też ta, która najprawdopodobniej zaleje sklep niepotrzebnymi danymi. Wszystkie powyższe zasady uczciwości stają się mniej skuteczne w miarę gromadzenia się niskiej jakości notatek. Dziesięć dobrych notatek w tygodniu jest cenniejszych niż czterysta, które powstają, gdy model działa samodzielnie.
Dzielenie się zespołem, synchronizacja między kilkoma maszynami oraz serwer MCP również zostały odłożone. Serwer MCP czytałby ten sam zasób, więc stanowi jedynie uzupełnienie, a nie całkowitą przepisówkę.
Jedno twierdzenie wciąż nie zostało udowodnione. Istotnym testem jest „zimne odczytanie”: nowa rozmowa w repozytorium nienaruszanym od miesiąca, która poprawnie odpowiada wyłącznie na podstawie informacji z routingu. Wymaga to rzeczywistego czasu trwania i nie da się go symulować w zestawie testów. Siedemdziesiąt jeden testów przechodzi na Linux, macOS i Windows przy użyciu Node 22 i 24, ale żaden z nich nie pokazuje tego, co naprawdę chcemy wiedzieć.
Część wartą przejęcia
Każdy, kto buduje mechanizmy pamięci w procesach agentów, czy to własnych, czy tych, które dostarcza, może zastosować te cztery zasady również poza tym projektem:
- Umieść informację o aktualności przed tym, gdzie wiedza jest wykorzystywana, a nie na panelu kontrolnym, którego nikt nie otwiera.
- Pozwól narzędziu do czyszczenia na zawiedzieć poprzez brak zapisu jakichkolwiek danych i nie dodawaj flagi omijającej to ograniczenie.
- Wydrukuj to, co przeoczyłeś, ponieważ ciche skracanie treści sprawia wrażenie pełnego przykrycia.
- Zatwierdź sprawy, których nie można pominąć, zanim budżet się skończy, bo decyzje podejmowane pod presją są gorsze.
Żadna z tych zasad nie jest trudna do wdrożenia. Wszystkie cztery łatwo pominąć, a gdy działają, są niewidoczne, właśnie dlatego warto je zapisać.