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

Полная архитектура памяти для Claude Code: от CLAUDE.md до семантического поиска. Хуки, крон-скрипты, learnings v2, оптимизация токенов.

Структура workspace

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

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

.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».

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

СОВЕТ

Файл	За что отвечает	Размер	Токены
~/.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% – для работы.

СОВЕТ

Совет. 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, не весь журнал.

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

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

ВНИМАНИЕ

Время	Скрипт	Что делает
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

ВНИМАНИЕ

Внимание. Порядок важен. Сначала ротация 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:

{
  "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%.

## 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 – только там семантический слой хранит не журнал агента, а ваши заметки и материалы.

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

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

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

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: от ошибки к системному изменению

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

Коррекция от пользователя
  → 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:

{
  "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%, уже ощутимо. Сжатие существует для чистоты контекста и сохранения качества агента.

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

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

ПРОМПТ · Промпт для самоаудита AI-агента

Проверь свою конфигурацию по чеклисту:

Memory:

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

Settings:

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

Models:

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

Hooks:

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

Security:

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

Token optimization:

CLAUDE.md меньше 200 строк?
AGENTS.md и TOOLS.md грузятся on-demand, а не через @path-импорт?
Используется /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, тёплый и горячий слой по свежести и холодный архив, связав их хуками. Гайд показывает сборку по шагам.