Инструменты MCP

Engram поставляется с исполняемым файлом MCP-сервера engram-mcp, который предоставляет инструменты для хостов с поддержкой MCP.

Регистрация

engram link <target> также по умолчанию устанавливает известную регистрацию MCP для этой цели.

Область действия	Путь
Claude Code в рабочем пространстве и другие хосты, читающие .mcp.json (кроме Codex, который читает только ~/.codex/config.toml; см. Глобальный Codex)	.mcp.json
Gemini в рабочем пространстве	mcpServers.engram в .gemini/settings.json
Cursor в рабочем пространстве	.cursor/mcp.json
OpenCode в рабочем пространстве	поле mcp в opencode.json / opencode.jsonc
Глобальный Claude	Не файл: Engram выводит claude mcp add --scope user engram -- engram-mcp (Claude Code хранит пользовательские MCP-серверы в ~/.claude.json)
Глобальный Gemini	mcpServers.engram, объединенный в ~/.gemini/settings.json
Глобальный Codex	Управляемый блок [mcp_servers.engram] в ~/.codex/config.toml
Глобальный Antigravity	Файл конфигурации Gemini MCP
Глобальный OpenCode	поле mcp в ~/.config/opencode/opencode.jsonc / opencode.json
Глобальный Cursor	Встроен в локальный плагин
Глобальный Windsurf	~/.codeium/windsurf/mcp_config.json

MCP рабочего пространства для Windsurf пропускается, поскольку официальный контракт документирует только конфигурацию MCP пользовательского уровня.

Команда сервера — engram-mcp, если она есть в PATH, в противном случае форма npx, закрепленная за установленной версией (npx -y --package @the-long-ride/engram@<version> engram-mcp); engram upgrade и engram link <host> повторно закрепляют существующие записи. Unlink удаляет только запись или управляемый блок Engram и оставляет другие серверы и ключи нетронутыми.

Версии протокола

Один процесс engram-mcp обслуживает две эпохи протокола:

