Галоўная / Артыкулы

Чатыры правілы для кодавання памяці агента, якая заставаецца чыстай.

Зберагачыце большае колькасць зьвістак не вылечыць проблему памяці кодавальнага агента. Чатыры правілы дапамагаюць захаваць яе чыстасць: візуабельная старэчнасць, блокаванне пад час апত্যকা, яскравая адцягванне і сахаванне обмежэнняў.

Выдавец: REACTAPP.TOP9 хв чытання2130 слоў

Крыніцы: Your Coding Agent Has a Memory Problem. Storing More Won’t Fix It.

Адзін раз ачыніце другое вікно чату, і ваш агент для кодавання нічога не будзе ведаць. Не менш, чым раней, але нічога. Рашыненне, якое было падзеў чатырохдзесят хвілін тыму пра тое, чаму былы адхілены падходы на адной канве, знікло. Знікла таксама абмежэнне, што каманды безпекі кліента ніколі не схваліць новую базу дадзеных, а таксама тры мертвыя канцэры, якія вы вялікі час расследавалі, каб ніхто не мусеў іх зноў пераглядаць. Кантэкст не перазжывае пераходу між вікнамі.

Таму існуе стандартная процедура: запісаце стары чат, запісаце тое, што памятаеце, і зноў поясніце тое, што не можэце выявіць. Гэта легка займае дзесяць-пятнацаць хвілін на кожны пераход, а запіты прэміум-класу гораюць у спробах дасягнуць вынікі, якія вы ужо раз атрымалі.

Нічыя з асоблікаў платформ не запоўняе гэтую прасоў, адтолькі кожная функцыя памяці прызначаная самэ для таго, ад чаго вы намагаецеся адстаць. Адпаведзь аднаго з разрабоў была стварыць сабе самаму шар памяці: прыблізна 2,600 ліній коду на Node, без залежнасцяў пад час выканання, які працюе з GitHub Copilot, Claude Code і Codex. Практычна адразу ж гэта выйшла на ту сторону, пра якую ніхто не паветарае.

Зберагчы больш — становіцца горш

Праўая прычына неудачы сістэмы памяці — не тое, што вы забываеце. А тое, што памятаеце некалькі, і ўсё гэта з упэўненасцю.

Уявіце прымечку, у яком напісана фраза "аўтэнтыфіка выкарыстоўвае JWT", напісанага тады, калі гэта было правдай, і выкарыстоўванага чатыры месцы пасля таго, як база кода была перанесена на серверныя сэшны. Гэты прымечак не знікае ў неяснасці. Яго выкарыстоўваюць, вераюць у яго і будуюць на ям, і ў канцы канцоў утварываецца агент, які спецыфічна і абавязкова робіць неправільныя выводы, і ўсё ж можа наводзіць джэрэлу. Гэта значна горша, чым калі агент кажа "Я не ведаю, як тут працюе аўтэнтыфіка", таму што такі агент запытае вас, а той, які ўпэўнены, будзе працаваць.

Такім чынам, храненне не ёсць там, дзе знаходзіцца гэтыя хітрыя інжынерныя рашэнні, адколі гэта проста папка і схема. Складная частка — гарантаваць, што зберажаныя знанні застаюцца правдывымі, пакуль код, які іх падтрымвае, змінюецца. У дызайне было выбрана чатыры гарантыі, кожная з якіх выкарыстоўвае мало коду і трэбуе вялікай самаконтролі.

Хто піша прымечкі

Аваром являецца мадэль мовы, і практычна кожны выбор у дызайне вынікае з гэтага. Яго вхідныя даны нельзя вважаць надзеянымі, хоць не праз злыя намеры каго-небудзь: воні практычна завжды ўзяты з размовы, якая могла міць ключ API, стрынг з’яўлення з’ўязку або электронную адрэсу каго-небудзь. Фармат яго выходных даных таксама нельзя вважаць незменным, і кожны цыкл корэкцыі спрацоўвае як адзін рэальны запіт.

Паслядні момент проявляецца ў нечаканым аспекце: верыфікатор адзначае всі проблемы адразу, а не зупініцца на першай.

export function validateNode(input) {
  const e = [];
  // ...every check pushes onto e instead of throwing...
  if (e.length) throw new ValidationError(e);
  return n;
}

Швыракае падэнне — гэта рэфлекс, алі тут гэта некалькана. Мадэль, якая практычна свой выхад, можа вылечыць усё за адну спробу, замест таго каб шукаць бягі адна за адной, пры чым кожная з іх караецца додатковым запітам. Гэта невялікая змяна, але яна розлічвае адну практычну спробу ад пяці.

