Compaction и Context Capsules

Compaction — механизм сжатия контекста для работы с длинными сессиями. Вместо того чтобы терять историю, SOBA создаёт Context Capsules — портативные сжатые представления контекста проекта, которые подставляются в системный промпт. Это позволяет агенту «помнить» проект сколь угодно долго — как разработчику, который периодически перечитывает документацию и код, чтобы освежить понимание.

1. Зачем нужен Compaction

Проблема

Модель имеет ограниченное контекстное окно (context window) — типично 64K–128K токенов. Каждый запрос к агенту добавляет сообщения в контекст. Длинная сессия быстро исчерпывает лимит, после чего агент либо теряет начало разговора, либо получает ошибку контекста.

Традиционное решение (плохое)

Простое усечение истории — удаление старых сообщений. Но агент теряет контекст проекта: что уже сделано, какие файлы изменены, какие архитектурные решения приняты.

Решение SOBA (Context Capsules)

Вместо потери истории, агент сжимает её в капсулу — структурированное резюме:

• что было сделано
• какие файлы изменены и почему
• текущее состояние проекта
• ключевые решения и их обоснование
• незавершённые задачи

Капсула занимает ~2-10K токенов вместо 30-100K токенов сырой истории.

2. Как устроены Context Capsules

2.1. Структура капсулы

## SOBA Context Capsule
### Goal
Описание текущей задачи агента.

### Progress
- ✅ Fixed TypeScript errors in src/parser.ts (3 errors)
  - Added return type annotations
  - Fixed generic constraints
- ✅ Added tests for parser (85% coverage)
- 🔄 Working on refactoring utils/validator.ts (in progress)

### Key Decisions
1. Used strict TypeScript mode — rationale: ...
2. Chose Map over Record for parser state

### Current State
- Branch: feat/type-fixes
- Modified files: 5
- Test status: 12 passing, 0 failing

### Blockers
- #42: Need to update API types (blocked by backend deploy)

2.2. Как капсула используется

1. При compaction создаётся новая капсула
2. Старые сообщения (до keepRecentTokens) удаляются из контекста
3. Капсула вставляется в системный промпт
4. Последние keepRecentTokens токенов истории сохраняются для немедленного контекста

2.3. Несколько капсул

При очень длинных сессиях может быть несколько капсул. SOBA объединяет их: последняя капсула идёт в системный промпт полностью, более старые — сжимаются до однострочных резюме.

3. Триггеры compaction

SOBA использует 5 типов триггеров:

3.1. Hard Limit (блокирующий)

Срабатывает: Когда эффективных токенов больше чем:

hardLimit = contextWindow - maxOutputTokens - safetyReserveTokens

Действие: Блокирующий compaction перед следующим вызовом модели. Нельзя отключить через auto: false. Это аварийный механизм.

Пример: contextWindow=65536, maxOutputTokens=8192, safetyReserveTokens=8192 → hardLimit = 65536 - 8192 - 8192 = 49152 токенов

3.2. Turn Complete (фоновый)

Срабатывает: После каждого завершённого хода агента, если:

• auto: true и compactOnTurnComplete: true
• Эффективных токенов ≥ minTokensForAutoCompact (32K)
• ROI проходит проверку (см. §4)

Действие: Фоновый compaction. Асинхронный, не блокирует пользователя.

3.3. Milestone (фоновый)

Срабатывает: При milestone checkpoint (установленном агентом), если:

• auto: true и compactOnMilestone: true
• ROI проходит проверку

Действие: Фоновый compaction на milestone.

3.4. User Request (явный)

Срабатывает: При вызове /compact пользователем.

Действие: Безусловный compaction (ROI-проверка пропускается, но если нечего сжимать — операция no-op).

3.5. Context Overflow (аварийный)

Срабатывает: Когда провайдер возвращает ошибку context overflow.

Действие: Аварийный compaction с более агрессивными настройками (уменьшенный keepRecentTokens, увеличенный порог сжатия).

4. Метрики и конфигурация

4.1. Параметры в config.json

