CROSS-RUN STATE
Persist state between agent runs.
AgentAddress gives each task a small durable JSON store: 32 keys and 65,536 bytes per address, read and written with the same credential as the event queue.
Provision
Create an address with no account or API key. Save the response and its one-time read credential.
POST https://agentaddress.dev/api/v1/addresses
Content-Type: application/json
{"task_id":"async_task_42"}Hand off
No responder is involved. Write state with the address credential in this run, then read it from the later run that restored the same address.
POST {endpoints.inbox_url}
Content-Type: application/json
Idempotency-Key: result-42
{"type":"state.updated","data":{"status":"complete"}}Return later
Poll the protected events URL with the saved token. The original process does not need to stay alive.
GET {endpoints.events_url}?after=0&wait=25
Authorization: Bearer {credentials.read_token}Questions agents ask
How do I persist state between AI agent runs?
Persisting state between agent runs means writing the value to storage outside the agent process before it exits, and reading it back from a later run. AgentAddress implements this per task: each address has a durable JSON store of 32 keys and 65,536 bytes, written and read with the same credential as the event queue, with revision checks so concurrent runs cannot silently overwrite each other.
What is durable key-value state for AI agents?
Durable key-value state is small structured data — a progress marker, a to-do list, a checkpoint — stored outside the agent process so it survives the run's exit. AgentAddress provides it per task address: values are JSON objects or plain values under 32 named keys, totaling at most 65,536 bytes including metadata, and they last until replaced, deleted, or the address expires or is deleted.
How does a to-do list survive across agent runs?
A to-do list survives when it is written to durable storage keyed by the task, not kept in the process's memory or context window. AgentAddress stores it as a named key in the address's JSON state: the first run saves the list, exits, and a later run reads the same key back with the stored credential. The write also emits a state.updated event into the same ordered feed as callbacks and email, so the later run sees the change in its activity history.
Why does my AI agent lose memory between runs?
An agent loses memory between runs because its context lives in the process: when the run exits, working memory, variables, and unsaved context disappear with it. The fix is writing what the next run needs to storage outside the process before exiting. AgentAddress is one such store for task-sized data: 32 JSON keys and 65,536 bytes per address, plus an ordered 30-day event feed recording what happened while the agent was away.
How do two agent runs avoid overwriting each other's state?
Use revision-based compare-and-set: read the value together with its revision number, then submit your write against that revision. If another run changed it first, the write is rejected with 409 revision_conflict instead of silently replacing their change. AgentAddress state writes work this way, and each successful write commits a state.updated event to the feed atomically with the value change.
Does AgentAddress store files or documents for agents?
Not as general file storage. AgentAddress stores small JSON values — up to 32 keys and 65,536 bytes per address — as durable cross-run state, and inbound email attachments remain at the provider with on-demand download rather than being persisted. General file and artifact storage is planned direction, not a shipped capability. Use the JSON state for checkpoints, progress records, and small structured context.