okf-notebooks

Сценарии

Типовые способы использовать okf-notebooks: шаги настройки и ссылки на справочные страницы.

В каждом сценарии предполагается, что сервер запущен и у агента есть токен: см. Установка.

Память одного агента

Когда: вы работаете с Claude Code (или другим MCP-клиентом) и хотите, чтобы он помнил решения, термины и runbook’и между сессиями — в файлах, которые вы можете открыть сами.

  1. Создайте блокнот со встроенным пресетом core (Project, Decision, Playbook, Term). Дайте ему понятный scope: агент выбирает блокнот по назначению, а не по имени.
  2. Подключите агента и вставьте блок из okf-notebooks print-agent-guide в CLAUDE.md или AGENTS.md.
  3. Просите обычными словами: «посмотри в заметках», «запиши в блокнот». Агент начинает с notebooks_list, выбирает блокнот по scope и ищет через notebook_search.

Каждая заметка попадает в notebooks/<slug>/ как Markdown с frontmatter, по коммиту на запись.

Подробнее: Формат блокнота (OKF), Заметки и проверка.

База знаний проекта

Когда: команда и её агенты ведут знания о программном проекте: глоссарий предметной области, ADR, спеки, тикеты, исследования, прототипы, диагностику багов и ретроспективы.

  1. Укажите в конфиге presets_dir с каталогом пресетов и создайте блокнот с --preset dev-project.
  2. Агенты записывают каждый вид знаний отдельным типом заметки со своими обязательными полями и сроком устаревания.
  3. Нужен свой словарь (Runbook, Incident…)? Опишите пресет YAML-файлом; каталог читается при каждом обращении, перезапуск не нужен.

Подробнее: Пресет dev-project, Свои пресеты типов.

Несколько агентов, одна память

Когда: Claude Code пишет заметки, opencode читает и дополняет их, внешний harness (например, в CI) только читает, а человек проверяет и одобряет.

  1. Выпустите по токену на агента и машину: token create --actor claude-code --label laptop, --actor opencode, --actor external-harness. Актор и его права определяются только токеном.
  2. Если права по умолчанию не подходят, настройте actors.<name>.allow (read, write, notebook_creation, comments).
  3. Параллельные правки безопасны: notebook_update принимает etag, и устаревший отклоняется вместо того, чтобы затереть чужое изменение.

Подробнее: Несколько агентов, Заметки и проверка.

Проверка человеком

Когда: нужно знать, какие заметки действительно проверил человек.

  1. Всё, что пишет агент, — draft. Человек ставит verified (okf-notebooks verify) и статус stable или deprecated (okf-notebooks mark) в CLI или веб-интерфейсе ревью.
  2. Если агент потом правит проверенную заметку, отметка снимается, так что «проверено» всегда относится к текущему тексту.
  3. В веб-интерфейсе можно читать заметки, смотреть историю ревизий с diff и обсуждать фрагмент в тредах комментариев, на которые отвечают агенты.
  4. Агент может запросить новый блокнот или тип; при политике proposal по умолчанию человек одобряет или отклоняет заявку (okf-notebooks notebook pending).

Подробнее: Веб-интерфейс ревью, Жизненный цикл блокнота и типов.

Заметки, которые уже есть

Когда: у вас уже есть каталог OKF-заметок, например docs проекта.

  1. Выполните okf-notebooks notebook adopt <path> --slug <slug>. Каталог копируется в notebooks/<slug>/, исходник не меняется, каждый файл проходит проверку; при ошибках блокнот не создаётся.
  2. Заполните description и scope в .okf/notebook.yaml, чтобы агенты могли выбрать блокнот.

Подробнее: Подключение существующей OKF-базы.

Не только код: финансы и ретро агентов

Когда: та же проверяемая память нужна не для кодовой базы.

  • personal-finance: агент как финансовый помощник одного домохозяйства. Остатки и рыночные вводные устаревают за 30–90 дней, так что старые числа видны; предложения агента отделены от ваших решений.
  • agent-retros: один блокнот ретроспектив по всем проектам. Разборы сессий сводятся в паттерны, паттерны — в конкретные изменения скиллов, CLAUDE.md и инструментов, а эффект проверяется.

Оба лежат YAML-файлами в presets/: включите presets_dir и создайте блокнот с --preset. Это примеры: для других задач придумайте свои типы или попросите агента их предложить.

С разных машин и с бэкапом

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

  1. По умолчанию принимаются только loopback-значения Host. Перечислите подсети LAN или VPN в server.allowed_hosts или поставьте сервер за reverse proxy с TLS. Никогда не пробрасывайте порт на роутере.
  2. Укажите в git.remote приватный репозиторий: коммиты пушатся в фоне, okf-notebooks sync пушит по запросу, а okf-notebooks doctor перед бэкапом проверяет, что ничего не осталось незакоммиченным.

Подробнее: Доступ по сети, Git-публикация и бэкап.