Хуки и строки подтверждения
Хуки агентов — это подключаемые хуки хоста, которые внедряют маршрутизированный контекст Engram в начале сессии и при последующей смене задач, когда хост предоставляет безопасный канал контекста во время ввода промпта.
Установка хуков
engram link codex
engram link claude
engram link gemini
engram link cursor
engram link windsurf
engram link --global opencode
engram set-proof compact
Используйте --global для конфигурации на уровне пользователя и engram unlink для удаления только записей хуков, управляемых Engram.
Режим чтения
engram set-read startup|auto|always|manual|off управляет поведением во время выполнения:
autoзагружает память при запуске сессии и при последующих промптах, внедряя только те тела памяти, которые еще не были доставлены в данной сессии.startupзагружает только при запуске сессии.alwaysповторно внедряет память при каждом подходящем шаге.manualиoffснижают автоматизацию.
Кэш хуков хранит хэши, идентификаторы сессий, хост, cwd и ключи памяти, уже доставленные за сессию, — и никогда не сохраняет исходный текст промпта.
Дельта-инъекция (Delta injection)
Для каждого кортежа (хост, cwd, сессия) хук фиксирует ключи, которые он доставил. При вводе промпта внедряются только еще не доставленные тела и добавляется строка already loaded: <ids> для остальных; при отсутствии нового содержимого внедряется только эта строка (со строкой подтверждения, если подтверждение включено), а если ничего не маршрутизировано, память не внедряется. SessionStart и PreCompact сбрасывают набор, поэтому память доставляется снова после новой сессии или сжатия контекста. Записи старше 7 дней удаляются, сохраняется не более 200 записей. OpenCode сохраняет единственный слот системного промпта, поэтому его плагин заменяет или сохраняет текущий слот вместо отправки строгой дельты.
Ограничения размера полезной нагрузки
Хосты обрезают слишком большой вывод хуков, поэтому хук измеряет отрендеренный additionalContext в собственных единицах каждого хоста: не более 2 400 токенов в Codex (байты UTF-8 / 4; Codex ограничивает сообщение примерно 2 500 токенами), не более 9 500 символов в Claude (лимит 10 000) и load.max_tokens в остальных средах. Если текст превышает лимит, хук пересчитывает бюджет: тела сворачиваются в однострочные карточки, а карточки с наименьшим приоритетом опускаются; тело никогда не обрезается посреди текста. Тот же лимит распространяется на SubagentStart и вывод триггеров путей, и только фактически отправленные тела отмечаются как доставленные. Идентификаторы already loaded: сортируются, а sig подтверждения хэширует отсортированные маршрутизированные ключи, поэтому один и тот же набор маршрутизации всегда выводит одинаковые байты.
Триггеры с областью действия пути
При установке хуков Claude, Codex и Gemini также регистрируется триггер пути. Codex всегда использует PreToolUse, а Gemini — AfterTool. Claude использует InstructionsLoaded при hooks.path_rules native (по умолчанию) и PreToolUse при hooks.path_rules hook:
- Claude
InstructionsLoaded(сопоставительpath_glob_match, асинхронный, вывод игнорируется) срабатывает при загрузке сгенерированного файла.claude/rules/engram/<id>.mdи записывает эту память в набор доставленных и вusage.json. Сам файл правила содержит тело, поэтому двойное внедрение исключено. - Claude
PreToolUse(режим хука) сопоставляется сRead,Edit,WriteиMultiEditи используетtool_input.file_path. - В Codex нет инструментов чтения или множественного редактирования, и
PreToolUseне срабатывает при чтении, поэтому триггер активируют только файлы, измененные черезapply_patch. - Gemini
AfterTool(сопоставительread_file|write_file|replace, таймаут в миллисекундах) считывает затронутый путь из входных данных инструмента и добавляет воспоминания к результату инструмента, поэтому они приходят на шаг позже чтения. Сопоставитель Gemini представляет собой незакрепленное регулярное выражение, поэтому хук также запускается для инструментов, имя которых просто содержитreplace; для них он завершается с{}. Он разделяет набор доставленных записей сBeforeAgent.
Когда затронутый путь (относительно рабочего каталога) совпадает с glob-шаблонами applies_to еще не доставленной памяти, хук внедряет до 3 тел на событие в качестве additionalContext. Он никогда не возвращает решение о разрешении, поэтому не может заблокировать вызов инструмента, а пути за пределами рабочего каталога игнорируются. Текст промпта, указывающий реальный путь к файлу, также считается якорем для воспоминаний applies_to.
Выполните engram upgrade --latest (или снова engram link <host>), чтобы добавить триггер пути (InstructionsLoaded или PreToolUse) и PreCompact (Gemini: PreCompress) в старую установку; существующая установка Claude при таком обновлении переключается с PreToolUse на InstructionsLoaded, поэтому сначала выполните engram config set hooks.path_rules hook, чтобы сохранить PreToolUse; обычный engram upgrade не обновляет конфигурации хуков. Claude, Codex и Cursor считывают timeout хука в секундах; управляемые записи записывают 10.
Субагенты
При установке хуков Claude и Codex также регистрируется SubagentStart (сопоставитель *, все типы агентов). Он внедряет маршрутизированный контекст current session в субагент как дополнительный контекст и никогда не возвращает решение. Хуки субагента передают session_id родителя, поэтому набор доставленных воспоминаний субагента индексируется ключом <session_id>#agent:<agent_id>, а родительский набор не затрагивается; сохраняется не более 100 записей субагентов, чтобы они не вытесняли родительские сессии. Вывод SubagentStart в Codex опускает suppressOutput, так как Codex не перечисляет его для этого события. Применяется то же ограничение размера полезной нагрузки. Известный нюанс: Codex не документирует agent_id в PreToolUse, поэтому триггер пути внутри субагента Codex может быть записан в родительский набор доставленных воспоминаний.
Очередь транскриптов сессий (опционально)
engram link claude --session-end и engram link codex --session-end также регистрируют командный хук SessionEnd (таймаут Claude 5 секунд, Codex 3 секунды). Это простой командный хук: он ничего не внедряет, отвечает {}, безопасно завершается при сбое и только добавляет { transcript_path, host, session, at } в игнорируемый git файл session-queue.json в папке памяти рабочего пространства. Записи создаются под блокировкой файла, дедуплицируются по хосту и сессии и ограничиваются 50 самыми новыми. Флаг по умолчанию отключен, engram upgrade никогда не добавляет его (существующая запись сохраняется), engram unlink удаляет его, а Gemini не регистрируется. Сохраняемый путь является абсолютным и содержит имя пользователя ОС, благодаря чему файл никогда не покидает ваш компьютер.
Очистите очередь с помощью engram observe --queue (--dry-run выполняет только проверку, --limit n ограничивает количество записей за один запуск). Каждый транскрипт должен существовать, быть обычным файлом (не символической или жесткой ссылкой) и иметь размер не более 5 МиБ. Он очищается от конфиденциальных данных, освобождается от строк, похожих на инъекции, и сохраняется как трассировка с оберткой входящих сообщений, которая никогда не раскрывает абсолютный путь. Пропущенные или сохраненные записи покидают очередь; записи, исчерпавшие квоту входящих (max_files в необязательном .agents/engram.transcripts.json), остаются в ней. Память напрямую не записывается: повысьте статус файла входящих с помощью engram save-session --file <inbox file> и стандартного подтверждения. Запускайте observe --queue вручную или из простого командного хука, но не из асинхронного хука Codex.
Режим подтверждения
engram set-proof off|compact управляет тем, добавляют ли поддерживаемые хуки компактную строку Engram proof: при каждом подходящем шаге. Отображение подтверждения не зависит от set-read: режим compact может сообщать о загруженных, повторно использованных или пропущенных шагах без изменения момента внедрения полной памяти Engram.
Матрица возможностей хуков
| Хост | Путь конфигурации | События |
|---|---|---|
codex | .codex/hooks.json; глобально ~/.codex/hooks.json | SessionStart, UserPromptSubmit, PreToolUse, PreCompact, SubagentStart (опционально SessionEnd) |
claude | .claude/settings.json; глобально ~/.claude/settings.json | SessionStart, UserPromptSubmit, InstructionsLoaded (PreToolUse при hooks.path_rules hook), PreCompact, SubagentStart (опционально SessionEnd) |
gemini | .gemini/settings.json; глобально ~/.gemini/settings.json | SessionStart, BeforeAgent, AfterTool, PreCompress |
cursor | .cursor/hooks.json; глобальный плагин hooks/hooks.json | sessionStart |
windsurf / cascade | .windsurf/hooks.json; глобально ~/.codeium/windsurf/hooks.json | pre_user_prompt |
opencode | ~/.config/opencode/plugins/engram.js | chat.message, experimental.chat.system.transform |
copilot | Не записывается | Недоступно |
cline | Не записывается | Недоступно |