Мы прочитали 13 тысяч файлов логов своих агентов. Вот что они делают с памятью

Мы делаем kaeru — память для ИИ‑агентов вроде Claude Code и Codex. Несколько месяцев мы строили ее по ощущениям, а потом пошли читать логи своих агентов и проверять, как они на самом деле пользуются памятью. Многое оказалось не так, как мы думали, и почти все выводы — не про kaeru, а про агентов вообще. Если вы пишете свой MCP‑сервер, хук или просто длинные инструкции для агента, часть этого пригодится и вам.

Зачем агенту память и как устроена kaeru

Сначала коротко о том, что это за память, иначе цифры ниже будет не к чему приложить.

Проблема знакома всем, кто работает с агентами дольше недели. Каждая сессия начинается с чистого листа: агент переспрашивает то, что вы вчера объясняли, предлагает переделать то, что вы решили не трогать, а когда контекст переполняется и разговор сжимается в пересказ, половина обсужденного пропадает. Файл с правилами вроде CLAUDE.md помогает первое время, но его пишут руками, он только растет и хранит «что», но не «почему».

kaeru — это сервер, который работает у вас на машине. Агент подключается к нему по MCP — стандартному протоколу, через который Claude Code, Codex, Cursor и другие клиенты вызывают внешние инструменты, — и по ходу работы сам пишет в память записи: наблюдения, решения, задачи со сроками, гипотезы вместе с результатом проверки. Записи он связывает друг с другом, и у связи есть смысл и вес: «это решение выросло из того наблюдения, и вывод на него сильно опирается». Цепочку от наблюдения до решения агент может сохранить целиком — мы называем это сохраненным рассуждением. Через месяц на вопрос «почему мы так сделали?» находится не только решение, но и путь к нему.

Каждая запись хранит историю: исправленный факт не перезаписывается, а старая версия закрывается датой. Записи разложены по проектам и по слоям — от «нужно всегда» до архива, и сервер сам перекладывает их между слоями. Устойчивые ограничения проекта агент помечает как правила, а то, что станет важно позже, — как напоминания, которые всплывут с нужной даты.

Самое главное происходит при входе в проект: агент получает сводку — что действует, что просрочено, о чем пора вспомнить, какие рассуждения уже есть. Выглядит она так (проект выдуманный, данные демо):

И последнее, что понадобится ниже, — хуки. Это скрипты, которые клиент (Claude Code, Codex) сам запускает в определенный момент: при старте сессии, перед тем как агент передаст ход человеку, перед сжатием контекста. Через хук память может вмешаться, не дожидаясь, пока агент о ней вспомнит.

Вся эта конструкция работает, только если агент пользуется памятью в нужный момент: читает перед тем, как спросить, записывает то, что выяснил, отмечает устаревшее. Это мы и пошли проверять. А как выглядит обычный рабочий день с такой памятью, подробно расскажем в следующей статье.

Что мы читали

Полные логи своих рабочих сессий с июня по сентябрь — больше 13 тысяч файлов: какие инструменты агент вызывал, что ему приходило в ответ и что он делал дальше. Важная оговорка сразу: это наши собственные логи, а не выборка по рынку. Мы видим, что агенты делали, но почти нигде не проверяли, помогло бы им другое поведение.

И вторая оговорка: цифры в разных разделах сняты с разных срезов. Где‑то это тысячи событий, где‑то семь сессий или логи одного пользователя. Размер выборки мы указываем везде, где он известен, чтобы было видно, на чем держится вывод.

Подсказку «можешь прочитать» агент не выполнил ни разу из 7

Начали мы с простой идеи: в памяти все есть, агент умный, понадобится — заглянет. Добавили на вход в проект подсказку: «по этому проекту есть сохраненные рассуждения, можешь прочитать».

За четыре дня модель видела эту подсказку в 7 сессиях. Прочитала — ноль раз. При этом за те же дни агенты сохранили 17 новых рассуждений. Записывать хотели, перечитывать — нет.

А подсказку «свяжи эту запись с той, из которой она выросла», которая в тогдашних версиях kaeru приходила сразу после записи, агент выполнил 751 раз. Это было самое частое действие во всем продукте. В версии 0.8 мы пошли дальше: связь теперь указывается прямо в вызове записи, и отдельная подсказка уже не нужна.

Разница в моменте. Вторая подсказка продолжает то, что агент уже делает. Первая просит отложить задачу, ради которой он пришел, и заняться посторонним. Агенты так не поступают. Если подумать, мы тоже.