Запісі бяруць чатыры тыпы, і гэта скора будзе важна: system, decision, convention і constraint.

Правіла 1: паказваць старэнне запісі, калі яна вжываецца

Не можна запобiec проблеме між JWT і сэсіямі. Запіс можа быць правільной у панедзелак і неправільной ў март, незалежна ад дызайну. Тое, што ў нашай моцы, — гэта паказваць вік запісі тады, калі хтось збіраецца на яе паслацца, бо толькі тады хтось можа прыняць рашэнне.

Кожная запіс фіксуе рэпазітарый HEAD, пры якому яна была зафіксавана:

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

Пры выкарыстоўванні гэта ператвараецца на колькасць комітав:

captured 47 commits ago — verify before trusting

Няма жадных модэляў, няма запланаваных заданняў і няма фонавага сканера, які бы ацэніваў свежасць. Для гэтага достатньа адной команды git rev-list --count ..HEAD; гэта метод ёсць дэтэрміністычны і дастаткова дэшавы, ўсё можна выконваць безпосерэдна.

Выявілася, што тры маленькія дэталі маюць большое значэнне, чым сама галоўная ідэя.

Перапісаная історыя — гэта іншая адпаведзь. Калі да паказання паказоў не можна даць рэчы, чырвонаваць нуль паказоў было бы каламутненнем правды, якое магло б даць хыбныя надзеі. У такім случае адпаведзь мусіць быць „історыя перапісана, пераканайцеся“. „Не вядома“ і „свежа“ — гэта разныя адпаведы, і яны павінны застацца аддзельнымі.

Прымечанні пазначаюцца толькі ў тым рэпазітарыі, які яны адзначаюць. Колькасць комітаў, вылічаная на аднойчы з несувязанай історыяй, — гэта шум, які маскіруецца пад сігнал. Прымечанне, прызначанае для orders-api і атрыбутаванае пад час работы з billing-api, застаецца без змян і не пазначаецца як перапісанае.

if (Array.isArray(node.repos) && node.repos.length &&
!node.repos.includes(here)) return null;

Існуе певныя практыкі. Пры менш чым дзесяці коміттах праблема застарэласці зовсім не паводзіцца, таму што паветрак, які спрацоўвае сталяк, ўважаецца толькі дэкаратыўным элементам, а не справжнім паветракам. Шырокія межы можна налаштаваць. Другая, вышэйшая межа у розмярэ 100 коміттаў запускае команду doctor, якая паказвае прыметкі, якія заслуговуюць на рэштычную пераглядку, тады вы можэце самі шукаты, а не прыміць інформацыю пра кожную прыметку окрэма.

Правіла 2: невыпанне правіла закрывае задачу

Магазін выкладваецца у вогневом фармаце на корпаратывным рабочым столе, а мадэль запісвае ўсё, што ёй даецца з размов, якія моглі містыць будзь-што. Таму жадны даны не падае на дыск без прадзеіснавання. Чатырнацаць семей шаблонаў фіксуюць такі элементы, як ключы AWS, токены GitHub і Slack, прыватныя ключы, JWT-коды, токены-носіцы, стрынгі для з’яўлення ў базе дадзенаў, кукі сесіі, IP-адрэсы прыватнага дыяпазона і внутрашні імены хостаў, а таксама адрэсы электронной пошты; кожны такі элемент перад запісам заменяецца на <redacted:kind>.

„Fail-closed“ выпрацоўвае конкрэтныя задачы, што відна ў першых рэчэннях функцыі:

