Class ScratchpadManager

Manages the agent's ephemeral scratchpad (notes + task list) during a single run.

The scratchpad is:

In-memory only — not persisted to DB (snapshots are stored in step InputData/OutputData)
Ephemeral per run — starts empty, garbage collected when the run ends
Private — never shared with parent or sub-agents

Example

const manager = new ScratchpadManager();

// Apply changes from LLM response
manager.applyScratchpadChanges({
    notes: "Found 3 data sources to analyze",
    taskList: {
        upsert: [
            { id: "t1", title: "Analyze sales data", status: "in_progress" },
            { id: "t2", title: "Analyze marketing data", status: "pending" }
        ]
    }
});

// Get snapshot for step OutputData
const snapshot = manager.toJSON();

// Get prompt-friendly representation
const promptText = manager.toPromptString();

Index

Constructors

constructor

Methods

ApplyScratchpadChanges Clear EnforceTaskLimit GetNoteLines GetNotes GetTaskCounts GetTasks GetTasksByStatus GetTaskSummary HasContent PruneNotes RemoveTasks SetNotes ToJSON ToPromptString UpsertTasks

Constructors

constructor

new ScratchpadManager(): ScratchpadManager
Returns ScratchpadManager

Methods

ApplyScratchpadChanges

ApplyScratchpadChanges(scratchpad: AgentScratchpad): void
Apply a scratchpad change from the LLM response. Handles both notes and task list changes in one call.
Parameters
- scratchpad: AgentScratchpad
Returns void
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:202

Clear

Clear(): void
Reset the scratchpad to empty state.

Returns void
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:313

EnforceTaskLimit

EnforceTaskLimit(maxTasks: number): number
Enforce the maximum task limit by pruning completed tasks (oldest first). Returns the number of tasks pruned.
Parameters
- maxTasks: number
Returns number
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:223

GetNoteLines

GetNoteLines(): string[]
Return individual non-empty note lines from the scratchpad notes.

Returns string[]
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:68

GetNotes

GetNotes(): string
Get the current notes content.

Returns string
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:61

GetTaskCounts

GetTaskCounts(): Record<AgentTaskStatus, number>
Return counts per status.

Returns Record<AgentTaskStatus, number>
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:181

GetTasks

GetTasks(): AgentTask[]
Return the current task list.

Returns AgentTask[]
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:167

GetTasksByStatus

GetTasksByStatus(
status: "blocked" | "pending" | "in_progress" | "completed",
): AgentTask[]
Return tasks filtered by status.
Parameters
- status: "blocked" | "pending" | "in_progress" | "completed"
Returns AgentTask[]
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:174

GetTaskSummary

GetTaskSummary(): string
Returns a compact one-line summary of task progress. E.g., "3 of 7 tasks complete, 1 blocked"

Returns string
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:289

HasContent

HasContent(): boolean
Returns true if the scratchpad has any content (notes or tasks).

Returns boolean
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:306

PruneNotes

PruneNotes(maxNotes: number): number
Enforce a maximum number of note lines in the scratchpad by pruning the oldest low-priority note lines first, then the oldest remaining lines if still over the limit.

High-priority notes are lines marked with [HIGH], [IMPORTANT], [PINNED], PRIORITY: HIGH, ❗, or ⚠️ (case-insensitive). All other non-empty lines are treated as normal/low priority and are pruned oldest-first before any high-priority notes are removed.
Parameters
- maxNotes: number
  Maximum number of note lines to retain (must be >= 0)
Returns number
Number of note lines pruned
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:88

RemoveTasks

RemoveTasks(ids: string[]): void
Remove tasks by ID.
Parameters
- ids: string[]
Returns void
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:158

SetNotes

SetNotes(text: string): void
Replace the current notes content.
Parameters
- text: string
Returns void
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:54

ToJSON

ToJSON(): ScratchpadSnapshot
Returns a plain object snapshot for persisting in step InputData/OutputData.

Returns ScratchpadSnapshot
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:249

ToPromptString

ToPromptString(): string
Generates a compact markdown representation for prompt injection. More token-efficient than raw JSON dump.

Returns string
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:260

UpsertTasks

UpsertTasks(tasks: AgentTask[]): void
Add new tasks or update existing ones (matched by id). If a task with the same id exists, it is replaced entirely.
Parameters
- tasks: AgentTask[]
Returns void
- Defined in packages/AI/Agents/src/ScratchpadManager.ts:140

Class ScratchpadManager

Example

Index

Constructors

Methods

Constructors

constructor

Returns ScratchpadManager

Methods

ApplyScratchpadChanges

Parameters

Returns void

Clear

Returns void

EnforceTaskLimit

Parameters

Returns number

GetNoteLines

Returns string[]

GetNotes

Returns string

GetTaskCounts

Returns Record<AgentTaskStatus, number>

GetTasks

Returns AgentTask[]

GetTasksByStatus

Parameters

Returns AgentTask[]

GetTaskSummary

Returns string

HasContent

Returns boolean

PruneNotes

Parameters

Returns number

RemoveTasks

Parameters

Returns void

SetNotes

Parameters

Returns void

ToJSON

Returns ScratchpadSnapshot

ToPromptString

Returns string

UpsertTasks

Parameters

Returns void

Settings

On This Page