Sessions & Resuming

Conversations are saved as you go and can be picked up later. A resumed conversation reads as one that never stopped, and costs the prompt cache nothing.

Where they are saved

~/.oasis/sessions/

History is written after every clean turn. A failed turn leaves the last known-good file intact, so a poisoned context cannot be reloaded on the next run.

Interactive and one-shot runs save by default. Disable it per run:

oasis-agent --no-session -p "…"

Listing saved conversations

# All of them, most recent first
oasis-agent sessions

# Only conversations started in this directory
oasis-agent sessions --here

# How many to print (default 20)
oasis-agent sessions --limit 50

sessions is a subcommand rather than a flag for a reason: choosing which conversation to resume has to work on a binary that has never been pointed at a server. It needs no --base-url.

Resuming

# Pick from a list
oasis-agent -r

# Resume a specific one: a unique prefix of the id is enough
oasis-agent --resume 20260813-084212-a3f1

Context	Bare -r does
On a terminal	Shows a picker
No terminal: a one-shot -p run, or a pipe	Takes the most recent conversation from this working directory

From inside the REPL, /agents (or /resume) lists conversations and background agents together, and ↵ switches to one in place without leaving your session.

What a resume restores

A resumed session replays the transcript through the same renderers a live turn uses, so:

• Collapsed tool results stay expandable
• Diffs still render as diffs
• The cost meter continues from where it was

The assembled system prefix is byte-identical between a fresh run and a resumed one, so resuming costs the prompt cache nothing. The model server reuses its cached prefill.

Waiting conversations

A conversation that stopped to ask a question is marked as waiting. The marker clears itself when the next turn completes, so the list stays honest without anyone maintaining it.

Background agents in this state show as blocked. See Background Agents & Jobs.

Session ids

An id looks like 20260813-084212-a3f1: date, time, and a short random suffix. Any unique prefix works wherever an id is accepted.

Sessions and updates

An update installs a new version directory and repoints the launcher. It never modifies a file a running process has open.

	Effect of an update
A conversation running now	Finishes on the version it started on
A background agent mid-flight	Never interrupted
The next conversation you start	Picks up the new version
A conversation you resume afterwards	Runs on the new version

Over the control protocol

Sessions are addressable programmatically. session.list, session.resume is not a method; use session.create with a prior session id, or session.list then session.attach. See the OCP Method Reference.

Cleaning up

Session files are plain JSON under ~/.oasis/sessions. Delete them directly when you no longer want them; nothing else references them.

For runs that should never be recorded in the first place (anything scheduled, or anything touching material you would rather not have on disk) use --no-session.