• Устаревшая (Legacy): initialize возвращает protocolVersion клиента, если она равна 2024-11-05, 2025-03-26, 2025-06-18 или 2025-11-25, и 2025-11-25 в противном случае. Неизвестная строка версии никогда не возвращается обратно.
• MCP 2026-07-28: запрос, чей params._meta содержит io.modelcontextprotocol/protocolVersion, обслуживается без сохранения состояния (server/discover, tools/list, tools/call, resources/*, prompts/*). Он также должен содержать io.modelcontextprotocol/clientCapabilities (-32602 при отсутствии). Результаты содержат resultType: "complete", а методы списков добавляют ttlMs и cacheScope. Неподдерживаемая современная версия возвращает -32022 с data.supported и data.requested; ping, initialize и простые методы инструментов возвращают -32601 в эту эпоху.

Stdout передает только JSON-RPC, по одному сообщению на строку.

Инструкции сервера и поиск инструментов

Как результат устаревшего initialize, так и результат server/discover MCP 2026-07-28 содержат одну и ту же строку instructions (не более 512 символов, самодостаточную). Она сообщает хосту, когда использовать инструменты Engram (вспоминать правила и решения проекта, сохранять знания о проекте) и что engram_commit требует участия человека. Codex читает первые 512 символов; Claude Code заранее загружает только имена инструментов плюс instructions, а определения инструментов откладывает до поиска инструментов.

engram-mcp --always-load помечает engram_load флагом _meta["anthropic/alwaysLoad"]: true, чтобы Claude Code загружал этот инструмент заранее. Хуки Claude от Engram уже внедряют контекст, поэтому engram link добавляет этот флаг только тогда, когда хук Claude от Engram не установлен или не устанавливается, и только в конфигурации, которые читает Claude Code: .mcp.json и выводимую команду claude mcp add --scope user. Конфигурации Codex, Cursor, Gemini и Windsurf никогда его не получают. Существующая запись engram в .mcp.json изменяется только при использовании --force, engram upgrade или обновлении. engram-mcp --no-elicitation сохраняет процесс approval_token через чат даже для клиентов, поддерживающих диалог утверждения (см. ниже). Неизвестный параметр engram-mcp игнорируется с примечанием в stderr.

Инструменты

Инструмент	Назначение	Запись
engram_load	Маршрутизация и возврат памяти для задачи (query, id, budget_tokens, disclosure, full, explain)	Нет
engram_route	Классификация задачи и вывод списка памяти, на которую она маршрутизируется	Нет
engram_search	Поиск по памяти по запросу	Нет
engram_verify, engram_status	Проверка хэшей; отчет о работоспособности и счетчиках	Нет
engram_save, engram_save_session	Возврат пронумерованного предложения и approval_token	Нет
engram_commit	Запись утвержденного предложения	Да, после одобрения человеком
engram_set_role, engram_set_rule_variant	Обновление ролей или режима вариантов правил	Да
engram_note	Сохранение отредактированной заметки задачи рабочего уровня (text, objective, type, scope); возвращает {id, file, valid_until}	Да, после одного подтверждения да/отмена

По умолчанию engram_load выдает многоуровневый вывод, описанный в разделе Путь чтения и маршрутизация; передайте full: true для более широкого устаревшего вывода. budget_tokens не действует вместе с id.

Структурированные результаты

Текст для человека находится в content[0].text. structuredContent — это конверт {contract_version, ok, data, diagnostics}, где data содержит:

• engram_load: selected_keys, body_keys, card_ids, omitted_ids (идентификаторы, исключенные бюджетом токенов, доступные через id) и tokens.
• engram_search и engram_route: entries с id, type, scope и score. Записи маршрута идут в порядке загрузки, а не сортируются по оценке.

Одобрение и коммит (Commit)

engram_save и engram_save_session работают только в режиме предложений: они возвращают предварительный просмотр и approval_token. После того как человек утвердит точных кандидатов в чате, вызовите engram_commit с approval_token и approve: "all" или списком номеров кандидатов (начиная с 1). Запись происходит по тому же пути, что и save-session --force, поэтому связанные или дублирующиеся кандидаты откладываются как обычно.

• Токены являются случайными, привязаны к рабочему пространству, одноразовыми и истекают через 30 минут.
• Сохраняется только хэш токена в игнорируемом git файле pending-approvals.json; редактирование ожидающего кандидата приводит к сбою проверки целостности.
• Никогда не вызывайте engram_commit до того, как человек одобрит отображаемых кандидатов.
• engram_commit несет _meta["anthropic/requiresUserInteraction"]: true в tools/list, что заставляет Claude Code запрашивать подтверждение при каждом вызове, даже в режимах обхода. Управляемый блок Codex добавляет [mcp_servers.engram.tools.engram_commit] с approval_mode = "approve", а engram doctor предупреждает (host.gemini_trust), когда запись Gemini mcpServers.engram устанавливает trust: true, что привело бы к пропуску подтверждения.
• Каждый кандидат содержит детерминированную строку Verdict: (ADD, UPDATE <id>, SUPERSEDE <id>, NOOP duplicate of <id>). Токен фиксирует вердикты, а engram_commit применяет SUPERSEDE только до тех пор, пока пересчитанный вердикт по-прежнему совпадает.
• approval_token возвращается агенту. Он доказывает, что предложение существует, а не то, что человек его одобрил. Человеческим шлюзом является запрос разрешений для каждого инструмента хоста для engram_commit, поэтому не добавляйте mcp__engram__engram_commit (или эквивалент вашего хоста) в список разрешений и не одобряйте его автоматически.

Диалог утверждения (Elicitation)

Когда клиент заявляет о поддержке опросных форм (elicitation), engram_save и engram_save_session опрашивают человека в собственном диалоге хоста вместо возврата токена:

• В форме перечисляются номера кандидатов с ADD/UPDATE и заголовками идентификаторов (без текста воспоминаний) и область сохранения; both можно сузить до одной области, но нельзя расширить.
• accept записывает именно выбранных кандидатов по тому же пути, что и engram_commit. approval_token не возвращается.
• decline отзывает предложение: последующий engram_commit с его токеном завершится ошибкой approval was declined in the approval dialog. Недействительный ответ также отзывает его.
• cancel, 60-секундный таймаут или ошибка клиента приводят к возврату к тексту токена выше с префиксом nothing was saved, благодаря чему хосты, заявляющие о поддержке форм, но закрывающие диалог, продолжают работать. Хосту, который автоматически отклоняет запрос, требуется engram-mcp --no-elicitation.
• Устаревшие клиенты получают запрос от сервера к клиенту elicitation/create. Клиенты MCP 2026-07-28 получают результат input_required, чей requestState является запечатанным HMAC истекающим конвертом, привязанным к инструменту, рабочему пространству и аргументам; они повторяют tools/call с inputResponses и этим requestState. Поддельное, истекшее или несоответствующее состояние возвращает -32602 и ничего не записывает. Перезапуск сервера аннулирует открытые состояния, поэтому агент предлагает заново.
• Вызовы без этой возможности и с флагом --no-elicitation используют неизменный поток токенов.

Заметки рабочего уровня

engram_note сохраняет одну короткую заметку задачи в игнорируемый git уровень working/ (source: note, tier: working, valid_until = сегодня + load.working_ttl_days). Текст редактируется, а строки, похожие на инструкции, отклоняются перед предварительным просмотром. Человек отвечает на один запрос да/отмена через тот же диалог, повтор input_required или поток approval_token, описанный выше; decline, cancel и таймаут ничего не записывают. Заметка никогда не обновляет долговременную память с тем же идентификатором, а engram promote — единственный способ сделать ее постоянной. SessionStart опускает заметку, если только ENGRAM_SESSION_OBJECTIVE не совпадает с целью заметки; в противном случае она отображается как однострочная карточка. Инструмент содержит readOnlyHint: false и не содержит destructiveHint.

Правило принудительного выполнения

Явные запросы /engram save-session --force, включая ярлык /engram ss -f, должны использовать путь записи CLI. Подсчитанный ярлык /engram ss -f last 50 sessions должен использовать engram save-session --query-level 50 --force. Хосты только с MCP подтверждают изменения через engram_commit.

Запись MCP для OpenCode

"engram": {
  "type": "local",
  "command": ["engram-mcp"],
  "args": [],
  "enabled": true
}

MCP-сервер реализует стандартное рукопожатие JSON-RPC (initialize, notifications/initialized, tools/list и tools/call) и отвечает на ping. Память также предоставляется как ресурсы MCP (engram://index выводит однострочные карточки, engram://memory/{id} считывает то же тело, что и engram load --id, и считается операцией выборки), а один промпт, propose, возвращает протокол предложений памяти. resources/list возвращает индекс плюс лучшие воспоминания в количестве mcp.resource_limit по использованию (конфигурация JSON, по умолчанию 20, от 0 до 200). Инструменты чтения несут annotations.readOnlyHint: true. Неправильно сформированная строка JSON получает ответ об ошибке -32700, и сервер продолжает работать. Запросы без id являются уведомлениями и не получают ответа, а простой вызов метода, отличный от tools/call, возвращает обычный текст.

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

• Обзор интеграций агентов
• Хуки и строки подтверждения