> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Resume a Session
> Continue a previous conversation with full model/agent/history restored
Resume a previous conversation exactly where you left off โ [same model](#model-restoration), same agent, same chat history.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Session Resume Flow"
ID[๐ Session ID] --> PS[๐ Project Store]
PS -->|found| RS[โ
Restored State]
PS -->|not found| GS[๐ Global Store]
GS --> RS
RS --> CP[โถ๏ธ Continue]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef store fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class ID input
class PS,GS store
class RS,CP output
```
## Quick Start
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai session list
```
Copy the session ID from the output table.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai session resume
```
The CLI restores your prior model, agent name, full chat history, and cumulative usage totals, then shows:
```
โญโ Session Resumed โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Session: my-assistant โ
โ Model: anthropic/claude-3-5-sonnet-latest โ
โ Messages restored: 12 โ
โ Usage: 12,440 tokens ยท $0.0710 (3 requests) โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
--- Restored Conversation ---
[user] What is the capital of France?
[assistant] Paris.
```
The `Usage` line appears only when token/cost data has been accumulated for the session. Cumulative totals keep accumulating from this point โ they do not reset.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai session resume "What about Germany?"
```
Passes the resumed state directly into the same run path as `praisonai run --session`.
Rename the session so it's easy to spot in `session list` โ the id you resume with never changes:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai session rename "fix-auth-bug"
```
The title then surfaces in the `Name` column of `session list`. See [Session Rename](/docs/features/session-rename) for details.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai session resume --transcript
```
Prints recent events without restoring state โ useful for reviewing a session without continuing it.
## Resume into the interactive TUI
The same `resume` primitive is available on the bare `praisonai` interactive launch โ no need to type `/continue` inside a cold TUI:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Most recent session
praisonai -c
# Specific session id (equivalent to praisonai session resume without a follow-up prompt)
praisonai --session
# Fork non-destructively
praisonai --fork --session
```
The recorded session model is restored, the prior transcript is replayed into scrollback, and the primary agent is wired to the resumed session's store so your next prompt continues the conversation with full memory of prior turns.
Added in PR [#4912](https://github.com/MervinPraison/PraisonAI/pull/4912) as parity with `run --continue` / `chat --continue`. See [Interactive TUI โ Launching with a resumed session](/docs/cli/interactive-tui#launching-with-a-resumed-session).
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant CLI
participant ProjStore as Project Store
participant GlobalStore as Global Store
participant Session as RehydratedSession
participant Run
User->>CLI: session resume
CLI->>ProjStore: session_exists(id)?
alt found in project store
ProjStore-->>CLI: session data
else not found
CLI->>GlobalStore: session_exists(id)?
GlobalStore-->>CLI: session data
end
CLI->>Session: build RehydratedSession
Session-->>CLI: chat_history, model, agent_name
CLI-->>User: show "Session Resumed" panel
opt prompt supplied
CLI->>Run: _run_prompt(prompt, model, session)
end
```
The `rehydrate_session()` helper searches stores in order and returns a `RehydratedSession` dataclass:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from dataclasses import dataclass, field
from typing import Optional
@dataclass
class RehydratedSession:
session_id: str
chat_history: list[dict[str, str]] = field(default_factory=list)
model: Optional[str] = None
agent_name: Optional[str] = None
metadata: dict = field(default_factory=dict)
usage: dict = field(default_factory=dict) # cumulative token/cost totals
found: bool = False
```
When `found` is `False`, the CLI prints:
```
Error: Session not found:
โ Use 'praisonai session list' to see available sessions
```
***
## Model Restoration
Resuming restores the model the session was running with โ not the current default. Change your default model between runs and a resumed session still runs on the original model.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q{--model passed?} -->|Yes| M[Use --model
update recorded]
Q -->|No| C{Config has agent.model?}
C -->|Yes| CM[Use config model]
C -->|No| R{Session has recorded model?}
R -->|Yes| RM[Restore recorded model]
R -->|No| D[Fall through to default]
classDef pick fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef ans fill:#10B981,stroke:#7C90A0,color:#fff
classDef fall fill:#6366F1,stroke:#7C90A0,color:#fff
class Q,C,R pick
class M,CM,RM ans
class D fall
```
When the recorded model is used, the CLI prints:
```
Restored session model: anthropic/claude-3-5-sonnet-latest
```
**Precedence** (first match wins): explicit `--model` โ config `agent.model` โ **recorded session model** โ keyless local-first fallback โ default resolution.
The recorded-model lookup runs **before** the keyless local-first credential gate. A resumed cloud session on a machine with a reachable local endpoint (Ollama, LM Studio) is no longer silently switched to the local model. See [PraisonAI #3685](https://github.com/MervinPraison/PraisonAI/issues/3685).
### Override the recorded model
Pass `--model` on resume โ it wins and becomes the new recorded model for subsequent turns.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai session resume abc123 --model gpt-4o "continue with a different model"
```
### Where the model comes from
The store resolves the recorded model in this order: the session-level `metadata["model"]` (written by the session-continuity path), then the model on the most recent turn that recorded one. When neither exists, restoration is skipped and normal default resolution applies.
### Legacy sessions
Sessions written by older PraisonAI versions stored `model` / `llm` as top-level fields rather than under `metadata`. The store folds those legacy fields back into metadata on load, so historical sessions recover their recorded model on resume without any migration step. Existing `metadata` values always win over the mirrored top-level value.
***
## Cumulative Usage Across Resumes
Token and cost totals accumulate across all runs for a session. When you resume and run more prompts, the totals grow โ they are never reset.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
Run1[โถ๏ธ First run] --> Store1[๐พ Store: 1,240 in / 3,980 out]
Store1 --> Resume[โฉ Resume]
Resume --> Run2[โถ๏ธ Next run]
Run2 --> Store2[๐พ Store: 2,480 in / 7,960 out]
classDef run fill:#8B0000,stroke:#7C90A0,color:#fff
classDef store fill:#189AB4,stroke:#7C90A0,color:#fff
classDef resume fill:#F59E0B,stroke:#7C90A0,color:#fff
class Run1,Run2 run
class Store1,Store2 store
class Resume resume
```
The store that already holds usage metadata takes priority on resume โ a globally-stored session resumed via the project store keeps its original totals intact.
## Project vs Global Store
The resume helper always searches the **project-scoped store first**, then falls back to the **global default store**. This means sessions created inside a project are resolved with higher priority, and you can still resume cross-project sessions by ID.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Start([Resume request]) --> PS{Project store
has session?}
PS -->|Yes| Use1[Use project session]
PS -->|No| GS{Global store
has session?}
GS -->|Yes| Use2[Use global session]
GS -->|No| Err[โ Session not found]
classDef start fill:#8B0000,stroke:#7C90A0,color:#fff
classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
classDef err fill:#8B0000,stroke:#7C90A0,color:#fff
class Start start
class PS,GS check
class Use1,Use2 ok
class Err err
```
The `project_path` parameter (optional, defaults to `cwd`) controls which project store is searched first. Use it when running resume from a different working directory:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai session resume
```
***
## Flags
| Flag | Description |
| -------------- | --------------------------------------------------- |
| `` | Session ID to restore (required) |
| `[PROMPT]` | Optional prompt to continue the session immediately |
| `--transcript` | Show transcript only โ do not restore state |
***
## Relation to `run --continue` / `run --session`
`praisonai session resume` and `praisonai run --session ` call the **same `rehydrate_session()` helper** under the hood. The outcomes are identical: same chat history, same model, same agent. Use whichever form fits your workflow.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# These are equivalent:
praisonai session resume abc123 "next question"
praisonai run --session abc123 "next question"
```
As of the fix for [PraisonAI #2655](https://github.com/MervinPraison/PraisonAI/issues/2655), `run --continue` also searches **both** stores when finding the last session โ before, only `session resume` did.
As of [praisonai/PraisonAI#3203](https://github.com/MervinPraison/PraisonAI/pull/3203), both the resume path and the show/delete/export path enumerate the same store instances (same classes, same order) by delegating to a single `canonical_cli_stores()` helper โ so an id you can `resume` is guaranteed to also be `show`-able, `delete`-able, and `export`-able.
For the memory-driven resume path (different code path, uses `DefaultSessionStore` memory layers), see [Session Resume in Persistence](/docs/guides/persistence/session-resume).
***
## Best Practices
Store the session ID in an environment variable or config file so automation scripts always resume the correct conversation:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
SESSION_ID="abc-123-def"
praisonai session resume "$SESSION_ID" "run daily report"
```
`--transcript` shows events without restoring state, making it safe to inspect a live session from a second terminal without risk of creating conflicting state.
The global store covers cross-machine cases when the same project root is checked out. Sessions written to the project-scoped store travel with the project directory.
Always run `praisonai session list` first to confirm the session ID and its message count before resuming โ especially after long gaps.
***
## Related
View and manage all sessions
Give a session a friendly title for easy scanning
praisonai run --session and --continue flags
How sessions are stored and retrieved
The memory-driven session resume path