{
  "compaction": {
    "auto": true,
    "compactOnTurnComplete": true,
    "compactOnMilestone": true,
    "minTokensForAutoCompact": 32000,
    "minReclaimableTokens": 12000,
    "minSavingsRatio": 0.25,
    "keepRecentTokens": 20000,
    "safetyReserveTokens": 8192,
    "backgroundTimeoutMs": 15000
  }
}

4.2. Описание параметров

4.3. ROI-проверка

Автоматический compaction выполняет проверку Return on Investment:

reclaimable = effectiveTokens - keepRecentTokens
savingsRatio = reclaimable / effectiveTokens

Compaction выполняется, только если:

• reclaimable ≥ minReclaimableTokens (есть что сжимать)
• savingsRatio ≥ minSavingsRatio (сжатие оправдано)

Пример: 50K эффективных токенов, 20K keepRecent → reclaimable = 30K. savingsRatio = 30/50 = 0.6 (60%) → выше порога 0.25 → OK.

Если эффективных всего 25K → reclaimable = 5K. savingsRatio = 5/25 = 0.2 (20%) → ниже порога → пропускаем.

5. Процесс compaction (пошагово)

1. Триггер — одно из условий §3 срабатывает
2. Сбор контекста — агент собирает все сообщения, результаты инструментов, статус проекта
3. Генерация капсулы — агент создаёт резюме по структуре Context Capsule
4. Замена контекста — старые сообщения удаляются, капсула вставляется в системный промпт
5. Сохранение в сессию — капсула записывается как "type":"capsule" в JSONL

6. Ручное управление

6.1. Команды TUI

# Принудительный compaction
/compact

# Включить/выключить авто-компакт (на лету)
/auto-compact off
/auto-compact on

# Просмотр бюджета
/budget

# Детальная статистика
/budget
/capsule

6.2. Переменная окружения

# Отключить авто-компакт глобально
export SOBA_AUTO_COMPACT=false

6.3. CLI-флаг

# Отключить на один запуск
soba --no-auto-compact

7. Диагностика

7.1. Просмотр состояния контекста

/budget

# Вывод:
# Context Stats:
#   Effective tokens:    38,420
#   Hard limit:          47,616
#   Safety reserve:       8,192
#   Keep recent:         20,000
#   Capsules:             2
#   Messages:            47
#   Turns:               12
#   Last capsule:        2m ago (2,840 tokens)
#   Savings ratio:       0.48 (48%)
#   Auto-compact:        ON
#   Next trigger est.:   ~3 turns

7.2. Просмотр капсулы

/capsule

# Показывает последнюю капсулу в читаемом виде

7.3. Валидация конфигурации

При старте SOBA проверяет compaction-инварианты. При нарушении выводит предупреждение:

⚠️  Compaction disabled: config validation failed:
    keepRecentTokens (40000) must be < hard limit (47300)

8. Portable Capsules

Context Capsules внутри JSONL-сессии нужны для compaction и rewind. Portable Capsules — отдельный формат .capsule.md, который можно передать другой сессии, агенту или проекту.

Основные команды:

/capsule create "handoff auth work"
/capsule export ck_abc ./handoff.capsule.md
/capsule load ./handoff.capsule.md

Подробнее: Portable Capsules.

9. Лучшие практики

9.1. Когда отключать auto-compact

• Короткие сессии (1-3 хода) — compaction не нужен
• Тестирование промптов — нужно видеть полную историю
• Дебаггинг — не хотите терять детали

9.2. Когда включать ручной compact

• Перед сменой задачи в рамках одной сессии
• После крупного рефакторинга (сжать старый контекст)
• Перед долгим перерывом (зафиксировать состояние)

9.3. Оптимизация параметров

• Большие проекты (>50 файлов): увеличьте keepRecentTokens до 30000
• Маленькие проекты (<10 файлов): уменьшите minTokensForAutoCompact до 16000
• Модели с большим контекстом (128K+): compaction менее агрессивен — можно увеличить minSavingsRatio до 0.4
• Модели с reasoning (R1, o1): они потребляют больше токенов на thinking — увеличьте safetyReserveTokens до 16000