Чотири правила кодування пам’яті агента, яка залишається чесною
Зберігання більшої кількості нотаток не виправить проблему пам’яті кодувального агента. Чотири правила забезпечують її чесність: видимість застарілості, автоматичне приховування при помилках, чітке обрізання та дотримання обмежень.
Джерела: 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: робити старість примітки видимою під час її використання
Ви не можете уникнути проблеми між 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 , вона є детермінованою та достатньо дешевою для використання безпосередньо в коді.
Виявилося, що три дрібні деталі мають більше значення, ніж основна ідея.
Переписана історія — це інша відповідь. Коли до певного коміту вже неможливо дістатися через rebase чи prune, відображення нуля комітів було б хибним результатом, який міг би ввести в оману. Замість цього інструмент показує „Історія переписана, перевірте“. „Невідомо“ та „свіже“ — це різні відповіді, і вони мають залишатися окремими.
Примітки позначаються лише у тому репозиторії, який вони вказують. Кількість комітів, виміряна за допомогою нерелевантної історії, є шумом, який прикидається сигналом. Примітка, обмежена проектом 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,
}
Функція редагування, яка спотворює звичайний прозовий текст, вимикається, і тоді вона вже нічого не захищає. У всьому модулі є лише один виняток: ваша власна ідентичність git зберігається, оскільки вона вже записана у кожному коміті, який ви опублікували, а її приховування лише ускладнить читання приміток.
Правило 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 || ...)
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');
Дві речі не підлягають скороченню: запитана вами основна нота та кожен обмежувальний фактор. Логіка ґрунтується на витратах, а не на смаку. Обмежувальний фактор може стосуватися того, що клієнт не схвалить нову базу даних, сервіс не може підключитися до публічного Інтернету чи команда платформи вже відхилила використання 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, але жоден з них не показує того, що насправді потрібно знати.
Частина, яку варто запозичити
Будь-хто, хто вбудовує функції пам’яті у робочий процес агента — свій чи той, який він розробляє для інших — може застосовувати ці чотири правила поза межами цього проекту:
- Вказуйте термін дії інформації безпосередньо там, де вона використовується, а не на панелі керування, яку ніхто не відкриває.
- Дозвольте механізму очищення зазнати невдачі, якщо він нічого не запише, та не додавайте флаг для обходу цього правила.
- Роздрукуйте те, що ви пропустили, адже мовчазне скорочення може здатися повним охопленням.
- Вирішіть те, що неможливо пропустити, ще до того, як бюджет стане обмеженим, адже рішення, прийняті під тиском, є гіршими.
Жоден з цих кроків не є складним для впровадження. Усі чотири легко ігнорувати, і коли вони працюють, це залишається непомітним, саме тому варто їх записати.