# Механизм памяти coding agents > По мотивам [Memory Mechanism](https://docs.z.ai/devpack/resources/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`-файлы памяти - не полагайтесь только на разговор для сохранения правил