Data and retention¶

Agents keeps plain files, not a database. Most stores have a bound: a time, a count or a size. A conversation has none: it is kept until its agent is deleted. This page lists the stores, then says what a backup holds and what it does not.

On each machine¶

A machine's data folder is ~/Library/Application Support/Agents on a Mac and ~/.local/share/Agents on Linux (~/.agents-server/root on a server installed by its join command). Only its user can read it (mode 0700).

On the control plane¶

The control plane's store is a folder or an S3-compatible bucket. It holds no conversations. The one exception is a prompt sent to a stopped workspace: it waits in the store until that machine starts.

On the hosted service, an account keeps its GitHub user id, its GitHub login and the date it signed up. Delete Account stops its control plane and deletes everything under that account, then the account. It does not delete the account's machines.

Erasure¶

Delete works on an archived agent. It stops the agent's runtime, takes back its tokens, and deletes its folder (record, conversation, tool log) and its turn summaries. Then (T8, #1001):

• The runtime's own copy goes. The machine starts the runtime as the agent ran (with its account) and asks it to delete the conversation (ACP session/delete). For Claude and Codex it also removes the session's files in the runtime's folder (~/.claude or CLAUDE_CONFIG_DIR; ~/.codex or CODEX_HOME). This waits in erasures.json in the data folder: 1,000 at most, done one at a time, and tried again at the next start when the runtime does not answer, 3 times at most within 7 days.
• A restore never brings the agent back. erased.json in the data folder names every agent the machine deleted: 10,000 at most, each for 400 days. A backup carries it, and a restore skips each agent in it, also on a new machine.

These stay behind:

• the copy of a runtime whose files are not known and that cannot delete a conversation;
• attachments, until the next sweep finds no conversation that names them;
• the agent's events, until they are 7 days old;
• the backups that hold it, until they age out (a restore skips it).

Export and import¶

Export… in an agent's menu, and Export Agents… in a folder's, on the Mac, the Remote and the web page, give a .tar.gz of the agent, or of every agent of the folder (T8, #1001). It is in the backup format: each agent's record, conversation, turn summaries and tool log. It holds no secret, no usage history and no other agent.

Import Agents… in a folder's menu sends the file to that folder's machine. Its agents come back archived, to read and search. They are never run there, and bring no MCP servers. An agent that the machine has already, or that it deleted (erased.json), is skipped.

The machine makes an export in its Outgoing folder and an import arrives in Incoming. Each goes once it is read or imported, or after an hour untouched.

Backups¶

See Back up and restore a machine.

• A machine backs up every day by default, and keeps the newest 3 (1 to 10). A backup holds each agent's record, conversation, turn summaries and tool log, and the usage and time history. It holds no sign-in, key or secret.
• A Mac backs up to a folder, backups in its own data folder by default. That is the same disk: it undoes a mistake, but does not survive the loss of the Mac. Choose a second disk or a synced folder. Local backups are not encrypted.
• A server backs up to the control plane's store, sealed. The copy on the server is deleted once it is sent.
• Restore brings agents back archived, to read and search. An agent from another machine is shown, never run.

What is not backed up today¶

The first HADR review (2026-10-21, #1557) found these. Each one is an open issue.

• The control plane in the cloud is one VM with one disk, with no snapshot and no copy (#2136). Losing that disk makes every device and machine pair again, and loses every server backup in its store.
• A copy of the store does not restore a control plane on its own (#2137). A restore also needs the control key, the secrets-key and the TLS certificate from the old home. With all of them, a machine joined again in 26 seconds in the review's drill.
• Machine providers' secrets are outside the store (#2138). A copy of the store does not carry them.
• A machine's backups are on its own disk by default (#2139).
• Not in a machine's backup: settings, workflows, secrets, attachments, events and the runtimes' own session files. A folder's .agents/ folder is in the folder, and so in its git repository if you commit it.
• Writes that are not synced. Appends to a machine's events, its records' logs and its turn summaries are not synced to disk one by one, so a power cut can lose the last lines.

Related¶

• Data flow
• Security overview
• Back up and restore a machine
• The ~/.agents folder