# Память AI-агента 2026: 4 слоя, хуки, самообучение

## Структура workspace

Каждая папка в `.claude/` отвечает за свой слой:

Принцип разделения: в контекст при старте попадают только 4 файла через `@path/to/file`. Всё остальное – агент читает по запросу через Read tool. Экономия ~18K токенов на каждой сессии.

```text
.claude/
├── CLAUDE.md              # SOUL – личность, роль, стиль, границы
├── settings.json          # Настройки: env, хуки, permissions
├── core/
│   ├── USER.md            # Профиль владельца
│   ├── rules.md           # Операционные правила и границы
│   ├── AGENTS.md          # Справочник агентов (on-demand)
│   ├── MEMORY.md          # Холодная память, индекс уроков
│   ├── LEARNINGS.md       # Архив уроков из ошибок
│   ├── warm/
│   │   └── decisions.md   # Ключевые решения (14 дней)
│   └── hot/
│       ├── handoff.md     # Последние 10 записей (в контексте)
│       ├── recent.md      # Полный журнал (НЕ грузится в сессию)
│       └── archive/       # Старые журналы по датам
├── tools/
│   └── TOOLS.md           # Справочник инструментов (on-demand)
├── skills/                # Скиллы – переиспользуемые навыки
├── hooks/                 # Shell-скрипты для автоматизации
│   ├── block-dangerous.sh
│   ├── protect-files.sh
│   └── ...
└── scripts/               # Крон-скрипты для ротации памяти
    ├── trim-hot.sh
    ├── rotate-warm.sh
    └── ...
```

## 4 слоя памяти

Каждый слой загружается по-разному:

| Слой | Файлы | Загрузка | Время жизни |
|------|-------|----------|-------------|
| IDENTITY | CLAUDE.md + USER.md + rules.md | Автоматически (@path) | Постоянно |
| WARM | decisions.md | Автоматически (@path) | 14 дней |
| HOT | handoff.md (последние 10 записей) | Автоматически (@path) | 24 часа |
| COLD | MEMORY.md, LEARNINGS.md | По запросу (Read tool) | Архив |
| L4 SEMANTIC | внешний семантический слой (напр. pgvector) | По запросу (API) | Бессрочно |

**IDENTITY + WARM + HOT** – загружаются автоматически при старте сессии. **COLD** – агент читает через Read tool, когда нужен старый контекст. **L4** – семантический поиск, когда нужна информация старше 24 часов. Сердце слоя IDENTITY – `CLAUDE.md`: что в нём писать и как не раздуть его до бесполезности, разобрано в гайде [«CLAUDE.md – память и правила для Claude Code»](/guides/claudemd-guide/).

## Что грузится при старте сессии

