Session Resume

Continue conversations across sessions

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

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.

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

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.

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

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