Механизм памяти coding agents

По мотивам Memory Mechanism (Z.AI DevPack)

Память позволяет coding agent сохранять контекст между задачами и сессиями, сокращая повторный ввод и повышая эффективность выполнения. С хорошо продуманной системой памяти агент может постоянно учитывать структуру проекта, инженерные конвенции и предпочтения пользователя, автоматически переиспользуя эту информацию в будущей работе.

В системах coding agents память обычно организована в несколько слоёв: автоматическая память, проектная память и сессионная память.

Зачем coding agents нужна память?

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

Агентные системы решают это ограничение через внешнюю память.

Типичная архитектура выглядит так:

Ввод пользователя
       ↓
Извлечение памяти
       ↓
Сборка контекста
       ↓
Рассуждение LLM
       ↓
Действие / вызов инструмента
       ↓
Обновление памяти

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

Эта архитектура является общим паттерном в современных агентных системах, таких как LangGraph, AutoGPT и Devin.

Полная архитектура памяти

На высоком уровне полная архитектура памяти агента выглядит так:

Краткосрочная память
    ↓
Контекст сессии

Долгосрочная память
    ├ семантическая память
    ├ эпизодическая память
    └ процедурная память

Основные типы памяти

Сессионная память

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

Пример:

Пользователь: Исправь этот баг в Python
Агент: Анализирует ошибку
Агент: Модифицирует код
Агент: Запускает тесты

Все эти шаги выполнения относятся к сессионной памяти.

Проектная память

Проектная память хранит долгоживущую информацию о всей кодовой базе: архитектуру проекта, стандарты кодирования, процессы сборки, часто используемые команды. Такая память обычно записывается в .md-файлы и загружается в начале сессии.

Пример структуры:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Основные инструкции проекта
│   └── rules/
│       ├── code-style.md   # Стиль кода
│       ├── testing.md      # Конвенции тестирования
│       └── security.md     # Требования безопасности

При такой структуре агент автоматически следует этим правилам при модификации кода.

Семантическая память

Семантическая память хранит фактические знания и справочную информацию: документацию API, правила языков программирования, базы знаний проекта. На практике часто реализуется через RAG (Retrieval-Augmented Generation).

Типичный поток:

запрос
  ↓
эмбеддинг
  ↓
векторный поиск
  ↓
извлечение документов
  ↓
рассуждение LLM

Это один из наиболее распространённых методов запоминания в coding agents.

Эпизодическая память

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

Пример:

Эпизод:
Сбой CI из-за отсутствующей зависимости
Решение: обновить pip-пакет

Процедурная память

Процедурная память хранит стратегии или пошаговые процессы выполнения задач.

Пример:

Debug_Workflow.md
1. прочитать лог ошибок
2. найти файл
3. написать патч
4. запустить тесты

Такая память обычно используется в системных промптах, шаблонах рабочих процессов и политиках агента.

Стандартный паттерн использования памяти

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

Шаг 1: Извлечение памяти

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

Шаг 2: Сборка контекста

Извлечённые воспоминания собираются в полный контекст и передаются модели.

Шаг 3: Обновление памяти

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

Как правильно использовать память

В основных агентных системах память проектируется как многослойная, управляемая, извлекаемая и обновляемая.

Обычно память делится на краткосрочную и долгосрочную. Краткосрочная используется для сохранения состояния в текущем потоке или сессии. Долгосрочная поддерживается через явные файлы, конфигурации правил, векторное извлечение или другие механизмы постоянного хранения.

Например, в Claude Code каждая сессия начинается с чистого контекстного окна. Знания переносятся между сессиями через файлы инструкций (CLAUDE.md) и автоматическую память. В LangChain / LangGraph память также делится на краткосрочную в рамках потока и долгосрочную между сессиями.

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

Разделяйте инструкционную и обучающую память

Один из наиболее практичных принципов: различать два фундаментально разных вида памяти.

• Инструкционная память: написана людьми, чтобы указать агенту, как он должен работать. Обычно включает стандарты кодирования, конвенции директорий, команды сборки, процедуры тестирования, требования к именованию, правила коммитов и правила безопасности на уровне команды. В Claude Code это файлы инструкций вроде CLAUDE.md

• Обучающая память: не определена заранее, а накоплена агентом из ваших поправок, предпочтений, неудачных попыток, частых команд и привычек проекта. В Claude Code это называется автоматическая память (auto memory)

Если эти два типа памяти смешиваются, поведение системы со временем дрейфует. Лучший подход: чётко разделить их роли.

• Правила, политики и поведенческие ограничения записывайте в инструкционную память, чтобы поведение агента оставалось стабильным и предсказуемым
• Опыт, предпочтения пользователя, временные открытия и ретроспективные выводы записывайте в обучающую память, чтобы решения улучшались в будущих задачах

Это разделение предотвращает постепенное загрязнение основных правил системы заметками из опыта.

Многоуровневое управление памятью

Уровень организации

Правила, определённые и распространяемые на уровне команды или компании, применимые ко всем разработчикам и проектам:

• требования безопасности и соответствия
• базовые стандарты код-ревью
• запрещённые директории для чтения/записи
• ограничения зависимостей и лицензий
• инженерные стандарты организации

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

Уровень проекта

Командный контекст проекта, версионируемый и общий для всех участников. Это самый важный слой памяти для coding agent.

• документация архитектуры проекта
• конвенции структуры директорий
• команды сборки и тестирования
• где должны располагаться API
• конвенции именования
• типовые процессы разработки

