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

# Session Resume

> Continue conversations across sessions

Resume conversations automatically by using the same `session_id` in your Agent's memory configuration.

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

# First conversation
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant",
    memory={"session_id": "my-session-123"}
)
agent.start("My favorite color is blue")

# Later, in a new process - automatically resumes!
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant",
    memory={"session_id": "my-session-123"}
)
agent.start("What's my favorite color?")  # Remembers: "blue"
```

By default, passing `session_id` enables `history=True` automatically, which restores prior user and assistant turns from the session store into the new agent before it processes your next prompt. An explicit `session_id` is global — it resumes the same conversation from any project.

<Note>
  **Upgrading from name-only sessions:** without an explicit `session_id`, `history=True` now derives a **workspace-scoped** id, so the same agent name in a different project is a separate conversation. Legacy `history_<name-only>.json` files are not adopted automatically in workspace scope. To keep an old file everywhere, export `PRAISONAI_GLOBAL_SESSIONS=true`; to pin it to one project, pass an explicit `session_id`. See [Where sessions live](/docs/docs/memory/features#where-sessions-live).
</Note>

## With Database Persistence

For production apps, persist to a database:

<CodeGroup>
  ```python PostgreSQL theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  from praisonaiagents import Agent

  agent = Agent(
      name="Assistant",
      memory={
          "session_id": "user-123-main",
          "db": "postgresql://user:pass@localhost/mydb"
      }
  )
  ```

  ```python SQLite theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  from praisonaiagents import Agent

  agent = Agent(
      name="Assistant",
      memory={
          "session_id": "user-123-main",
          "db": "sqlite:///sessions.db"
      }
  )
  ```
</CodeGroup>

## Session ID Strategies

| Pattern            | Use Case            | Example                          |
| ------------------ | ------------------- | -------------------------------- |
| User-based         | Persistent per user | `f"user-{user_id}-main"`         |
| Conversation-based | New chat each time  | `f"conv-{uuid.uuid4().hex[:8]}"` |
| Task-based         | Workflow tracking   | `f"task-{task_id}-{user_id}"`    |

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

# User-based (recommended for most apps)
agent = Agent(
    name="Assistant",
    memory={"session_id": f"user-{user_id}-main"}
)

# Conversation-based (new session per chat)
import uuid
agent = Agent(
    name="Assistant",
    memory={"session_id": f"conv-{uuid.uuid4().hex[:8]}"}
)
```

## Auto-Derived Session ID Is Workspace-Scoped

When `history` is enabled and you don't pass a `session_id`, the Agent derives one automatically — and that id is now scoped to your workspace, so same-named agents in different projects keep separate history.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

# Two projects each define an agent called "assistant" with memory enabled.
# Each project gets its own history file automatically.
agent = Agent(
    name="assistant",
    instructions="Be helpful",
    memory="history",
)
```

The auto id folds a stable workspace identity into the hash: `history_<sha256("{workspace_id}:{name}")[:8]>`. The workspace identity prefers the git repository's root-commit sha, falls back to the resolved working directory, then `"global"`.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start[Auto id needed] --> Global{PRAISONAI_GLOBAL_SESSIONS?}
    Global -->|true| GName[sha256 'global:name']
    Global -->|false| Git{Inside a git repo?}
    Git -->|yes| GitId[workspace = 'git:root-commit-sha']
    Git -->|no| Cwd[workspace = 'dir:resolved-cwd']
    GitId --> Hash[sha256 'workspace:name']
    Cwd --> Hash

    classDef start fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Start start
    class Global,Git decision
    class GName,GitId,Cwd,Hash result
```

An explicit `session_id` is unchanged — it stays fully global and resumes anywhere.

### Opt Out with `PRAISONAI_GLOBAL_SESSIONS`

Set `PRAISONAI_GLOBAL_SESSIONS` to restore the pre-workspace, name-only global id — useful for a shared CLI where one agent should persist across every project.

| Env var                     | Values                                | Effect                                                            |
| --------------------------- | ------------------------------------- | ----------------------------------------------------------------- |
| `PRAISONAI_GLOBAL_SESSIONS` | `1`, `true`, `yes` (case-insensitive) | Force name-only global session ids (opt out of workspace scoping) |

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export PRAISONAI_GLOBAL_SESSIONS=true
```

### Backwards Compatibility

Legacy name-only session files (older sha256 and md5 ids) are adopted **only in global scope**, so existing history keeps loading when you opt out. In workspace scope, legacy files are ignored by design to preserve cross-project isolation.

Sessions live in `~/.praisonai/sessions/` by default; a custom `PRAISONAI_HOME` is honoured because the lookup resolves through `get_sessions_dir()`.

### Inspect the Workspace Identity

Read the opaque workspace identity string directly with the public helper.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.session import workspace_id

print(workspace_id())  # e.g. "git:<root-commit-sha>" or "dir:/path/to/project"
```

The result is cached per working directory.

## CLI Resume

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List sessions
praisonai session list

# Resume a session
praisonai session resume my-session

# Show session details
praisonai session show my-session
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Consistent IDs" icon="fingerprint">
    Same `session_id` = same conversation thread
  </Card>

  <Card title="User Isolation" icon="users">
    Include `user_id` in session\_id for multi-user apps
  </Card>

  <Card title="Right Backend" icon="database">
    JSON for dev, PostgreSQL for production
  </Card>

  <Card title="Meaningful Names" icon="tag">
    Use descriptive IDs: `user-123-support-ticket`
  </Card>

  <Card title="CLI equivalent" icon="terminal" href="/docs/cli/run">
    Use `praisonai run --continue` or `praisonai run --session <id>` for the same restore behaviour from the command line
  </Card>
</CardGroup>