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

Структура workspace

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

Принцип разделения: в контекст при старте попадают только 4 файла через `@include`. Всё остальное – агент читает по запросу через 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 + WARM + HOT – загружаются автоматически при старте сессии. COLD – агент читает через Read tool, когда нужен старый контекст. L4 – семантический поиск, когда нужна информация старше 24 часов.

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

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

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

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

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

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

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)

Отправляет промпт в OpenViking, возвращает релевантные воспоминания. Долгосрочная память без нагрузки на CLAUDE.md.

6. correction-detector.sh (UserPromptSubmit)

Ловит фразы типа «не надо», «неправильно» – и триггерит запись урока.

7. review-reminder.sh (PostToolUse)

После 10+ правок напоминает запустить code review перед коммитом.

8. flush-to-openviking.sh (PreCompact)

Перед компакцией сохраняет HOT+WARM в OpenViking. Ничего не теряется.

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: $15 vs $75 за 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 для субагентов. Без полумер.

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

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

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

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

1. Stop hook или cron (06:30 UTC) загружает HOT + WARM в OpenViking

2. OpenViking создаёт эмбеддинги автоматически

3. При следующей сессии `auto-recall.mjs` ищет релевантную информацию

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

curl -X POST "http://localhost:1933/api/v1/search/find" \
  -H "X-API-Key: <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):

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

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

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

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

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

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

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

При рабочем окне 400K: после крона память занимает 7%, без крона – 15%. Крон сломан неделю – 29%, ощутимо. Сжатие существует для чистоты контекста и сохранения качества агента.

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

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

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

Memory:
1. Есть ли CLAUDE.md? Сколько строк? (цель: до 200)
2. Есть ли @include для 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, а не @include?
18. Используется /compact между задачами?

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

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

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

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

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

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

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

Узнай больше на edgelab.su