Execution History & Compaction

Relevant source files

The following files were used as context for generating this wiki page:

• packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts
• packages/@n8n/ai-workflow-builder.ee/src/utils/context-builders.ts
• packages/cli/src/modules/mcp/tools/get-execution.tool.ts
• packages/@n8n/instance-ai/evaluations/system-prompts/mock-execution-verify.ts
• packages/cli/src/modules/agents/builder/agents-builder-prompts.ts

Execution History & Compaction manages the lifecycle of workflow and agent execution data. This system records how nodes process data, handles errors during runtime, and compresses historical context to maintain performance during multi-turn AI interactions. It ensures that large volumes of execution data remain accessible for debugging while preventing context overflow in AI-driven builder sessions.

Execution Data Structure

The system captures detailed traces for every node in a workflow. Each execution record includes metadata, status information, and a per-node execution trace.

Core Components of Execution Data

• Run Data: Maps node names to their specific execution tasks. Each task records start times, execution duration, and the data processed on the main or AI-specific ports.
• Execution Schema: Defines the shape of the data processed by each node, allowing the system to understand data structures without loading full payloads.
• Status & Errors: Tracks if an execution succeeded, failed, or was stopped due to issues like identical pagination results.

Sources: packages/@n8n/ai-workflow-builder.ee/src/utils/test/context-builders.test.ts:32-70, packages/@n8n/instance-ai/evaluations/system-prompts/mock-execution-verify.ts:1-50

Execution Data Model

Field	Type	Description
id	string	Unique identifier for the execution.
workflowId	string	ID of the workflow that generated the execution.
status	string	Current state (e.g., success, error, waiting, crashed).
runData	Record<string, ITaskData[]>	Per-node execution details including input/output items.
executionSchema	NodeExecutionSchema[]	Type definitions and data shapes for processed items.
redactionInfo	Object	Details on whether data was hidden due to security policies.

Sources: packages/cli/src/modules/mcp/tests/get-execution.tool.test.ts:75-120, packages/@n8n/ai-workflow-builder.ee/src/utils/test/context-builders.test.ts:16-25

Execution Data Flow

The following diagram illustrates how execution data moves from a running workflow into the persistence layer and AI context.

The diagram shows the lifecycle of execution data from the initial trigger to its use in external AI interfaces and persistence modules.
Sources: packages/@n8n/ai-workflow-builder.ee/src/utils/test/context-builders.test.ts:100-150, packages/cli/src/modules/mcp/tests/get-execution.tool.test.ts:50-100

Context Compaction

Context compaction is the process of summarizing older conversation turns and execution results to fit within the limited context window of Large Language Models (LLMs). This is critical for the "Code Builder" and "Agent Builder" modules.

Compaction Logic

When a conversation grows too large, the system performs the following actions:

1. Summary Generation: Creates a previousSummary of older conversations.
2. Schema Extraction: Keeps the executionSchema but may redact or truncate the actual item values to save tokens.
3. Redaction: Applies valuesExcluded flags when sensitive data is removed during the compaction process.
4. Action Logging: Summarizes discovery and builder phases (e.g., "Found 3 node types") rather than keeping the raw tool outputs.

Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:738-755, packages/@n8n/ai-workflow-builder.ee/src/utils/test/context-builders.test.ts:220-250

Redaction & Security

Execution data often contains sensitive information. The ExecutionRedactionServiceProxy manages the visibility of these fields.

• Redaction Policy: The system checks a workflow_redaction_policy to decide if specific fields (like secret) should be removed.
• Hiding Data: When data is redacted, a redaction object is added to the JSON item indicating the reason.
• MCP Integration: MCP tools like get_workflow_execution automatically process executions through the redaction proxy before returning data to external clients.

Sources: packages/cli/src/modules/mcp/tests/get-execution.tool.test.ts:508-570, packages/cli/src/modules/mcp/tests/get-execution.tool.test.ts:580-620

Multi-Turn History Management

The AI builder agents utilize a HistoryContext to track multi-turn refinement. This context combines compacted summaries with raw messages for the most recent turns.

This sequence shows how the system maintains context for the Agent while summarizing older interactions to prevent token limit breaches.
Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:738-750, packages/@n8n/ai-workflow-builder.ee/src/utils/test/context-builders.test.ts:310-340

Error Diagnosis in History

Historical execution data is specifically formatted for AI diagnosis. The SimplifiedExecutionContext provides targeted blocks for the AI to identify:

• Nodes with Empty Output: Nodes that executed but produced zero items, often breaking downstream logic.
• Nodes Not Executed: Active nodes that were never reached due to upstream filters or errors.
• Incomplete Execution: Cases where a workflow stopped unexpectedly before reaching a final action node.

Sources: packages/@n8n/ai-workflow-builder.ee/src/utils/test/context-builders.test.ts:100-145, packages/@n8n/instance-ai/evaluations/system-prompts/mock-execution-verify.ts:60-90

Conclusion

Execution History & Compaction provides a robust framework for recording and analyzing workflow behavior. By combining detailed runtime traces with intelligent context compaction and strict redaction policies, the system enables powerful AI-driven building and debugging experiences while maintaining system performance and data security.