Session Resume

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

Interrupted streamed runs now resume with their partial assistant turn (PraisonAI PR #5413). The streaming path persists the user turn and flushes the growing assistant answer as tokens arrive, so Ctrl-C mid-generation no longer loses the in-progress turn. See Streaming — Resuming after an interrupt.

Quick Start

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.

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.

With Database Persistence

For production apps, persist to a database:

from praisonaiagents import Agent

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

from praisonaiagents import Agent

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

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}"`

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.

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". 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)

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.

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

# List sessions
praisonai session list

# Resume a session
praisonai session resume my-session

# Show session details
praisonai session show my-session

Session and checkpoint name rules

Session names and checkpoint ids map to files on disk, so they cannot contain path separators or ...

Example name	Result
`my session`	✅ allowed (becomes `my session.json`)
`ckpt-1`	✅ allowed
`../../etc/passwd`	❌ raises `ValueError`
`a/b` or `a\b`	❌ raises `ValueError`
`..`	❌ raises `ValueError`
`""` or whitespace only	❌ raises `ValueError`

This applies to FileMemory.save_session, resume_session, delete_session, create_checkpoint, restore_checkpoint and delete_checkpoint, and to the name passed to RulesManager.create_rule, DocsManager.create_doc and MCPConfigManager.create_config.

Best Practices

Consistent IDs

Same session_id = same conversation thread

User Isolation

Include user_id in session_id for multi-user apps

Right Backend

JSON for dev, PostgreSQL for production

Meaningful Names

Use descriptive IDs: user-123-support-ticket

Memory Features

Auto-save sessions, episodic memory and FileMemory storage

CLI equivalent

Use praisonai run --continue or praisonai run --session <id> for the same restore behaviour from the command line

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

With Database Persistence

Session ID Strategies

Auto-Derived Session ID Is Workspace-Scoped

Opt Out with `PRAISONAI_GLOBAL_SESSIONS`

Backwards Compatibility

Inspect the Workspace Identity

CLI Resume

Session and checkpoint name rules

Best Practices

Consistent IDs

User Isolation

Right Backend

Meaningful Names

Memory Features

CLI equivalent

​Quick Start

​With Database Persistence

​Session ID Strategies

​Auto-Derived Session ID Is Workspace-Scoped

​Opt Out with PRAISONAI_GLOBAL_SESSIONS

​Backwards Compatibility

​Inspect the Workspace Identity

​CLI Resume

​Session and checkpoint name rules

​Best Practices

Consistent IDs

User Isolation

Right Backend

Meaningful Names

Memory Features

CLI equivalent

Quick Start

With Database Persistence

Session ID Strategies

Auto-Derived Session ID Is Workspace-Scoped

Opt Out with `PRAISONAI_GLOBAL_SESSIONS`

Backwards Compatibility

Inspect the Workspace Identity

CLI Resume

Session and checkpoint name rules

Best Practices