[Blog](https://cohesivity.ai/blog)

Architecture

Published Jul 18, 2026·Updated Aug 30, 2026

![](https://cohesivity.ai/authors/arag.webp)![](https://cohesivity.ai/authors/shouryamaan.webp)[Arag](https://www.linkedin.com/in/aragagrawal/) and [Shouryamaan](https://www.linkedin.com/in/shouryamaanjain/)

# How to Build Persistent State for Long-Running AI Agents

[Read as Markdown](https://cohesivity.ai/blog/persistent-state-for-long-running-ai-agents.md)

State

State

Checkpoint

Resume

Persistent agent state is the structured record a fresh worker needs to resume a task without replaying completed work or guessing from chat history. It should identify the current step, completed operations, pending signal, retry state, and next legal transition.

State is different from memory, business data, artifacts, and audit history. Treating all five as a vector-store document makes recovery ambiguous and access control difficult.

## Separate the five kinds of stored information

| Kind           | Question it answers                                    | Typical store                                     |
| -------------- | ------------------------------------------------------ | ------------------------------------------------- |
| Workflow state | Where is this run, and what may happen next?           | Relational row or workflow engine                 |
| Business state | What is true about the order, customer, or deployment? | Authoritative application database or provider    |
| Memory         | What prior context may help a future decision?         | Relational records, search index, or vector store |
| Artifact       | Where is the generated file, report, or code bundle?   | Object storage with metadata                      |
| Audit record   | Who decided and executed what, and when?               | Append-only event or audit table                  |

An invoice status belongs in business state. The fact that the workflow is waiting for finance approval belongs in workflow state. A summary of the customer’s preferences may belong in memory. The PDF belongs in object storage. The approval decision belongs in the audit record.

The broader [agent architecture guide](https://cohesivity.ai/blog/ai-agent-architecture-memory-tools-state-durable-execution) shows how these stores connect to tools and durable execution.

## Store a state machine, not a prose summary

Use explicit states and allowed transitions:

```mermaid
stateDiagram-v2
    [*] --> Created
    Created --> Running
    Running --> WaitingForApproval
    WaitingForApproval --> Running: approved
    WaitingForApproval --> Cancelled: rejected or expired
    Running --> RetryScheduled: retryable failure
    RetryScheduled --> Running
    Running --> Completed
    Running --> Failed

```

A task row can hold `state`, `state_version`, `current_step`, `attempt`, `wake_at`, `approval_id`, and timestamps. Completed side effects should be referenced through operation records rather than embedded as free-form model text.

Define legal transitions in code and reject stale updates. The model may propose a transition, but the state layer should decide whether `waiting_for_approval` can become `completed` without an approval record.

## Make concurrent workers disagree safely

Queues can deliver twice, leases can expire, and a slow worker can finish after another worker resumes the same task. Add optimistic concurrency with a version column, or use a lease with an owner and expiry. A state update should include the version it read and fail if another worker already advanced it.

Keep the lease separate from the workflow state. A crashed worker should lose its lease without changing the task to failed. The next worker can acquire the lease, read persisted state, and resume.

## Checkpoint around effects

Persist intent before a write and verified completion after it. If a timeout leaves the outcome unknown, move to a state such as `reconciling` rather than pretending the step failed.

The [durable execution guide](https://cohesivity.ai/blog/durable-execution-for-ai-agents) covers idempotency and reconciliation in detail. The state store’s job is to retain the operation reference and block an unsafe transition while the outcome is unresolved.

## Persist human waits as first-class records

An approval record should include the exact action, resource, requested scope, requester, approver, expiry, decision, and policy version. When the workflow resumes hours later, recheck that the approval applies to the current parameters and that the represented user still has access.

Do not keep a server process sleeping while it waits. Persist the condition and let a signal or scheduled job enqueue the next transition. [Temporal’s durable execution model](https://docs.temporal.io/encyclopedia/durable-execution) uses event history and signals for this class of wait, but the same design can be built with a database and queue.

## Version state without stranding old runs

Long-running tasks can outlive a deployment. Store a workflow definition version and design migrations for active states. A new worker should know whether it can read an old payload, migrate it, or continue using the old handler.

Avoid placing the entire model context in one unversioned JSON blob. JSON is useful for step-specific payloads, but stable fields used for scheduling, authorization, retention, and operations should be explicit and indexed.

## Give every record a retention rule

Workflow state may be compacted after completion. Audit records may need longer retention. Memory should support correction and deletion. Artifacts need expiry and ownership metadata. Business data follows the product’s own policy.

Deletion must cross references. Removing a user’s memory while leaving the same personal data in prompts, traces, and artifacts is not complete deletion. Store references and classifications so the cleanup path can find each copy.

## Test resume with a blank process

Stop the worker during approval, after a provider call, and during retry backoff. Resume on a process with no local cache or conversation object. It should derive the next action from persisted state and authoritative backend records.

The prompt below performs that inventory before suggesting changes. Any required fact found only in a log line or prompt is a concrete persistence gap.

or send it to[Claude Code](https://claude.ai/new?q=Inspect+this+repository%27s+longest-running+AI+agent+workflow.+Do+not+edit+code+or+call+external+services.+Inventory+its+workflow+state%2C+business+state%2C+long-term+memory%2C+artifacts%2C+and+audit+records.+For+every+field%2C+name+the+authoritative+store%2C+writer%2C+reader%2C+retention+rule%2C+and+concurrency+control.+Simulate+a+fresh+worker+resuming+during+a+human+approval+and+after+a+completed+external+write.+List+facts+that+exist+only+in+prompts%2C+process+memory%2C+or+logs%2C+then+propose+the+smallest+persistence+changes+needed+for+an+unambiguous+resume. "Send to Claude")[Cursor](https://cursor.com/link/prompt?text=Inspect+this+repository%27s+longest-running+AI+agent+workflow.+Do+not+edit+code+or+call+external+services.+Inventory+its+workflow+state%2C+business+state%2C+long-term+memory%2C+artifacts%2C+and+audit+records.+For+every+field%2C+name+the+authoritative+store%2C+writer%2C+reader%2C+retention+rule%2C+and+concurrency+control.+Simulate+a+fresh+worker+resuming+during+a+human+approval+and+after+a+completed+external+write.+List+facts+that+exist+only+in+prompts%2C+process+memory%2C+or+logs%2C+then+propose+the+smallest+persistence+changes+needed+for+an+unambiguous+resume. "Send to Cursor")[Codex](https://chatgpt.com/codex?prompt=Inspect+this+repository%27s+longest-running+AI+agent+workflow.+Do+not+edit+code+or+call+external+services.+Inventory+its+workflow+state%2C+business+state%2C+long-term+memory%2C+artifacts%2C+and+audit+records.+For+every+field%2C+name+the+authoritative+store%2C+writer%2C+reader%2C+retention+rule%2C+and+concurrency+control.+Simulate+a+fresh+worker+resuming+during+a+human+approval+and+after+a+completed+external+write.+List+facts+that+exist+only+in+prompts%2C+process+memory%2C+or+logs%2C+then+propose+the+smallest+persistence+changes+needed+for+an+unambiguous+resume. "Send to Codex")[opencode](https://opencode.ai/?q=Inspect+this+repository%27s+longest-running+AI+agent+workflow.+Do+not+edit+code+or+call+external+services.+Inventory+its+workflow+state%2C+business+state%2C+long-term+memory%2C+artifacts%2C+and+audit+records.+For+every+field%2C+name+the+authoritative+store%2C+writer%2C+reader%2C+retention+rule%2C+and+concurrency+control.+Simulate+a+fresh+worker+resuming+during+a+human+approval+and+after+a+completed+external+write.+List+facts+that+exist+only+in+prompts%2C+process+memory%2C+or+logs%2C+then+propose+the+smallest+persistence+changes+needed+for+an+unambiguous+resume. "Send to OpenCode")