Память OpenCode V2: как сохранять правила между сессиями — это два коротких файла MEMORY.md, глобальный и проектный, подключённые через массив instructions в opencode.jsonc. OpenCode V2 читает AGENTS.md и явно указанные файлы, комбинирует их и не разрешает конфликты автоматически. Начните с проверки версии.
Проверка версии и ветка 2.x
Первое действие — терминал:
opencode --version
Шаги ниже рассчитаны на актуальный выпуск OpenCode V2 с поддержкой instructions. Обновите старый выпуск V2 перед настройкой: одного префикса 2. в ответе недостаточно, чтобы подтвердить загрузку настроенных файлов. В актуальной документации на dev.opencode.ai указано, что OpenCode V2 распознаёт AGENTS.md и не использует CLAUDE.md как запасной вариант. При переносе настроек из другого инструмента подключайте файлы с выбранными именами явно.
AGENTS.md — штатный механизм проектных указаний. В документации проекта он описан как файл с командами сборки, заметками об архитектуре, соглашениями кода и требованиями проверки. Его коммитят, чтобы все работающие в репозитории получали одинаковые указания. Область действия задаётся расположением: OpenCode загружает глобальный файл, затем каждый AGENTS.md от текущей рабочей директории в сторону домашней; для рабочих пространств вне домашней директории обход останавливается на корне проекта.
MEMORY.md — другое решение. Это имя выбирает пользователь, файл подключается вручную через instructions. Встроенного автоматического накопления памяти под этим именем нет: содержимое появляется только тогда, когда его добавил человек или его агент по вашей команде.
Три разных слоя: разговор, инструкции, факты
Разведите три вещи, которые легко смешать.
Текст текущего разговора живёт в истории сессии. Он влияет на ответы, пока сессия открыта, и не переносится в следующий запуск сам по себе.
Проектные инструкции — это AGENTS.md и подключённые файлы. Они задают правила работы: как называть ветки, где лежат запросы к базе, что запускать перед коммитом. Документация проекта описывает AGENTS.md как источник постоянных указаний.
Сохранённые автором факты — это записи, которые вы решили удержать: команда проверки, адрес стенда, договорённость о формате ответа. Их место — MEMORY.md. Разница практическая: инструкция говорит, как действовать; факт сообщает, что известно. Смешение приводит к тому, что файл растёт, а нужная строка теряется.
Два файла MEMORY.md и кто их ведёт
Создайте два файла.
Глобальный: ~/.config/opencode/MEMORY.md. Здесь живут предпочтения, действующие во всех проектах.
Проектный: .opencode/MEMORY.md в корне репозитория. Здесь — факты конкретного проекта.
Оба файла ведёт человек. Добавляет запись тот, кто обнаружил устойчивый факт; исправляет — тот, кто заметил расхождение. Агент может предложить строку, но запись в файл остаётся вашим решением. Так вы сохраняете контроль над тем, что попадёт в следующую сессию.
Держите файлы маленькими. Длинный файл дороже читать и легче пропустить при просмотре. Если процедура занимает больше нескольких строк, вынесите её в отдельный документ и подключайте по необходимости.
Конфигурация V2: instructions для двух файлов
Один opencode.jsonc подключает оба файла:
{
"$schema": "https://opencode.ai/config.json",
"instructions": [
"~/.config/opencode/MEMORY.md",
".opencode/MEMORY.md"
]
}
Путь с ~ разрешается от вашей домашней директории. Относительный путь ищется в каждой директории от рабочего пространства до корня проекта. Абсолютный путь используется как записан.
Настроенные файлы загружаются после AGENTS.md, в порядке перечисления. Записи из всех конфигурационных документов комбинируются. Отсутствующий файл пропускается: пока .opencode/MEMORY.md не создан, конфигурация остаётся рабочей. Локальные файлы обновляются при изменении, как AGENTS.md. Новые файлы, попавшие под glob, загружаются при следующем изменении конфигурации.
Пример: глобальное правило и проектный факт
Глобальный файл ~/.config/opencode/MEMORY.md:
# Предпочтения
Поясняй команды одной короткой фразой.
Проектный файл .opencode/MEMORY.md:
# Факты учебного проекта
Команда проверки: python -m unittest discover.
Источник: README учебного проекта; проверить перед использованием.
Учебный маркер: МАЯК-71.
Команду проверки подставьте свою. Значение выше — пример для учебного проекта. Маркер нужен для проверки из следующего раздела: это редкая строка, которую легко найти в ответе модели.
Правило ведения записей
Каждая строка строится по одной схеме: факт, область действия, источник или дата. Учебный пример записи:
Команда проверки: python -m unittest discover.
Область: учебный репозиторий.
Источник: README учебного проекта; проверить перед использованием.
Дату подтверждения добавляют после фактической проверки в своём проекте.
Устаревшее убирайте. Файл, в котором лежат противоречащие строки, даёт модели оба варианта: OpenCode комбинирует источники и не разрешает конфликты между ними. Чистка — часть обслуживания.
Длинную процедуру храните отдельным документом. В MEMORY.md оставьте короткий факт и путь к подробностям; сам подробный документ агент читает по необходимости. Файлы, постоянно перечисленные в instructions, загружаются вместе с остальными указаниями.
Поведенческая самопроверка в двух сессиях
Проверка показывает, дошли ли записи до новой сессии. Это упражнение читателя; редакция модель не запускала, и соблюдение указаний не гарантируется.
Сессия первая. Запустите OpenCode в проекте и попросите перечислить действующие указания, не повторяя маркер в запросе. Если в ответе появился МАЯК-71, файл прочитан.
Сессия вторая, контрольная. Уберите .opencode/MEMORY.md из массива instructions, начните новую сессию и задайте тот же вопрос. Маркер исчезает — значит, строка приходила именно из файла.
Проверка поведенческая: она показывает, что файл загружен и виден модели. Она не доказывает, что модель будет следовать каждой строке в каждой задаче.
Порядок комбинирования и конфликты
Системная подсказка выбранного агента или провайдера отправляется первой. Дальше OpenCode собирает начальные указания по порядку: подсказка агента или провайдера; руководство инструментов Code Mode, когда включено; указания MCP-серверов, справочников и навыков; глобальный и проектные AGENTS.md, затем настроенные инструкции; встроенный контекст даты и окружения; записи указаний конкретной сессии, переданные через API.
Источники комбинируются. Вложенные AGENTS.md, обнаруженные позже, добавляются в историю сессии в порядке обнаружения: файлы ниже рабочего пространства находятся по мере исследования проекта, ближайшие загружаются первыми и дедуплицируются, пока их запись остаётся видимой модели. Автоматического разрешения конфликтов между источниками нет: если два файла требуют разного, в контекст попадут оба требования.
Что в MEMORY.md не записывают
Настройки модели, провайдера и permissions в MEMORY.md не попадают. Это конфигурация: ключи, выбор модели, разрешения на команды задаются в конфигурационных файлах и остаются там.
Практическое следствие: не переносите в MEMORY.md строки вида «использовать такую-то модель» или «разрешить такую-то команду». Такая запись не меняет поведение инструмента, зато создаёт ложное впечатление, что настройка применена. Значения указаний остаются привилегированными: клиенты видят, какие источники изменились, но не их содержимое.
Сравнение с плагином
Плагин — отдельный путь. В документации проекта плагин описан как пакет с серверной частью, частью TUI, GUI или их комбинацией; он добавляет инструменты, хуки, интеграции, команды и агентов. Плагины из .opencode/plugins/ загружаются автоматически, опубликованные пакеты добавляются в массив plugins.
Разница в назначении и сложности. Два файла MEMORY.md и массив instructions решают задачу удержания фактов без установки пакетов и без кода. Плагин нужен, когда требуются новые инструменты, хуки или интеграции. Сборка dot-opencode/memory на GitHub — пример отдельного проекта с трёхуровневой файловой памятью и плагином для OpenCode V2; это внешняя разработка со своим порядком установки.
Частые вопросы
Как включить память в OpenCode?
Создайте ~/.config/opencode/MEMORY.md и .opencode/MEMORY.md, затем добавьте оба пути в массив instructions в opencode.jsonc. Встроенного автоматического накопления под этим именем нет: записи добавляет человек. Файл, которого ещё нет, пропускается, и конфигурация продолжает работать.
Почему правила не применяются в новой сессии?
Проверьте, что установлен актуальный выпуск OpenCode V2, путь к файлу указан в instructions и файл существует по этому пути. Для старых выпусков одного префикса 2. недостаточно, чтобы подтвердить поддержку загрузчика. Правки во вложенном AGENTS.md после загрузки автоматически не отслеживаются — начните новую сессию, чтобы обновлённый текст применился сразу. Для глобального файла и файлов, найденных при движении вверх, изменение подхватывается до следующего запроса к модели.
Чем MEMORY.md отличается от AGENTS.md?
AGENTS.md — штатный файл проектных указаний, который OpenCode находит сам по расположению. MEMORY.md — обычный файл, который вы подключаете вручную через instructions. Первый задаёт правила работы, второй хранит факты. Оба комбинируются в контексте, и конфликты между ними автоматически не разрешаются.
Как проверить, что файл действительно прочитан?
Добавьте в файл редкую строку-маркер, начните новую сессию и попросите перечислить действующие указания, не повторяя маркер в запросе. Затем уберите файл из instructions, начните ещё одну сессию и повторите вопрос. Это поведенческая самопроверка загрузки.
Можно ли подключить файл правил по ссылке?
Да, массив instructions принимает адреса http:// и https://. Такой адрес запрашивается при загрузке конфигурации с таймаутом в пять секунд. Если адрес недоступен, он пропускается или сохраняет последнее полученное содержимое. Локальные файлы обновляются при изменении, как AGENTS.md.