Claude Code рекомендует хранить эту информацию в проектном файле, а команда /init может автоматически сгенерировать первоначальный черновик. Ключевое свойство этого слоя: общий для проекта, под контролем версий, стабильный во времени.

Уровень пользователя

Персональные предпочтения разработчика, применимые ко всем проектам. Лучше хранить в домашней директории пользователя как переиспользуемый личный контекст для всех рабочих пространств:

• предпочитаемый стиль кодирования
• привычная последовательность отладки
• предпочитаемый формат вывода
• персональные быстрые команды

Должен дополнять проектные конвенции, а не переопределять их.

Локальный уровень

Специфичен для вашей локальной копии проекта, не должен попадать в Git:

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

Ценность этого слоя: позволяет индивидуальную эффективную работу без загрязнения общей памяти.

Уровень субагента / роли

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

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

• агент тестирования помнит команды тестирования, поведение CI, стиль утверждений
• агент рефакторинга помнит границы модулей, запрещённые зависимости, стратегии миграции
• агент документации помнит глоссарий терминов, шаблоны документации, стиль для целевой аудитории

Это делает память короче, точнее и стабильнее.

Загрузка .md-файлов по пути

Для крупных репозиториев рекомендуется разделять инструкции на несколько Markdown-файлов в .claude/rules/, каждый посвящён одной теме: testing.md, api-design.md, security.md.

Claude Code также поддерживает привязку правил к определённым поддиректориям или типам файлов: правила загружаются только когда агент работает с подходящими файлами. Это снижает шум и экономит контекстное окно.

Три принципа организации:

• Основной файл памяти ограничен глобальным общим контекстом: фон проекта, высокоуровневая архитектура, кросс-проектные конвенции
• Специализированные правила модульны: один файл правил на тему
• Если правило можно загрузить по пути, не загружайте его глобально: включайте в контекст только при необходимости

Пример структуры:

agent-memory/
├── project.md            # Обзор проекта
├── rules/
│   ├── code-style.md     # Стиль кода
│   ├── testing.md        # Конвенции тестирования
│   ├── api-design.md     # Правила дизайна API
│   ├── security.md       # Требования безопасности
│   └── frontend/
│       └── react.md      # Правила фронтенда
└── local/
    └── developer.local.md

Три преимущества такой структуры:

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

Пишите правила памяти как конкретные инструкции

При написании памяти агента используйте конкретные, проверяемые правила, а не абстрактные принципы. Чем яснее инструкции, тем стабильнее поведение агента.

Общие рекомендации:

• инструкции должны быть лаконичными и явными
• правила должны быть согласованы друг с другом
• основной файл памяти не более 200 строк по возможности
• используйте Markdown-заголовки и списки для читаемости
• формулируйте требования как правила, которые можно проверить и выполнить

Избегайте расплывчатых формулировок:

• ~~Держите код чистым~~
• ~~Пишите хорошие тесты~~
• ~~Следите за дизайном API~~
• ~~Разделяйте модули при необходимости~~

Предпочитайте конкретные правила:

• Используйте 2-пробельный отступ во всех новых TypeScript-файлах
• Запускайте pnpm test после модификации бизнес-логики
• Размещайте все обработчики API в src/api/handlers/
• Держите React-компоненты страниц менее 300 строк; разбивайте большие на хуки или дочерние компоненты

Конкретные правила значительно сокращают пространство для интерпретации агентом, что повышает стабильность поведения.

Переиспользование памяти через импорт

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

В Claude Code:

• CLAUDE.md может импортировать другие файлы правил через @path/to/import
• .claude/rules/ может делить правила через символические ссылки (symlinks)
• импортируемый контент раскрывается рекурсивно, символические ссылки разрешаются нормально

Это позволяет командам создавать переиспользуемые пакеты правил:

• company-security-rules
• frontend-react-rules
• backend-api-rules
• python-testing-rules

Каждый проект ссылается только на нужные модули правил, а не поддерживает полную копию всего набора.

Два прямых преимущества:

1. Правила поддерживаются централизованно и обновляются единообразно
2. Разные проекты разделяют один инженерный язык, делая поведение агента согласованным между репозиториями

Устранение проблем с памятью

Агент не следует .md-файлам памяти

.md-файлы памяти предоставляются агенту как контекстные инструкции, а не как принудительная конфигурация. Агент прочитает их и попытается следовать, но не гарантирует строгое соблюдение при расплывчатых, неясных или конфликтующих правилах.

Если агент не следует правилам, проверьте:

• Подтвердите загрузку .md-файлов памяти (команда /memory или аналог)
• Проверьте, находятся ли файлы в пути, разрешённом для загрузки в текущей сессии
• Проверьте конфликты правил между файлами. Если разные файлы дают разные инструкции для одного поведения, агент может выбрать произвольно

Непонятно, что сохранила автоматическая память

Большинство coding agents поддерживают авто-память в фоне для захвата контекста проекта, предпочтений пользователя или частых действий.

Способы проверки:

• Выполните /memory (или аналогичную команду) для просмотра текущей директории авто-памяти
• Авто-память обычно хранится в Markdown-файлах, которые можно читать, редактировать или удалять напрямую

Файлы памяти слишком большие

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

Рекомендуется:

• разделить детальный контент на несколько Markdown-файлов
• использовать ссылки на файлы или импорты (@path/to/file)
• перенести правила в выделенную директорию правил (rules/)

Инструкции исчезают после сжатия контекста

Многие coding agents сжимают или резюмируют контекст в длинных разговорах для уменьшения длины контекста.

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

Решение:

• записывайте долгосрочные инструкции в .md-файлы памяти
• не полагайтесь только на разговор для сохранения правил