> ## 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, 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

<Steps>
  <Step title="Find your session ID">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai session list
    ```

    Copy the session ID from the output table.
  </Step>

  <Step title="Resume the session">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai session resume <session_id>
    ```

    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.
  </Step>

  <Step title="Continue with a new prompt">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai session resume <session_id> "What about Germany?"
    ```

    Passes the resumed state directly into the same run path as `praisonai run --session`.
  </Step>

  <Step title="View transcript only (read-only)">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai session resume <session_id> --transcript
    ```

    Prints recent events without restoring state — useful for reviewing a session without continuing it.
  </Step>
</Steps>

***

## 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 <id>
    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: <session_id>
  → Use 'praisonai session list' to see available sessions
```

***

## 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<br/>has session?}
    PS -->|Yes| Use1[Use project session]
    PS -->|No| GS{Global store<br/>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 <id>
```

***

## Flags

| Flag           | Description                                         |
| -------------- | --------------------------------------------------- |
| `<session_id>` | 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 <id>` 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.

<Note>
  For the memory-driven resume path (different code path, uses `DefaultSessionStore` memory layers), see [Session Resume in Persistence](/docs/guides/persistence/session-resume).
</Note>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Pin a session ID in scripts for reproducibility">
    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"
    ```
  </Accordion>

  <Accordion title="Use --transcript only for read-only viewing">
    `--transcript` shows events without restoring state, making it safe to inspect a live session from a second terminal without risk of creating conflicting state.
  </Accordion>

  <Accordion title="Resume after switching machines">
    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.
  </Accordion>

  <Accordion title="Check session list before resuming">
    Always run `praisonai session list` first to confirm the session ID and its message count before resuming — especially after long gaps.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Session List" icon="list" href="/docs/cli/session">
    View and manage all sessions
  </Card>

  <Card title="Run Command" icon="terminal" href="/docs/cli/run">
    praisonai run --session and --continue flags
  </Card>

  <Card title="Session Persistence" icon="database" href="/docs/features/session-persistence">
    How sessions are stored and retrieved
  </Card>

  <Card title="Memory-based Session Resume" icon="brain" href="/docs/guides/persistence/session-resume">
    The memory-driven session resume path
  </Card>
</CardGroup>