Контекст и знания

Istok запоминает важное о вашем проекте, чтобы вам не приходилось повторять это в каждой сессии. Здесь описаны два вида памяти проекта и то, что получает агент, когда берёт задачу.

Два вида памяти

Контекст — то, что агенту нужно знать с самого начала («Поля публичного API пишутся в snake_case»). Знания — справочный материал, который агент находит, когда тот нужен («Как устроена обработка заказов»).

Прогресс задачи, блокеры и история запусков не относятся ни к тому, ни к другому: они остаются в задаче и в контекст не копируются.

Записи контекста

У каждой записи есть вид: note, decision, instruction или constraint. А ещё режим доставки — он определяет, как запись попадает в запуск:

• always — запись получает каждый запуск. Режим по умолчанию для инструкций. Включённые инструкции упорядочены по приоритету — от critical до low.
• ranked — запись попадает в запуск, если подходит к заголовку, описанию, критериям приёмки и заметкам задачи. Режим по умолчанию для остальных видов.
• manual — запись никогда не выбирается автоматически; она попадает в запуск, только если её ID указали при взятии задачи.

Необязательные даты не дают старым записям задерживаться: после даты review after запись помечается для пересмотра, а после expires at или после замены другой записью (superseded by) она больше не выбирается.

Что получает запуск

Когда агент берёт задачу, Istok собирает для запуска снимок контекста:

записи always + записи, указанные по ID + лучше всего подходящие записи ranked
        +
код для этой задачи из локального индекса (индекс обновляется автоматически)
        +
сводка знаний: заголовки и краткие описания актуальных знаний
        ↓
снимок контекста  →  сохраняется в запуске

Снимок неизменен: если правило поменялось посреди запуска, этот запуск продолжает работать с тем, с чем начал, а новую версию получит следующий. Вы всегда можете посмотреть, что именно сообщили агенту.

Почему объём ограничен

Если бы каждый запуск получал всю память проекта, контекстное окно агента забилось бы ненужным. Поэтому у каждого снимка есть фиксированные лимиты:

Одна запись не может быть больше 12 КиБ. Если записей always больше 12, лимит на число записей растёт — до 64, но лимиты по объёму остаются жёсткими. Записи always попадают в снимок первыми, поэтому делайте их короткими. Если обязательные записи не помещаются, взять задачу не получится, и ошибка назовёт эти записи — Istok не выбрасывает ваши правила молча. См. Решение проблем.

Знания: агент берёт их сам

Запуск получает только сводку знаний. Если заголовок выглядит полезным, агент ищет по каталогу (только метаданные и фрагменты) и читает целиком одну нужную заметку.

Агенты считают знания актуальной истиной, поэтому написать заметку и принять её — разные шаги:

draft  →  reviewed draft  →  current  →  superseded

draft → reviewed draft   ревью (с комментарием)
reviewed draft → current утверждение
current → superseded     замена новым проверенным черновиком

• Редактировать можно только черновики, и правка сбрасывает прошлое ревью.
• Утвердить можно только проверенный черновик. В сводку попадают только актуальные заметки.
• Чтобы изменить актуальное знание, напишите новый черновик, проведите ревью и замените им старую заметку. Старая останется доступна для истории.

Агент может извлечь черновик из законченной работы с указанием происхождения: задач, запусков, записей контекста, заметок знаний или файлов репозитория, из которых он получен. Так ревьюер может сверить его с источниками. Файлом знания становятся, только когда вы сами выгружаете их по выбранному пути.

Как посмотреть, что получил агент

Откройте запуск в веб-интерфейсе и выберите вкладку What the agent saw («Что увидел агент»): там показан снимок и то, сколько лимита он занял.

127.0.0.1:7700/runs

Пока запуска ещё нет, istok context preview 12 покажет, что получит запуск при взятии задачи 12, а istok context doctor найдёт слишком большие, просроченные и повторяющиеся записи. Как сохранять правила и проводить ревью знаний со своей стороны, рассказано в разделе Правила и знания проекта.