Session Persistence

Save, resume, and fork conversations as JSON snapshots.

Storage

Sessions are stored at .aura/sessions/{id}.json. The ID is either a UUID (auto-generated) or a user-chosen name set via /name. Each session contains:

• Conversation history (all messages except ephemeral error feedback)
• Metadata: title, agent, mode, model, provider, thinking level, thinking display state, loaded tools (deferred tools activated via LoadTools), sandbox state, read-before policy, session approvals, stats, cumulative token usage
• Todo list

Commands

Command	Description
/save [title]	Save current session. Preserves existing title on re-save.
/name [name]	Set or show the session name (custom ID). No args shows current ID.
/resume [id]	List sessions or resume by ID prefix match.
/load	Alias for /resume.
/fork [title]	Fork into new session. Auto-titles as “Fork of {original}”.

Auto-Save

Sessions are automatically saved when Aura exits, but only if at least one user message was sent during the session. Starting Aura and immediately quitting does not create an empty session file.

Resume

When resuming a session, Aura restores:

• Agent — switches to the saved agent
• Mode — switches to the saved mode
• Model/Provider — restores the model and provider used at save time
• Thinking — restores thinking level and display state
• Messages — rebuilds conversation and replays it in the TUI
• Todos — restores the todo list
• Loaded tools — re-activates any deferred tools that were loaded via LoadTools
• Sandbox — restores sandbox toggle state
• Read-before policy — restores write/delete enforcement if changed at runtime
• Session approvals — restores in-session tool approval patterns
• Stats — restores session statistics (interactions, tool calls, tokens, etc.)
• Cumulative usage — restores total token usage across the session

The TUI displays the restored conversation filtered for display — user messages, assistant responses, tool calls, DisplayOnly notices, and Bookmark dividers are shown. System messages, raw tool results, and Metadata messages are excluded from the visual replay.

Use /resume without arguments to open the interactive session picker (TUI) or list sessions (Simple/Headless).

CLI Flags

Resume a specific session on startup with --resume:

aura --resume abc123

Accepts the same ID prefix as /resume. Supports AURA_RESUME environment variable.

Resume the most recently updated session with --continue (-c):

aura --continue
aura -c

Equivalent to --resume <id> where <id> is the session with the latest UpdatedAt. Cannot be combined with --resume.

Named Sessions

By default, sessions get a UUID as their ID. Use /name to assign a human-friendly name:

> /name weekly-review
Session named: weekly-review

> /save
Saved session: weekly-review (Weekly Code Review)

> /resume weekly
Resumed session: weekly-review (Weekly Code Review)

• /name weekly review (multiple words) → weekly-review (joined with dashes)
• Names must be unique — error if another session already has that name
• Works before or after saving — set the name first, then /save, or rename an already-saved session
• /resume prefix matching works identically for UUIDs and custom names

Title Generation

Session titles are automatically generated using a dedicated Title agent when saving. Configure in .aura/config/features/title.yaml:

• disabled: true — skip LLM generation, use first user message instead
• agent: "Title" — dedicated agent for title generation
• prompt: "" — named prompt for self-title (overrides agent — uses current model)
• max_length: 50 — maximum character length

Title uses the same ResolveAgent() framework as Compaction and Thinking. If neither agent nor prompt is set, falls back to the first user message.

Forking

/fork creates a new session as a copy of the current one. The new session gets a fresh UUID and the title defaults to “Fork of {original title}”. Both sessions are independent after forking. Use /name afterward to assign a custom name to the fork.