Честная оговорка: семь сессий — мало, и это не эксперимент, а наблюдение. Мы знаем только, что агент не стал читать, а помогло бы ему чтение в этих сессиях, не проверяли. Но ноль из семи рядом с 751 выполненной «свяжи» — достаточно яркий контраст, чтобы пересмотреть подход.

Долг выполняется, возможность пропускается

Та же картина повторилась со сводкой при входе в проект. По строке вида «2 записи под вопросом, ждут решения» агенты 8 раз садились разбирать спорные записи. Просроченные задачи исправно закрываются. А строка «можешь прочитать сохраненные рассуждения» не сработала ни разу.

Агент воспринимает долг как часть текущей работы, а возможность вежливо пропускает. С тех пор все, что сводка говорит агенту, мы стараемся формулировать как долг: не «можешь посмотреть», а «это ждет решения».

Агент спрашивает человека, не заглянув в память

Сцена, знакомая всем: агент спрашивает то, что уже лежит в памяти. Это мы пока посчитали на логах одного пользователя. У него 80% вопросов агента к человеку шли без единого обращения к памяти за предыдущие десять минут. Медиана — 74 минуты с последнего чтения.

То есть память агент читает, но не тогда, когда собирается спросить. Отсюда хук: когда агент собирается передать ход человеку, хук ищет в памяти что‑нибудь по теме вопроса и, если находит, сначала отправляет агента прочитать. Один раз, без зацикливания.

«Вопрос» шире знака вопроса

Чтобы хук срабатывал, ему нужно понимать, что агент обращается к человеку. Первая версия смотрела на «?» в конце ответа. Мы прогнали ее по 2 608 моментам, когда агент останавливался и ждал человека, и сравнили с тем, сколько обращений распознает текущая версия.

Обращений к человеку набралось 1 164. Первая версия видела 201 из них — 17%. Больше всего, 856 случаев, она пропускала просьбы в повелительной форме: «скажи», «исправляй», «пришли отчет», «нужен твой ответ по поставщику». Агенты гораздо чаще просят, чем спрашивают.

Что не дошло до модели, то не используется

Эту находку мы бы с радостью не делали. Клиент, в котором мы работали, обрезал инструкцию MCP‑сервера на 2 048 символах, и два месяца мы этого не замечали.

Из инструментов, упомянутых в инструкции до места обрыва, не использовались 9%. Из упомянутых после обрыва — 31%, ровно как у инструментов, которые в инструкции не упомянуты вообще. То есть все, что стояло после обрыва, для модели просто не существовало.

Сейчас вводная инструкция kaeru занимает 1 499 символов. Это не описания инструментов, а короткий текст, который сервер отдает агенту при подключении. Если вы пишете свой MCP‑сервер, проверьте, сколько вашей инструкции доходит до модели в том клиенте, которым пользуетесь.

Необязательное никто не заполняет

У связи в kaeru есть вес: от него зависит, какие рассуждения поднимаются первыми. Вес был необязательным, с удобным значением по умолчанию. За 6 003 вызова инструментов памяти в реальной работе агенты создали 1 262 связи и ни разу не указали вес.

Необязательный параметр с удобным значением по умолчанию оказался гарантией, что о нем никто не подумает. В 0.8 вес связи стал обязательным. А у напоминаний, которые мы добавили позже, срок показа обязательный с самого начала и без умолчания: агент указывает его сам, иначе запись не примется. «Сертификат истекает» и «перемерь эту цифру, прежде чем цитировать» требуют совсем разных сроков, и знает их только тот, кто пишет.

Лучше всего работает то, что не нужно вызывать

Фоновая уборка, которая перекладывает записи между слоями памяти, ни о чем не просит агента. И она сработала с первого же прохода: сама разложила по слоям 33 накопившиеся записи без единого вызова со стороны агента.

Что мы из этого вынесли

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

2. Формулируйте как долг. «Ждет решения» работает, «можешь посмотреть» — нет.

3. Подсказывайте в момент действия. Сразу после записи, перед вопросом человеку, а не в начале сессии про все сразу.

4. Обязательное — без умолчаний. Если параметр важен, агент должен выбрать его сам.

5. Короткая инструкция. И проверьте, сколько ее доходит до модели.

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

Если у вас есть свои наблюдения о том, как агенты обращаются с памятью, особенно если они расходятся с нашими, напишите в комментариях или в чате сообщества. Исходники kaeru — на GitHub, описание — на сайте.