Notes

Notes provide persistent key-value storage scoped to each user. Data saved in notes survives across workflow executions, enabling preferences, accumulated results, and cross-workflow data pipelines.

• User preferences: Store commit style, preferred region, coding conventions
• Data accumulation: Weekly analysis results compared over time
• Cross-workflow pipelines: Collector workflow saves data, Reporter workflow reads it
• Session continuity: Intermediate results survive session archiving

The notes MCP tool provides 6 actions for agent access:

notes({ action: "save", key: "commit-style", value: "conventional", tags: ["preferences"] })
notes({ action: "get", key: "commit-style" })
notes({ action: "list", tag: "preferences" })
notes({ action: "history", key: "commit-style" })
notes({ action: "delete", key: "commit-style" })
notes({ action: "stats" })

Keys accept alphanumeric characters, underscore, and hyphen. Length: 1-100 characters.

my-config          # valid
project_settings   # valid
2024-report        # valid

Three node types execute note operations without agent interaction. They run server-side and continue to the next node automatically.

Reads notes matching filter criteria into a context variable:

{
  "type": "read-note",
  "id": "load-metrics",
  "outputVariable": "metricsNotes",
  "filter": {
    "tag": "metrics",
    "keyPattern": "metrics-"
  },
  "connections": {
    "default": "process-data",
    "error": "no-data-handler"
  }
}

Writes data from context to a note:

{
  "type": "write-note",
  "id": "save-results",
  "key": "results-{{projectName}}-{{date}}",
  "source": "{{analysisData}}",
  "tags": ["analysis", "{{projectName}}"],
  "connections": {
    "default": "next-step"
  }
}

When source resolves to an object or array, the value is auto-serialized to a JSON string. Strings pass through unchanged, numbers and booleans convert to their string form.

Finds existing note by search criteria or creates a new one:

{
  "type": "upsert-note",
  "id": "update-latest",
  "search": { "tag": "latest-metrics" },
  "keyTemplate": "latest-metrics-{{projectName}}",
  "value": "{{metricsData}}",
  "tags": ["metrics", "latest-metrics"],
  "connections": {
    "default": "next-step"
  }
}

When value resolves to an object or array, the value is auto-serialized to a JSON string.

Reference note content in directive and completionCondition fields using {{note:KEY}} syntax:

Analyze the project using this configuration: {{note:project-config}}

Note content is injected before the agent sees the directive. Missing notes produce [NOTE NOT FOUND: KEY].

Template variables inside note content are resolved after injection:

// Note "greeting" contains: "Hello, {{userName}}!"
// Directive: {{note:greeting}}
// Agent sees: "Hello, Alice!" (when userName="Alice")

This example shows two workflows communicating through Notes: a Collector saves project metrics, a Reporter reads and analyzes them.

Collects metrics and saves them as notes:

flowchart LR
    A[start] --> B[gather-metrics]
    B --> C[write-note]
    C --> D[upsert-note]
    D --> E[confirm-saved]
    E --> F[end]

Key nodes:

write-note saves raw metrics with a timestamped key. The source field references agent output using dot-path syntax — objects and arrays are auto-serialized to JSON:

{
  "type": "write-note",
  "id": "write-metrics-note",
  "key": "metrics-{{gather-metrics.projectName}}-{{gather-metrics.collectionDate}}",
  "source": "{{gather-metrics.metrics}}",
  "tags": ["metrics", "{{gather-metrics.projectName}}", "raw-data"]
}

upsert-note maintains a “latest” reference:

{
  "type": "upsert-note",
  "id": "upsert-latest-summary",
  "search": { "tag": "latest-metrics" },
  "keyTemplate": "latest-metrics-{{gather-metrics.projectName}}",
  "value": "{{gather-metrics.metrics}}",
  "tags": ["metrics", "{{gather-metrics.projectName}}", "latest-metrics"]
}

Reads saved metrics and generates a report:

flowchart LR
    A[start] --> B[ask-project]
    B --> C[read-note]
    C --> D[generate-report]
    D --> E[end]
    C -->|error| F[no-data]
    F --> G[end-no-data]

read-note loads all metrics by tag and key prefix:

{
  "type": "read-note",
  "id": "load-all-metrics",
  "outputVariable": "metricsNotes",
  "filter": {
    "tag": "metrics",
    "keyPattern": "metrics-"
  }
}

The report directive uses {{note:KEY}} to inject the latest snapshot. Dot-path syntax references agent output from previous nodes:

Generate a metrics report.

Latest metrics snapshot:
{{note:latest-metrics-{{ask-project.projectName}}}}

All collected metrics:
{{metricsNotes}}

1. Start the Metrics Collector workflow and provide project metrics
2. Notes are saved automatically via write-note and upsert-note nodes
3. Start the Metrics Reporter workflow for the same project
4. read-note loads all metrics, {{note:KEY}} injects the latest snapshot
5. Agent generates a report comparing data across collection dates

The Collector can run multiple times — each run adds a new timestamped note while upsert-note keeps the “latest” reference current.

Notes are managed through the web interface at the Notes page (accessible from sidebar navigation):

• View all notes with key, tags, size, and preview
• Filter by tag or search by key name
• Create, edit, and delete notes
• View version history and restore previous versions
• Monitor quota usage

• MCP Tools Reference — notes tool with all 6 actions
• Nodes — Automatic node type configuration
• Templates — Template variable syntax including {{note:KEY}}