Execution Memory

Agent task state management with checkpoint, pause, and resume capabilities. Enables long-running agent workflows that survive restarts and interruptions.

What Is Execution Memory?

Execution memory tracks the state of agent tasks as they run. Each task has an identifier, a status (running, paused, completed, failed), and checkpoint data that captures the exact point of progress. When an agent restarts or an error occurs, execution memory allows the task to resume from the last checkpoint rather than starting over.

This is essential for long-running agent workflows: data processing pipelines, multi-step research tasks, complex code refactoring, or any task that may take minutes to hours and should not lose progress on failure.

When to Use

  • •Long-running agent tasks that should survive restarts
  • •Multi-step workflows where progress must be preserved
  • •Tasks that require human approval at certain checkpoints
  • •Parallel agent coordination where tasks depend on each other
  • •Any workflow where "start from scratch" is expensive or undesirable

Quick Example

Create and manage an execution task
import Rekall from '@rekall/sdk';


const rekall = new Rekall({ apiKey: 'rk_your_api_key' });


// Start a new task
const task = await rekall.execution.create({
  taskId: 'refactor-auth-module',
  state: {
    phase: 'analysis',
    filesProcessed: 0,
    totalFiles: 42,
  },
  status: 'running',
});


// Update checkpoint as work progresses
await rekall.execution.checkpoint({
  taskId: 'refactor-auth-module',
  checkpointData: {
    phase: 'refactoring',
    filesProcessed: 15,
    totalFiles: 42,
    lastFile: 'src/auth/middleware.ts',
  },
});


// Complete the task
await rekall.execution.complete({
  taskId: 'refactor-auth-module',
  result: {
    filesModified: 42,
    testsUpdated: 18,
    summary: 'Auth module refactored to use new token validation',
  },
});

Fields Reference

FieldTypeRequiredDescription
task_idstringYesUnique identifier for the task. Use descriptive names.
stateobjectYesCurrent task state. Arbitrary JSON describing progress and context.
checkpoint_dataobjectNoSnapshot of state at a specific point. Used for resume-from-checkpoint.
statusenumYesOne of: running, paused, completed, failed.

Advanced Usage

Checkpointing

Checkpoints capture a snapshot of task state at a specific point. If the task fails or the agent restarts, you can resume from the last checkpoint. Rekall maintains a history of checkpoints for each task.

Resume from checkpoint
// Check if a task has an existing checkpoint
const existing = await rekall.execution.get('refactor-auth-module');


if (existing && existing.status === 'running') {
  // Resume from last checkpoint
  const checkpoint = existing.checkpointData;
  console.log('Resuming from:', checkpoint.lastFile);
  console.log('Progress:', checkpoint.filesProcessed, '/', checkpoint.totalFiles);


  // Continue processing from where we left off
  await processFiles(checkpoint.lastFile, checkpoint.filesProcessed);
} else {
  // Start fresh
  await rekall.execution.create({ taskId: 'refactor-auth-module', ... });
}


// List checkpoint history
const history = await rekall.execution.listCheckpoints('refactor-auth-module');
for (const cp of history) {
  console.log(cp.timestamp, cp.data.filesProcessed);
}

Pause & Resume

Tasks can be explicitly paused -- for human approval, external dependency completion, rate limiting, scheduled waits, or when the agent needs to yield resources. Rekall supports typed pause reasons ( human_approval, human_input, external_dependency, scheduled_wait, rate_limit, checkpoint) so dashboards and automations can differentiate between pause types. The paused state is persisted and the task can be resumed at any time.

Pause and resume a task
// Pause a task (e.g., waiting for approval)
await rekall.execution.pause({
  taskId: 'refactor-auth-module',
  reason: 'Waiting for code review approval',
  checkpointData: {
    phase: 'review',
    filesProcessed: 42,
    prUrl: 'https://github.com/acme/app/pull/123',
  },
});


// Later: resume the task
await rekall.execution.resume({
  taskId: 'refactor-auth-module',
  state: {
    phase: 'applying-feedback',
    reviewApproved: true,
  },
});


// Mark as failed with error details
await rekall.execution.fail({
  taskId: 'refactor-auth-module',
  error: {
    message: 'Test suite failed after refactoring',
    failedTests: ['auth.test.ts:42', 'middleware.test.ts:18'],
  },
});

Use Cases

Code Refactoring

Large refactoring tasks that touch dozens of files. Checkpoint after each file so the agent can resume if interrupted. Track which files have been processed.

Data Processing Pipelines

Processing large datasets in batches. Checkpoint after each batch to avoid reprocessing on failure. Track total items processed and remaining.

Human-in-the-Loop Workflows

Tasks that pause for human approval. The agent does initial work, pauses for review, then resumes with the approved direction.

Waiting for External Processes

Agents that trigger CI/CD builds, deployments, third-party API jobs, or approval workflows in other systems. The agent pauses with an external_dependency reason, records what it's waiting for, and resumes when the external process completes -- either via polling or a webhook callback. See the Execution State guide for full examples.

Multi-Agent Coordination

Multiple agents working on related tasks. One agent can check the execution state of another's task before proceeding with dependent work.

Best Practices

Checkpoint frequently

Checkpoint at every meaningful progress point. The cost of saving a checkpoint is negligible compared to the cost of restarting a long-running task from scratch.

  • 1.Use descriptive task IDs. IDs like "refactor-auth-module" are clearer than "task-1". Include enough context to identify the task later.
  • 2.Design for resumability. Structure checkpoint data so the task can resume without any additional context. Include everything needed to continue.
  • 3.Always check for existing tasks. Before starting a new task, check if one with the same ID already exists. Resume if running/paused.
  • 4.Clean up completed tasks. Archive or delete completed/failed tasks after extracting results to keep the execution memory lean.
  • 5.Pair with procedural memory. Define the workflow steps in procedural memory and track execution progress here.
Rekall
rekall