# Sessions

> Resume saved Raw conversations from the terminal or dashboard, list and inspect history, and manage where sessions are stored and how long they are kept.

A session is a saved conversation. Raw stores the history and the context that the model uses. The terminal, the dashboard and ACP clients all read and write the same sessions, so you can start a task in one and continue it in another.

## Resume a session

| Command                                | Result                                                                                         |
| -------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `raw --continue "task"`                | Resumes the most recent unexpired session for the current workspace.                           |
| `raw --resume ID "task"`               | Resumes one session in the working directory it was saved with, and prints that directory.     |
| `raw sessions`                         | Lists sessions in the current workspace, with a cursor for the next page.                      |
| `raw sessions --all`                   | Lists sessions across all workspaces.                                                          |
| `raw sessions show ID`                 | Prints the newest 20 visible items of a session, formatted with your current display settings. |
| `raw sessions show ID --before CURSOR` | Prints an older page.                                                                          |

Running a task with `--continue` or `--resume` loads the current agent, tools, skills, MCP servers, limits and prompt from your config. The session keeps its ID and its committed history.

When a session is resumed with `--config` or `--agent`, the explicit value replaces the saved one for that run, and Raw saves the new selection for the next resume. A session whose saved working directory has been removed, or whose selected config file is missing, reports an error. Pass an explicit `--config` to recover a session whose original config file no longer exists.

With a task, stdout contains only the new answer. Viewing a session with `raw sessions show` needs no model credential and starts no tools.

## Start a new session

Each one-shot task starts a new session unless you pass `--continue` or `--resume`. In the REPL, `/clear` closes the current session and starts a new saved one. The old history remains available.

## Delete a session

```sh
raw sessions delete ID
```

This permanently removes one session that is not currently active. Raw does not export or archive it first. To see storage use, run `raw sessions stats`. It reports the database, write-ahead log and payload sizes, plus the largest sessions.

## Where sessions are stored

Sessions are stored in a database that is private to your operating system account:

- `$XDG_STATE_HOME/raw/sessions.sqlite`, or
- `~/.local/state/raw/sessions.sqlite` when `XDG_STATE_HOME` is not set.

Large payloads, such as big tool outputs, are kept as checksum-verified files beside the database in the same state directory.

If Raw finds an older database format that it cannot read, it leaves that file untouched. New sessions are stored in a separate database under `raw/stores/`, inside the same state root. Raw does not migrate old sessions automatically. A session that exists only in the preserved file is unavailable until that file is handled separately.

## Retention

By default, a session expires seven days after its last committed conversation activity. Reading history, listing sessions and viewing metrics do not extend the period.

To change the period, set `sessions.retention_days` to a positive integer in the canonical global config file, `~/.config/raw/config.json` (or `$XDG_CONFIG_HOME/raw/config.json`):

```json
{
  "sessions": { "retention_days": 14 }
}
```

An alternate file passed with `--config` cannot set this value. The retention policy applies to the shared session store, so Raw rejects a `sessions` block in an alternate config.

When a session expires:

1. It becomes unavailable immediately.
2. Raw permanently deletes its history, its active model context and its payload files during routine cleanup.

Cleanup runs after session commands, and a long-running ACP server checks while idle. A session with live background processes stays available while its owning host runs, even after the cutoff.

> **Expired sessions cannot be recovered:**
>
> Cleanup is permanent. Raw does not export or pin sessions. If you need to keep history beyond the retention period, back up the entire state directory before the cutoff. Include both database files and the payload files beside them. Copy the whole `raw` state directory, not only `sessions.sqlite`.

## Sessions and the dashboard

The dashboard creates and resumes the same sessions as the terminal. Closing a browser tab does not stop a run. If a session is busy in another process, the dashboard can still read it. It becomes runnable there after that process releases the session.

## Tips

- Use `raw --continue` for a quick follow-up in the same project.
- Use `raw sessions` to find an older session by its ID. Copy the ID from the footer or the dashboard’s resume command.
- Keep a session’s workspace and config stable. A change to the agent, model or tools applies on the next resume, while the history stays the same.