export function redact(text, opts = {}) {
  if (typeof text !== 'string') {
    throw new TypeError('redact() requires a string; refusing to write unscanned content');
  }

Калі даць сістэме ўсё, што яна не можа сканаваць, яна не прыпініт канцэлірацію сканавання і не будзе працаваць далей. Яна абараніць запіс. Працэс рэдакцыі павінен завершыцца так, каб «нічога не было запісана», а не так, каб «гэта засталося без увагі». Таксама няма флага для абходжэння, таму што флаг для абходжэння — гэта тое, чым вы востаткі скорыстаецеся у пятнічны вечар.

Два варыянты, якія ёсць унутро, варта захішчаць.

Строкі з’ўязку залішаюцца цэлымі. URI, такі як postgres://user:hunter2@db.internal:5432/orders, несе свае аутэнтыфікацыйныя даны безпосерэдна, таму заменяецца весь URI, а не толькі пароль унутро. Паўнарэдагаваны URI все рава дае чытальніку імя хоста, порт, назву базы дадзеных і імя карыстальніка.

Таёмніцы, якія знаходзяцца ў форме задачы, павінны падтвердзіць свою правамоцнасць. Няўжыткавая правіла для password: <чыго-небудзь> таксама могла б перакрыць рэчэнне на кшталт „Палітыка змены пароля — 90 дзён“, таму правіла вымагае вжывання апошнікаў або довгага фрагмента без апошнікаў:

{
  kind: 'assigned-secret',
  re: /\b(?:api[_-]?key|secret|password|token|client[_-]?secret|
access[_-]?key)\b\s*[:=]\s*(?:"[^"\n]{6,}"|'[^'\n]{6,}'|[^\s"'`,;)]{12,})/gi,
}

Рэдакцыя, якая спяшна перакладае звычную прозу, перастае функцыянаць, і тады яна нічаго не захоўвае. У всім модулі ёсць толькі адна аўтаматычная адміністрацыя: ваша сабэйская ідэнтыфікацыя застаецца, адколькі яна ужо ўказана ў кожным комітэ, які вы выклалі, а ўтаіванне яе толькі ускладніць чытанне запісаў.

Правіла 3: скрацэнне ніколі не выконваецца без паўтарэння

Запрос другага роўна ў добра з’яўленым узле можа вернуць пяцьдзесят запісаў і перапыліць самае вікна кантэксту, якое захоўваее дызайн. Таму існуе ліміт па байтах — 8 КБ за замовчаннем, і скрацэнне запісаў, калі гэты ліміт перакрыты. Нічога з гэтага не ўражае. Важлівая частка — гэта, што выканаецца пасля скрацэння:

3 nodes omitted for budget: legacy-batch-job, vendor-sftp-quirk,
old-retry-policy

Кожны ідэнтыфікатор, які не быў уключаны, выдруковываецца, без жадных асаблівэй. Гэтыя правіла маюцы наўсёх большую сілу, адтолькі ўскорочэнне без паведамлення ёсць парадоксам, які выглядае як успех. Калі ёсць вясьме з адзіннадцатых знакав, і няма жадных адзнак таго, што трохі з яных зніклі, агент прыпускае, што бачыць усё, і адпавядае з той жа впэўненасцю. Тры знакавы, якія зніклі, верагатываецца, якраз і былі неабходныя: іх проста не паважалі як важлівыя для запіту, а часта саме на самым краю стоіць неспадзяваныя абмежэнні.

Ускорочэнне ведзецца спачатку з самых значных элементаў, а потым з тых, якія менш су пов’язаны:

.sort((a, b) => b.depth - a.depth || a.degree - b.degree || ...)

Глыбіна — гэта адзінакоўнасць з тым, што на самай працо было запітана, а нізкая глыбіна указвае на тое, што жаданага вузла як цэнтру не было. Злам лепшых звязкаў па ідэнтыфікатору дае ідэнтычныя байты для таго ж запіту ў кожны раз, таму тэст на дэтэрмінізм перыіндэксавання пераканальваецца ў рэальныя даны.

Правіла 4: абмежэнні ніколі не скасоўваюцца

Ні пад якімі ўмовамі, ні ў якім рангу, без жадных аўтаматызацый.

const removable = nodes.filter((n) => n.depth > 0 && n.type !== 'constraint');

Два элемента не падаюць пад прыем пры скарыстоўванні: запрошаная вам корэнная нота і кожны constraint. Логіка тут стосуецца костаў, а не смаку. Канстанты паведамляюць пра тое, што кліент не падпісае новую базу дадзеных, што сервіс не можа выйсці у публічную інтэрнэт-сетка, або што каманда платформы вялікімі шансамі вярнула адмову для Kafka. Бны самэўсёлкі не дазволяюць агенту направляць дзесяткі запыткаў у напрамку падходу, які з самага пачатку прыгожданы да невыкарыстоўвання. Скарыстоўванне аднаго запытка, каб заэканоміць чатырыста байтаў, заменяе дэшавы кост на дорогі: байты ёсць дэшавымі, а нерэалізаваны праект — ні.

Гэта стварае сітуацыю, пра якую код павінен ясна паведамляць з самага пачатку. Калі корэнная нота плюс усі канстанты вялікімі шансамі перакроююць бюджэт, бюджэт вынужданы ўступіць у спарчу:

Note: 9,412 bytes returned, over the 8,192 budget, because constraints
are never dropped.

Осё гэта зафіксавана, але не выправлена, таму што выправленне абяцаўалася б усуненнем таго, што варта заставіць.

Магазін напісаны на Markdown, а індэкс ёсць тымчасовым

Одны структурны выбар падтрымлівае ўсе чатыры правілы: запісы ўважаюцца звычайнымі файламі Markdown з YAML-фронтматэром, а index.db — кэш, які можна выдаліць калі толькі пажадаеце.

~/.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

Адзін каманды index перагэнеруе базу дадзэных з нотатак, байт за байтом. База дадзэных існуе там, таму што працаванне з графамі ў SQL ўскоранае, тады як працаванне з каталогамі файлаў — медленнае. Апаратна частка — гэта рэкурзіўны CTE з лімітом глыбіны і UNION замест UNION ALL, таму цыкл contradicts не можа рэкурсаваць пакуль SQLite не завершыцца. Над SQLite не існуе окалічнага шару графа; CTE выкананае гэтую ролю.

Нічога ценнага не захоўваецца выключна ў індэксе. Калі SQLite зіпсавана, вы втрачаеце кэш. Як толькі адмахнуцца ад інструмента, застаецца толькі папка з чытаемым markdown, якая ўжытковая, калі нічога не інсталавана. Знанні павінны перазіць якія-б усі індэксы, а прыналежны бінарны хранільнік вяршыць сваю ролю вучора.

Гэта таксама тое, што дазволяе яму запускацца ў захішчанай асяроддзі, якая была первачальной метай. З версіі 22.5 Node включыў node:sqlite у свой ядро, таму для працы індэкса не трэба ні пакетаў, ні служб, ні сеткі. На кераваным настольным камп’ютары пры пропанаванні скрыпты на Node і стварэнні новай базы дадзеных выкалываюць абсалютна разныя розмовы і рэзультаты.

Што было навмесна не адключана

Нічога не фіксуецца аўтаматычна: вы самі гэта запускаеце, або гэта робіць спецыяльная функцыя. Гэта ўмышленая мерыя. Функцыя фонавага працэсу, які сочыць за вашай сесіяй і выбірае, што залішыць, — гэта і функцыя, якую прасяць усі, але якая, што больш за ўсё, можа запалаваць магазін некальканасобнымі, неякіснымі данымі. Усе вышэйзгаданыя правіла чыстасцы становяцца слабейшымі, калі накапліваюцца некальканасобныя, нізкакалітэтныя зазначэнні. Дзесяць хорашых зазначэнняў за тыдзень цэнююцца вышэ, чым чатырыста, якія застаюцца, калі мадэль працюе сама.

Адмініструванне колькама членамі команды, сінхронізацыя межа калькама апаратамі і сервер MCP таксама адкладзены. Сервер MCP чытаў бы той самы база дадзенаў, таму ён ўжо ўскладненне, а не перапісва.

Адна з тэзаў яшчэ не падтверджана. Актуальны тэст — цэ холадны чытанне: новы чат у рэпазітарыі, які не змінювалі месцы месяц, які правільна адпавядае толькі на падставе рутынгу. Для гэтага патрэбны рэальны час, і гэта немагчыма сімулявацыя ў наборы тэстаў. Сямдзесят адзін тэста праходзяць на Linux, macOS і Windows пад Node 22 і 24, але ніхто з іх не паказвае таго, што насправды важна ведаць.

Тое, што варта запозіціяваць

Кожны, хто вбудоввае функцыі памяці ў рабочы працэс агента, будзь то свой агент чы той, які вы выкладзаеце, можа застосаваць гэтыя чатыры правілы і паza межамі гэтага праекта:

  1. Указваць староść інформацыі там, дзе яна вікорыстоўваецца, а не на панелі керування, яку ніхто не ачынае.
  2. Дазволіць функцыі чысткі не працаваць, не пісаючы нічога, і не дадаваць флага для айхіду ад гэтага правіла.
  3. Адраптавайце тое, што вы прынялі, калі ўжо не можаце гэта змяніць, таму што мовчанліва адміністрацыя выглядае як повна падтрымка.
  4. Рашыце тыя пытанні, якія ніколі нельга прыняць, перш чым бюджэт стане обмежаным, таму што рашэнні, прынятыя пад тым прытыскам, ўсё гіршыя.

Ні адна з гэтых практык не ўскладнена для выкарыстоўвання. Усе чатыры лёгкае праігнораваць, і калі ўсё працуе, гэта застаецца непазначальным, самэўсёлкі гэта і ўсё, чаму ўжо варта іх запісаць.