Паттерн персистентности Notes

Назначение

Сохранение структурированных данных, которые переживают перезапуски workflow или должны передаваться между шагами. Notes обеспечивают key-value хранилище с версионированием и тегами.

Когда использовать

Сценарий	Пример
Восстановление сессии	Сохранение промежуточных результатов для продолжения после прерывания
Передача данных между шагами	Передача сложных данных между agent-directive нодами
Пользовательские настройки	Запоминание выборов, настроек, конфигурации
Результаты анализа	Сохранение исследований, сравнений, рекомендаций
История выполнения	Отслеживание решений во время выполнения workflow

Структура

[collect-data] → [write-note] → [other-steps] → [read-note] → [use-data]

Реализация

Нода write-note

Сохранение результата agent-directive ноды:

{
  "id": "save-analysis",
  "type": "write-note",
  "key": "purchase-{{executionId}}-01-analysis",
  "source": "{{analyze-step-output}}",
  "tags": ["purchase-{{executionId}}", "analysis"],
  "connections": {
    "default": "next-step",
    "error": "handle-error"
  }
}

Паттерн ключа: {domain}-{{executionId}}-{sequence}-{description}

Часть	Назначение	Пример
`domain`	Область workflow	`purchase`, `research`
`scope`	Изоляция выполнения	`{{executionId}}`
`sequence`	Порядок	`01`, `02`, `03`
`description`	Подсказка содержимого	`user-needs`, `analysis`

Пакетный режим записи

Запись нескольких notes из массива:

{
  "id": "save-batch",
  "type": "write-note",
  "source": "{{items-to-save}}",
  "batchMode": true,
  "connections": { "default": "next" }
}

Формат массива source:

[
  { "key": "item-001", "value": "content 1", "tags": ["batch"] },
  { "key": "item-002", "value": "content 2", "tags": ["batch"] }
]

Нода read-note

Загрузка notes в context variable:

{
  "id": "load-data",
  "type": "read-note",
  "outputVariable": "previousData",
  "filter": {
    "keyPattern": "purchase-{{executionId}}"
  },
  "connections": { "default": "use-data" }
}

Режим single для единственной note:

{
  "id": "load-preferences",
  "type": "read-note",
  "outputVariable": "userPrefs",
  "filter": { "tag": "preferences" },
  "singleMode": true,
  "connections": { "default": "apply-prefs" }
}

Нода upsert-note

Обновление существующей или создание новой:

{
  "id": "update-preferences",
  "type": "upsert-note",
  "search": {
    "tag": "user-prefs",
    "keyPattern": "prefs-{{userId}}"
  },
  "keyTemplate": "prefs-{{userId}}-new",
  "value": "{{collected-preferences}}",
  "tags": ["user-prefs"],
  "outputVariable": "saveResult",
  "connections": { "default": "confirm" }
}

Инъекция шаблонов

Прямой доступ к notes в директивах:

{
  "id": "research-step",
  "type": "agent-directive",
  "directive": "Исследуй на основе потребностей пользователя.\n\n**Потребности:**\n{{note:purchase-{{executionId}}-01-user-needs}}\n\nОпредели основные категории.",
  "completionCondition": "Исследование завершено"
}

Синтаксис: {{note:key-name}}

Содержимое note инжектируется в директиву до получения агентом.

Использование MCP Tool

Внутри agent-directive нод используйте MCP tool notes:

// Сохранить note
notes({
  action: "save",
  key: "user-preferences",
  value: JSON.stringify({ theme: "dark", lang: "ru" }),
  tags: ["preferences"]
})

// Получить note
notes({
  action: "get",
  key: "user-preferences"
})

// Список notes по тегу
notes({
  action: "list",
  tag: "preferences"
})

// Проверить квоту
notes({
  action: "stats"
})

Реальный пример

Из smart-purchase-assistant.json:

{
  "id": "write-note-step-1",
  "type": "write-note",
  "key": "purchase-{{executionId}}-01-user-needs",
  "source": "{{step-1-identify}}",
  "tags": ["purchase-{{executionId}}", "smart-purchase"],
  "connections": { "default": "step-2-research" }
}

Далее в workflow:

{
  "directive": "Создай финальный отчёт о покупке.\n\n**Потребности:**\n{{note:purchase-{{executionId}}-01-user-needs}}\n\n**Результаты исследования:**\n{{note:purchase-{{executionId}}-02-research}}"
}

Лучшие практики

Стратегия тегов

Используйте тег выполнения: purchase-{{executionId}}
Используйте тег категории: smart-purchase, research-flow
Позволяет эффективную фильтрацию и очистку

Обработка ошибок

{
  "id": "write-critical",
  "type": "write-note",
  "key": "critical-data-{{executionId}}",
  "source": "{{results}}",
  "connections": {
    "default": "continue",
    "error": "handle-write-error"
  }
}

Сериализация данных

Объекты и массивы автоматически сериализуются в JSON
Примитивные значения сохраняются как строки
Для больших объектов рассмотрите разбиение или artifacts

Антипаттерны

Отсутствие изоляции выполнения

// Неправильно - общий между выполнениями
{ "key": "user-analysis" }

// Правильно - изолирован по выполнению
{ "key": "user-analysis-{{executionId}}" }

Избыточное использование notes для простых данных

Не храните счётчики циклов или временные значения в notes. Используйте expression ноды или context variables.

Хранение больших бинарных данных

Notes предназначены для структурированных текстовых данных. Используйте Artifacts для HTML контента или больших файлов.

Связанные паттерны

Публикация Artifacts - Для HTML контента с публичными URL
Рабочее пространство - Для организованных файловых структур