Агентам не нужна память. Им нужна документация
Плагин памяти для агента устроен так: он читает ваши разговоры с моделью, нарезает их на тысячу отдельных фрагментов и складывает в векторную базу. К каждому вашему запросу он прикрепляет пять самых похожих фрагментов. Если агент запутался (а он путается часто), вы даёте ему инструмент поиска и просите найти ещё.
Само по себе это выглядит странно. Ведь задача у вас другая: агент должен понимать ваш проект — где лежит нужная функция, зачем её сделали, о чём вы договорились и что для вас важно. А получаете вы лотерею из кусочков, которые подмешиваются в каждый запрос в расчёте на то, что нужный всплывёт сам.
Кевин Лиао из блога liao.gg приходит к выводу, который удивит любого, кто писал плагины памяти: агентам не нужна память. Им нужна документация.
Что делает любой плагин памяти
Как бы их ни рекламировали, архитектура у них одна и та же. У неё пять шагов:
- Пройтись по записям прошлых сессий.
- Сгенерировать фрагменты — «воспоминания» агента.
- Положить их в RAG-базу.
- К каждому запросу достать пять самых подходящих и подставить в контекст.
- Если не хватило — дать агенту инструмент, чтобы он сам искал в этой базе.
Дальше начинаются украшения. Одни инструменты умеют искать по прошлым разговорам дословно. Другие строят многоуровневую память и делят её на краткосрочную и долгосрочную. Третьи запускают фоновые процессы, которые пересматривают записи, склеивают их и убирают дубликаты. Есть «мечтатели», которые переписывают воспоминания за ночь. Есть постоянное сжатие контекста. Есть пересортировка результатов поиска.
Каждая такая надстройка добавляет новую дорогую по токенам функцию. А архитектура под ней всё та же, и фундамент у неё не работает. Поэтому эти инструменты и не справляются с задачей стабильно.
Пять проблем, из которых не выбраться
Лиао перечисляет проблемы, общие для всего класса плагинов памяти.
Воспоминания подбираются по похожести текста. Поиск по смыслу ранжирует фрагменты по тому, насколько они близки в пространстве векторов. И всё. Вы не знаете, какой из них верный, какой ещё актуален и какого не хватает вообще.
Воспоминания хранятся без контекста. В один фрагмент помещается ограниченный объём текста. Всё остальное теряется: почему так решили, какой урок из этого вынесли, в какой среде это работало.
Прошлое считается истиной. Любой такой плагин опирается на повторное чтение прошлого — через поиск по разговорам или через векторную базу. Но код меняется каждый день. Насколько, к примеру, актуальны пятьсот фрагментов про аутентификацию? Проверить это никто не может.
Агент не ищет то, чего он не знает. Даже если дать ему инструмент поиска, непонятно, когда он до него дойдёт. Агент не осознаёт, что чего-то не знает.
Хранилище нельзя проверить. В SQLite лежат десять тысяч векторов. Какие воспоминания вообще есть? Какие устарели? Какие ещё ни разу не попали ни в один запрос? Какие неверны и при этом тихо влияют на работу агента?
Это, по словам автора, пять проблем из многих. И все они растут из одного и того же допущения, которое разработчики таких плагинов ни разу не ставят под сомнение: агенты забывают — значит, надо запоминать. А чтобы запоминать лучше, надо сохранять больше и искать умнее.
Почему документация, а не повторное чтение
Автор считает, что эта посылка не работает — потому что так не устроено мышление людей. Никто не пересматривает запись встречи трёхлетней давности, чтобы вспомнить ограничения по какой-то функции. Люди записывают и пользуются записями.
По той же причине Лиао считает неудачным и другое решение: дать агенту инструмент поиска, который будет прокручивать десять миллионов токенов прошлых разговоров и собирать из них обрывки того, что было.
Он предлагает другое. Отдельное место в проекте, где агент сам ведёт документацию. Перед работой он читает подходящие документы. После работы обновляет устаревшее и дописывает новое. Пока агент работает, полная картина ещё в его контексте. Поэтому дописывать легко.
Схематично цикл работы меняется с промпта «сделай — забудь» на промпт «сделай — сверься с документацией — обнови документацию». Память из отдельной базы, которую прикручивают к агенту снаружи, превращается в рабочую папку, которую можно прочитать, поправить и показать коллегам.
Сегодня код пишут с помощью ИИ быстрее, чем кто-либо успевает его прочитать. В таких условиях документацию легко объявить второстепенным делом, хотя именно она стала важнее всего остального.
Один AGENTS.md — это ещё не документация
С идеей, что агентам нужен контекст, люди и так договорились: они придумали файлы AGENTS.md, чтобы агент не прыгал в кодовую базу вслепую. Приём работает. Проблема в другом.
Обычно этот единственный файл — вся документация, которая есть в проекте. Одного файла мало. Агенту нужен целый мозг: структурированное рабочее пространство, где он может записывать инструкции, спецификации, решения, результаты исследования, оглавления — и никто его за это не ругает. Инструкции о том, как идёт код-ревью. Спецификации того, что вы обсудили с пользователем. Разобранная один раз документация незнакомой библиотеки или API.
Как автор это проверял
Лиао говорит, что понял проблему больше года назад, когда впервые начал программировать с ИИ. Ему нужен был способ держать работу агента между сессиями, и он завёл папку internal/, где просил агента записывать всё: спецификации, планы, оглавления. Агенту было сказано всегда читать подходящие документы и оглавление перед работой и обновлять их после.
Постепенно эти нехитрые инструкции превратились в формальную систему, а потом в плагин Operator Memory, которым автор пользуется во всех своих проектах. Система устроена ровно так, как описано выше: Markdown-мозг, в котором агент хранит инструкции, спецификации, исследования и оглавления. Перед работой он всегда сверяется с этим мозгом. После работы обновляет: перечитывает устаревшие документы и создаёт новые там, где их не хватает.
Никаких векторных баз. Никаких эмбеддингов. Никаких фоновых помощников: ни тех, что сжимают и пересматривают текст, ни «мечтателей», которые переписывают воспоминания за ночь. Никакого чёрного ящика с поиском. Всё — обычные Markdown-документы, которые можно прочитать, поправить, закоммитить и показать команде. Автор пользуется этим больше года. Проект бесплатный и с открытым кодом: https://github.com/aerovato/operator-memory
Стоит ли соглашаться
Важно понимать, что это позиция автора, а не установленный научный факт. Рынок плагинов памяти огромный, и многие из них построены именно на подходе, который Лиао называет неправильным. Часть его аргументов бьёт по реальной слабости любого RAG: чем длиннее становится база воспоминаний, тем меньше оттуда можно выжать за один запрос. Но сама идея «вместо истории разговоров вести документацию» в проекте не нова — тот же принцип лежит в основе AGENTS.md, спецификаций и любого .md в репозитории, который вы и так читаете вместе с кодом.
Что добавляет Лиао — очень конкретную механику: папка, в которой агент сам пишет и сам обновляет документы, и цикл работы, в котором эта проверка и это обновление обязательны. Если для вашего проекта AGENTS.md действительно остаётся единственным файлом с контекстом, у вас как раз нет повода это менять.