de-roadmap/ai-dev/memory-mechanism.md

# Механизм памяти 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`-файлы памяти
- не полагайтесь только на разговор для сохранения правил