Tonbo Artifacts
Book a demo

Persist agent memory across runs

Give an agent in a disposable sandbox a memory that survives: mount at boot, a directory contract the agent follows, and notes the next run can trust.

An agent that boots in a fresh sandbox starts from zero: yesterday's research, half-finished work, and lessons learned died with yesterday's VM. This guide wires a workspace in as the agent's memory, so each run picks up where the last one stopped.

When you need this

  • Your agent runs in throwaway sandboxes (Daytona, Modal, Firecracker, CI jobs) and re-learns the same things every run.
  • You copy results out of the sandbox by hand, or lose them when it exits.
  • Several runs collaborate on one long task over days.

Skip this guide if your agent runs on one durable machine; a local directory already persists there.

1. Mount at sandbox boot

Install the CLI in the sandbox image once (see Install), then mount in the boot script:

artifacts mount my-workspace /mnt/work

Authenticate with an API key if the sandbox is your own infrastructure (TONBO_API_KEY, see API keys). If the sandbox runs code you don't fully trust, inject a short-lived mount ticket instead of any account credential: see Temporary mount credentials.

2. Give the agent a memory contract

Agents follow instruction files. Point yours at the mount:

## Memory

Your memory lives at /mnt/work/memory and survives this sandbox.
- Read memory/summary.md before starting.
- Append what you learned to memory/runs/<run-id>.md before finishing.
- Working files go in /mnt/work/scratch; final results in /mnt/work/outputs.

Nothing else changes. The agent reads and writes plain files; it doesn't need to know the directory is remote.

3. Write notes the next run can trust

Two habits keep memory clean when runs overlap or die mid-write:

  • One file per run. memory/runs/2026-06-10-a.md never collides with another run's notes, even if two sandboxes run at once.
  • Publish summaries by rename. Rewrite the rolling summary to a hidden file, then mv /mnt/work/memory/.tmp.summary.md /mnt/work/memory/summary.md. A run that boots mid-update sees the old summary or the new one, never half. (Concurrent writes explains why this is safe.)

4. Watch it work

Run the agent, destroy the sandbox, boot a new one:

ls /mnt/work/memory/runs/
# 2026-06-09-a.md  2026-06-10-a.md   — the new run reads what the old runs left