Главная / Статьи

Четыре правила кодирования памяти агента, сохраняющей честность

Хранение большего количества заметок не решит проблему памяти кодинг-агента. Четыре правила обеспечивают её надежность: видимость устаревания, автоматическая цензура при сбоях, заметная обрезка и соблюдение ограничений.

Издатель: 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: делать устаревание видимым при использовании примечания

Проблему 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; она детерминированна и достаточно дешева, чтобы использоваться непосредственно в коде.

Оказалось, что три небольших детали имеют большее значение, чем сама основная идея.

Переписанная история — это другой ответ. Когда к коммиту больше невозможно получить доступ из-за операций 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> перед записью.

Механизм «отказ при ошибке» выполняет определенные действия, что видно из первых строк функции:

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

Every omitted id gets printed, with no exceptions. This rule carries the most conviction, because silent truncation is the failure that looks like success. Given eight of eleven notes and no sign that three are missing, an agent assumes it sees everything and replies as confidently as that implies. The missing three are probably the ones it needed: they were dropped as peripheral to the query, and a surprising constraint often sits at the edge.

Pruning goes deepest-first, then least-connected:

.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, но ни один из них не показывает того, что действительно важно знать.

Что стоит заимствовать

Любой, кто внедряет механизмы хранения данных в рабочий процесс агента — будь то собственный проект или проект, выпускаемый другими, — может применять эти четыре правила и в других проектах:

  1. Указывайте старость данных там, где они используются, а не на панели управления, которую никто не открывает.
  2. Позволяйте механизму очистки данных дать ошибку, не записывая ничего, и не добавляйте флаг для обхода этой ошибки.
  3. Выпечатайте то, что вы отложили, ведь молчаливое опускание деталей воспринимается как полное охват информации.
  4. Решите те вопросы, которые невозможно отложить, до того, как бюджет станет ограниченным, поскольку решения, принятые под давлением, бывают худшими.

Ни один из этих пунктов не сложен в реализации. Все четыре легко игнорировать, и когда они работают, это остается незаметным, именно поэтому они стоит записать.