Persistent Agents Need a Workspace, Not a Bigger Prompt

Vercel Drives just reached general availability: persistent storage that survives individual Sandbox runtimes, with drives that default to 1 TiB and can be configured up to 16 TiB. That release is a good excuse to fix the mistake I see in almost every long running agent I review. Teams treat a persistent agent workspace, sandbox memory and chat history as one thing, then wonder why the agent forgets its own files halfway through a job.

TL;DR

• Agents juggle three kinds of state: conversation memory, workflow checkpoints, and files. Each one has its own lifecycle, and mixing them up is where long tasks break.
• A bigger prompt does not make an agent persistent. A workspace that outlives the runtime does, and that is the gap storage like Vercel Drives fills.
• Give each kind of state its own home, write a small manifest that ties them together, and make resume the default path instead of the exception.

If you want the wider map of agent memory types first, I wrote up the four kinds of AI agent memory every architect should know. This post is narrower: what has to survive when the sandbox goes away.

Three kinds of state agents confuse

Here is the split I use on every agent project.

Conversation memory is what the model has been told. The OpenAI Agents SDK keeps session history outside a single model call, which is great, but its in process MemorySession resets when the process exits. That is fine for a chat. It is a footgun for a job that runs for an hour.

Workflow checkpoints are where the agent is in its plan. LangGraph handles this with a checkpointer plus a thread identifier, so a workflow can resume after an interruption, even long after the original process ended.

Files are what the agent has actually produced: the cloned repo, the generated report, the half finished dataset. Neither of the first two stores holds them, because neither was built to.

The bug pattern is always the same. Someone stuffs file contents into the conversation so the agent "remembers" them. The prompt grows, the context fills up, and the next run starts from a fresh sandbox with none of the files on disk anyway.

What survives a run

Ask one question about every piece of state: what happens to it when the runtime dies?

The row that bites people is the fourth one. The agent wrote real work to disk, the checkpoint says "step 7 of 9 done", and the resumed run finds an empty directory. The checkpoint is now lying.

Why files and memory are different

Memory is about meaning. Files are about bytes. You summarise memory, trim it, and pick what goes back into the prompt. You never summarise a git repo or a parquet file; you either have it or you do not.

That difference changes how you design for persistent agent workspace sandbox memory architecture. Memory gets a budget and a retrieval strategy. Files get a path, a size limit and an owner. With drives that can grow up to 16 TiB, the size limit is rarely what stops you. Knowing which run wrote what is.

The cheapest fix I know is a manifest: one small JSON file on the persistent drive that records what each step produced. The checkpoint points at the manifest, and the manifest points at the files. Here is a version you can run with plain Node:

import { mkdir, readFile, writeFile, stat } from "node:fs/promises";
import { join } from "node:path";

type StepRecord = { step: string; files: string[]; finishedAt: string };
type Manifest = { threadId: string; steps: StepRecord[] };

const WORKSPACE = process.env.AGENT_WORKSPACE ?? "./workspace";

async function loadManifest(threadId: string): Promise<Manifest> {
  try {
    const raw = await readFile(join(WORKSPACE, threadId, "manifest.json"), "utf8");
    return JSON.parse(raw) as Manifest;
  } catch {
    return { threadId, steps: [] };
  }
}

async function recordStep(m: Manifest, step: string, files: string[]) {
  for (const f of files) await stat(join(WORKSPACE, m.threadId, f)); // throws if a file is missing
  m.steps.push({ step, files, finishedAt: new Date().toISOString() });
  await mkdir(join(WORKSPACE, m.threadId), { recursive: true });
  await writeFile(join(WORKSPACE, m.threadId, "manifest.json"), JSON.stringify(m, null, 2));
}

export async function nextStep(threadId: string, plan: string[]) {
  const m = await loadManifest(threadId);
  const done = new Set(m.steps.map((s) => s.step));
  return { manifest: m, next: plan.find((s) => !done.has(s)) ?? null };
}

Point AGENT_WORKSPACE at the mounted persistent drive and the same code works on your laptop and in a fresh sandbox. The stat check is the important bit. A step only counts as done when its files really exist, so a checkpoint can never claim work the disk does not have.

A persistence architecture for long tasks

Put the three stores together and you get an architecture that survives a dead sandbox without a bigger prompt.

The rules I follow:

1. One thread id, everywhere. The checkpoint key, the manifest folder and the session id share the same id. Debugging a stuck run should start with one string.
2. Files on the drive, never in the prompt. The prompt gets a short listing of what exists and where. The agent reads a file when it needs it.
3. Workers get their own folders. When the agent forks parallel workers, each one writes under its own path on the shared drive. The coordinator merges at the end. No two workers ever write the same file.
4. Resume is the default. Every run starts by loading the manifest and asking for the next unfinished step. A fresh job is just a manifest with no steps.

Which framework you pick for the checkpoint layer matters less than following those rules, but it is still a real decision. The AI agent framework chooser walks through the tradeoffs if you are still deciding between a graph runtime and a lighter SDK.

Persistent agent workspace sandbox memory checklist for production

Before you ship a long running agent, check these:

• [ ] Conversation memory is persisted to a session store, not only kept in process
• [ ] Workflow state uses a checkpointer keyed by a thread id
• [ ] Files live on storage that outlives the sandbox (a persistent drive, not the ephemeral disk)
• [ ] A manifest records which step produced which files, and verifies they exist
• [ ] Parallel workers write to separate folders
• [ ] A killed run resumes at the next unfinished step without a human

My own rule of thumb after a few painful rewrites: if I cannot kill the sandbox in the middle of a job and watch the next run pick up cleanly, the agent is not production ready, no matter how good its answers look.

FAQ

What changed in persistent agent workspace sandbox memory?

Vercel Drives reached general availability as persistent storage that survives individual Sandbox runtimes, with drives that default to 1 TiB and can be configured up to 16 TiB. That gives agents a place for files that outlives the runtime, which conversation memory and workflow checkpoints were never designed to hold.

How should teams adopt persistent agent workspace sandbox memory?

Split agent state into three stores: a persisted session for conversation memory, a checkpointer keyed by a thread id for workflow state, and a persistent drive for files. Tie them together with a small manifest per thread, give parallel workers separate folders, and make every run start by resuming from the manifest.

Related reading: why your AI agent forgets: context engineering patterns that hold up and why 40% of AI agent projects get killed, and the ones that survive.

If you are deciding whether a long running agent is worth building at all, the AI agent ROI calculator is a quick way to sanity check the numbers before you invest in the plumbing.

Drop a comment if your setup looks different. Curious how people are splitting memory and files in production.