Skip to main content

Persistence

Every agent has durable state (files, settings, run history) and disposable state (the container itself). Knowing where the line falls saves you from workflows that quietly depend on things that can vanish.

Containers are disposable​

Each agent runs in its own Docker container — a real Linux environment with a shell and common developer tools. But the container can be recreated at any time: after idle periods, during platform deployments, or when settings change. When that happens, the agent gets a fresh filesystem, fresh process space, fresh home directory.

So never treat the container as permanent. Anything worth keeping must live on a persistent volume.

(Containers are also created lazily — a new agent gets one on its first run, not at creation time.)

What persists​

  • /workspace — the agent's private volume and its working directory for every run. Only this agent can see it. This is where memory, continuity logs, and project files live.
  • /shared — a volume mounted into every container in the same agent tree, root to leaves. Think of it as the team's shared drive: repos several agents work on, files one agent produces and another consumes, the shared knowledge base.
  • Agent settings — name, prompt, model, tools, schedule, hierarchy. Stored server-side, independent of any container.
  • Run history — messages, tool calls, and usage, stored server-side until you delete the run or the agent.

What resets​

Everything outside /workspace and /shared lives on the disposable container filesystem:

WhatHow to handle it
System packages (apt-get install)Reinstall in .shell-init.sh
/root contents — dotfiles, SSH configSymlink from /workspace or recreate in .shell-init.sh
Environment variablesSet in .shell-init.sh
Globally installed tools (npm -g, pip install)Reinstall in .shell-init.sh
Running processes and background jobsDon't depend on them surviving
/tmpUse /workspace for anything you want to keep

The base image already includes common developer tools, so most agents only need .shell-init.sh for extras and credentials.

The files that matter​

/workspace/MEMORY.md​

The agent's long-term memory. The top of this file is injected into the agent's context at the start of every run — this is how it remembers who it is and what it's working on, across runs and compactions.

The injection has a size limit (roughly the first 16 KB, depending on the model), so the convention is: important things at the top, details in separate files that MEMORY.md points to. If an agent seems to be acting on stale context, you can edit MEMORY.md yourself in the Editor tab — it's one of the most direct steering mechanisms you have.

/workspace/.shell-init.sh​

Sourced at the start of every shell session. This is where environment variables, API keys, symlinks, and package reinstalls go, so they come back automatically after every container recreation:

# /workspace/.shell-init.sh — example
export GH_TOKEN="ghp_xxxx"
ln -sf /workspace/.ssh /root/.ssh
which jq > /dev/null 2>&1 || apt-get install -y jq > /dev/null 2>&1

The script lives in /workspace, so it persists; its output is logged to /workspace/.shell-init.log for debugging.

/workspace/continuity/​

Episodic logs — agents note what happened in each run, in monthly files. Unlike MEMORY.md this is not auto-injected; agents read it when they need to reconstruct what past runs did, especially after compaction has discarded old conversation history.

/workspace/kb/ and /shared/kb/​

Knowledge bases: reference material and learned patterns. /workspace/kb/ is for facts only this agent needs; /shared/kb/ is for the whole tree.

Further reading​