:::tip
| Файл | За что отвечает | Размер | Токены |
|------|-----------------|--------|--------|
| ~/.claude/CLAUDE.md | Глобальные правила для всех проектов | 7 KB | ~3 200 |
| ~/.claude/rules/*.md | Правила по языкам (python, typescript, bash) | 1 KB | ~430 |
| CLAUDE.md (SOUL) | Личность агента, стиль, роль, границы | 8 KB | ~3 500 |
| core/USER.md | Профиль владельца | 2 KB | ~765 |
| core/rules.md | Операционные правила, безопасность | 4 KB | ~1 935 |
| core/warm/decisions.md | Ключевые решения за 14 дней | 3 KB | ~1 400 |
| core/hot/handoff.md | Последние 10 записей журнала | 1–4 KB | 450–1 800 |
| **ИТОГО** |  | **26–29 KB** | **~11–13K** |

11–13K токенов из 1M рабочего окна – это ~1.2% контекста. Остальные ~99% – для работы.
:::

:::tip
**Совет.** AGENTS.md и TOOLS.md НЕ грузятся при старте – агент читает их через Read tool по запросу. recent.md (полный журнал) тоже НЕ загружается. Только handoff.md – последние 10 записей.
:::

## HOT-память: журнал разговоров

Gateway автоматически записывает каждое взаимодействие в `recent.md`:

Теги источников:

| Тег | Источник |
|-----|----------|
| own_text | Текстовое сообщение |
| own_voice | Голосовое (транскрибация через Groq Whisper) |
| forwarded | Пересланное сообщение |
| external_media | Внешние медиа |

recent.md – полный журнал. Растёт до 80KB+ за день без сжатия. В контекст сессии попадает только **handoff.md** – последние 10 записей (~1–4 KB). Stop-хук извлекает их при завершении сессии. Следующая сессия получает сжатый handoff, не весь журнал.

```text
### 2026-04-14 15:03 [own_voice]
Пользователь: (транскрипция голосового, 200 символов)
Агент: (сжатый ответ, 200 символов)
```

## Крон-скрипты: автоматическая ротация

:::warning
| Время | Скрипт | Что делает |
|-------|--------|------------|
| 04:30 | rotate-warm.sh | WARM старше 14 дней → COLD |
| 05:00 | trim-hot.sh | HOT старше 24ч → Sonnet сжимает → WARM |
| 06:00 | compress-warm.sh | WARM больше 10KB → Sonnet пересжимает |
| 06:30 | semantic-sync.sh | HOT + WARM → семантический слой (pgvector) |
| 21:00 | memory-rotate.sh | COLD больше 5KB → archive/YYYY-MM.md |
:::

:::warning
**Внимание.** Порядок важен. Сначала ротация WARM, потом сжатие HOT, потом пересжатие WARM, потом синхронизация в семантический слой. Sonnet используется для сжатия (не Opus) – дешевле при том же качестве суммаризации.
:::

## Хуки: автоматизация без участия агента

CLAUDE.md – это рекомендация (~80% compliance). Хуки – принуждение (100%). Shell-команды на события жизненного цикла Claude Code.

## Базовые хуки (для любого агента)

**1. block-dangerous.sh** (PreToolUse → Bash)
Блокирует `rm -rf`, `git push --force`, `DROP TABLE`, `curl | bash`. Exit 2 = операция отменена.

**2. protect-files.sh** (PreToolUse → Edit|Write)
Защищает `.env`, `.pem`, `.key`, `secrets/*`, `package-lock.json` от случайного изменения.

**3. log-commands.sh** (PostToolUse → Bash)
Логирует каждую команду в `command-log.txt`. Аудит-трейл.

## Продвинутые хуки (мультиагентная система)

**4. session-bootstrap.sh** (SessionStart)
Загружает топ-5 уроков из `episodes.jsonl`, проверяет inbox, ставит heartbeat «online».

**5. auto-recall.mjs** (UserPromptSubmit)
Отправляет промпт в семантический слой, возвращает релевантные воспоминания. Долгосрочная память без нагрузки на CLAUDE.md.

**6. correction-detector.sh** (UserPromptSubmit)
Ловит фразы типа «не надо», «неправильно» – и триггерит запись урока.

**7. review-reminder.sh** (PostToolUse)
После 10+ правок напоминает запустить code review перед коммитом.

**8. flush-to-semantic.sh** (PreCompact)
Перед компакцией сохраняет HOT+WARM в семантический слой. Ничего не теряется.

**9. write-handoff.sh** (Stop)
Генерирует handoff.md – последние 5 записей, активные топики, изменённые файлы. Следующая сессия начинается там, где закончилась предыдущая.

Конфигурация в `settings.json`:

```json
{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "400000"
  },
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": ".claude/hooks/block-dangerous.sh"
      }]
    }]
  }
}
```

## Оптимизация токенов

Единственная env-переменная: `CLAUDE_CODE_AUTO_COMPACT_WINDOW=400000`. Не ставьте `MAX_THINKING_TOKENS`, `SUBAGENT_MODEL`, `AUTOCOMPACT_PCT` – оставьте дефолты.

## Terse Mode: экономия на выводе

Output-токены стоят в 5 раз дороже input (Opus 4.8: $5 vs $25 за 1M токенов). Добавьте в `rules.md`:

Результат: агент пишет полный код и точные ошибки – сжимается только проза. Экономия ~75%.

```markdown
## Output style
Drop: articles (a/an/the), filler, pleasantries, hedging.
Fragments OK. Short synonyms.
Pattern: [thing] [action] [reason]. [next step].
```

## Стратегия моделей

Opus для кода и решений, Sonnet для субагентов. Без полумер.

| Модель | Роль | Для чего |
|--------|------|----------|
| Opus 4.8 (`claude-opus-4-8`) | Primary | Код, ревью, планирование, координация |
| Sonnet 4.6 | Subagents | Ресёрч, поиск, анализ, сжатие памяти |
| Codex GPT-5.5 | Optional | Double review (второе мнение рядом с Opus) |
| Sonar | Optional | Веб-ресёрч, проверка фактов |

| Модель | Input | Output | Относительно |
|--------|-------|--------|--------------|
| Sonnet 4.6 | $3/M | $15/M | 1x (базовая для субагентов) |
| Opus 4.8 | $5/M | $25/M | ~1.7x (окупается качеством кода) |

На подписке Max ($100–200/мес) все модели включены. Стоимость = расход rate limit, не деньги. Sonnet для субагентов = быстрее ответ + меньше контекста.

## Семантический поиск (L4)

L4 – внешний семантический слой для долгосрочной памяти. Агент ищет по смыслу, не по ключевым словам. В нашей архитектуре это вынесенный сервис на Postgres + pgvector; подойдёт любая векторная БД с эмбеддингами. Тот же приём лежит в основе [базы знаний на Claude Code](/guides/second-brain-knowledge-base/) – только там семантический слой хранит не журнал агента, а ваши заметки и материалы.

Как работает:

1. Stop hook или cron (06:30 UTC) загружает HOT + WARM в семантический слой
2. Слой создаёт эмбеддинги автоматически
3. При следующей сессии `auto-recall.mjs` ищет релевантную информацию

Каждый агент пишет в свой namespace, но ищет по всем. Кросс-агентный поиск из коробки.

```bash
curl -X POST "$SEMANTIC_API/v1/search/find" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{"query": "что решили по API", "limit": 10}'
```

## Learnings v2: самообучение

Агент записывает уроки из ошибок. Не просто «запомнить», а системно менять себя, чтобы ошибка не повторилась.

## Как работает detection

Хук `correction-detector.sh` (UserPromptSubmit) сканирует каждое сообщение пользователя на триггерные слова:

| Категория | Слова |
|-----------|-------|
| Прямые коррекции | «не надо», «не нужно», «неправильно», «не так», «не делай», «перестань» |
| Обвинительные вопросы | «почему ты», «зачем ты», «ты не», «ты забыла», «ты опять» |
| Сломанное состояние | «сломал», «сломала», «сломано», «не работает» |
| Повторные инструкции | «я же говорил», «я уже говорил», «сколько раз» |

При совпадении хук инжектирует напоминание: «КОРРЕКЦИЯ ОБНАРУЖЕНА. Запиши learning через learnings-engine.mjs capture».

## Pipeline: от ошибки к системному изменению

Полный путь от коррекции до изменения системы:

```text
Коррекция от пользователя
  → correction-detector.sh (ловит триггер)
  → learnings-engine.mjs capture (записывает в episodes.jsonl)
  → learnings-engine.mjs score (вычисляет рейтинг)
  → learnings-engine.mjs lint (находит HOT/STALE/PROMOTE)
  → learnings-engine.mjs promote (меняет систему)
```

## Формат записи (episodes.jsonl)

Каждый эпизод хранится как JSON-объект в `episodes.jsonl`:

```json
{
  "id": "EP-20260414-001",
  "ts": "2026-04-14T15:03:00Z",
  "type": "correction",
  "source": "user",
  "context": "что произошло",
  "error": "что было не так",
  "rule": "правило на будущее",
  "impact": "high",
  "tags": ["workflow", "git"],
  "freq": 1,
  "status": "active"
}
```

## Скоринг

Каждый эпизод получает композитный score (0–1):

| Фактор | Вес | Как считается |
|--------|-----|---------------|
| Recency (свежесть) | 40% | Линейное затухание за 30 дней |
| Frequency (частота) | 30% | Сколько раз повторилось (cap: 3) |
| Impact (критичность) | 30% | critical=1.0, high=0.7, medium=0.4, low=0.1 |

Автоматические триггеры:

- **Score > 0.8** или **freq >= 3** → PROMOTE (изменение системы)
- **Score < 0.15** → STALE (архивировать, урок неактуален)
- **freq >= 3** → HOT (правило не работает, менять систему, а не запоминать)

## Пирамида надёжности

| Уровень | Что | Надёжность |
|---------|-----|------------|
| 1 | Память сессии | Теряется при compact/reset |
| 2 | episodes.jsonl | Топ-5 при старте, затухает через 30 дней |
| 3 | LEARNINGS.md | Не в контексте, но из неё создаются скиллы |
| 4 | TOOLS.md / SKILL.md | Ищется grep по запросу |
| 5 | CLAUDE.md / rules.md | Всегда в контексте |
| 6 | Scripts / Hooks | Выполняется автоматически (100%) |

Принцип: чем критичнее ошибка – тем выше по пирамиде она промоутится. Продакшн-баг → сразу в хук/скрипт.

## Куда промоутится по тегам

| Теги эпизода | Целевой файл | Нужно OK владельца? |
|--------------|--------------|---------------------|
| stack, models, tools | TOOLS.md | Нет |
| workflow, communication | CLAUDE.md или SKILL.md | Нет |
| security, git | rules.md | Да |
| config, scp | rules.md | Да |

Зелёная зона (TOOLS.md, SKILL.md) – агент меняет автономно. Красная зона (rules.md, CLAUDE.md) – только с разрешения владельца.

## Три сценария загрузки

| Сценарий | Токены | % от рабочего окна (1M) |
|----------|--------|-------------------------|
| После крона | ~27K | ~2.7% |
| Конец дня (до крона) | ~60K | ~6% |
| Крон сломан неделю | ~114K | ~11% |

При рабочем окне 1M: после крона память занимает ~2.7%, без крона – ~6%. Крон сломан неделю – ~11%, уже ощутимо. Сжатие существует для чистоты контекста и сохранения качества агента.

## Промпт для самоаудита

Скопируйте и отправьте своему агенту – он проверит себя по всем правилам:

:::prompt Промпт для самоаудита AI-агента
Проверь свою конфигурацию по чеклисту:

Memory:
1. Есть ли CLAUDE.md? Сколько строк? (цель: до 200)
2. Есть ли @path-импорты для USER.md, rules.md, decisions.md?
3. Есть ли core/hot/recent.md? Какой размер?
4. Есть ли core/warm/decisions.md?
5. Настроены ли крон-скрипты для ротации памяти?

Settings:
6. CLAUDE_CODE_AUTO_COMPACT_WINDOW установлен? (цель: 400000)

Models:
7. Opus используется для кода и ревью?
8. Sonnet используется для субагентов?
9. Double review настроен (Opus + Codex)?

Hooks:
10. Есть ли PreToolUse хук для блокировки опасных команд?
11. Есть ли PostToolUse хук для логирования?
12. Есть ли Stop хук для записи handoff?

Security:
13. .env, .key, .pem файлы в .gitignore?
14. Секреты хранятся в secrets/?
15. Нет ли хардкоженных токенов в файлах?

Token optimization:
16. CLAUDE.md меньше 200 строк?
17. AGENTS.md и TOOLS.md грузятся on-demand, а не через @path-импорт?
18. Используется /compact между задачами?

Формат: Пройдено: X/18, Не пройдено: [список с рекомендациями]
:::

## Репозитории и тесты

| Репозиторий | Назначение | Ссылка |
|-------------|------------|--------|
| public-architecture-claude-code | Архитектура, шаблоны, скрипты, install.sh | github.com/qwwiwi/public-architecture-claude-code |
| jarvis-telegram-gateway | Gateway: Telegram → Claude Code | github.com/qwwiwi/jarvis-telegram-gateway |
| architecture-brain-tests | 800 тестов, проверяющих всё вышеописанное | github.com/qwwiwi/architecture-brain-tests |
| edgelab-install | Установщик: install.sh ставит всё за 2 минуты | github.com/qwwiwi/edgelab-install |

Категории тестов:

- **T20:** безопасность (нет секретов в шаблонах, .gitignore)
- **T26:** модели (правильные ID, запреты, double review)
- **T27:** COMPACT_WINDOW (порог компакции, 1M контекст)
- **T28:** Learnings v2 (движок, скоринг, пирамида)
- И ещё 25+ категорий

## Следующий шаг

Архитектура открыта. `install.sh` ставит всё за 2 минуты. 800 тестов проверяют, что ничего не сломано. Берите, адаптируйте, улучшайте. Начните с CLAUDE.md и трёх базовых хуков – за час у вас будет агент, который помнит контекст и не повторяет ошибок.

Хочешь собрать агента с полной системой памяти на практике? В сообществе EdgeLab мы делаем это вместе – воркшопы, готовые шаблоны, поддержка.

Узнай больше в сообществе EdgeLab Space – edgelab.space

## FAQ

### Как устроена память AI-агента?
Из 4 слоёв — IDENTITY, WARM, HOT, COLD — плюс семантический слой, хуки и самообучение. Так агент помнит контекст между сессиями, а не начинает с нуля.

### Как сделать так, чтобы агент помнил контекст между сессиями?
Собрать многослойную память: постоянную identity, тёплый и горячий слой по свежести и холодный архив, связав их хуками. Гайд показывает сборку по шагам.