Skip to main content
The SessionStoreProtocol defines five methods that any session backend must implement. This lets you swap between JSON files, Redis, MongoDB, or your own custom store — without changing any agent or bot code.

​
Quick Start

1

Use the built-in JSON store (zero config)

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    memory={"session_id": "chat-123"}
)
agent.start("Hello!")
Sessions are automatically persisted to ~/.praisonai/sessions/chat-123.json.
2

Swap to a custom store

from praisonaiagents.session import SessionStoreProtocol

class RedisSessionStore:
    """Your custom Redis-backed session store."""

    def add_message(self, session_id, role, content, metadata=None):
        # Save to Redis
        ...
        return True

    def get_chat_history(self, session_id, max_messages=None):
        # Load from Redis
        return [{"role": "user", "content": "Hi"}]

    def clear_session(self, session_id):
        return True

    def delete_session(self, session_id):
        return True

    def session_exists(self, session_id):
        return False

# Verify at runtime
store = RedisSessionStore()
assert isinstance(store, SessionStoreProtocol)  # ✅ True

​
Protocol Methods

The protocol requires exactly five methods:
MethodReturnsPurpose
add_message(session_id, role, content, metadata)boolStore a single message
get_chat_history(session_id, max_messages)list[dict]Retrieve messages in LLM format
clear_session(session_id)boolRemove all messages (keep metadata)
delete_session(session_id)boolDelete session completely
session_exists(session_id)boolCheck if a session exists
The protocol uses Python’s typing.Protocol with @runtime_checkable, so any class with matching method signatures automatically satisfies it — no inheritance needed.

​
Built-in Implementations

DefaultSessionStore

JSON file-based persistence with atomic writes and file locking. Zero dependencies.
from praisonaiagents.session import DefaultSessionStore

store = DefaultSessionStore(
    session_dir="/custom/path",
    max_messages=200,
)

HierarchicalSessionStore

Extends DefaultSessionStore with session forking, snapshots, and revert.
from praisonaiagents.session import HierarchicalSessionStore

store = HierarchicalSessionStore()
parent = store.create_session(title="Main")
child = store.fork_session(parent, from_message_index=5)

​
Using with Bots

Bots use the same SessionStoreProtocol for persistent per-user sessions: 
from praisonaiagents.session import get_default_session_store

# Bot sessions persist automatically
from praisonai.bots import Bot

bot = Bot(
    "telegram",
    agent=my_agent,
    session_store=get_default_session_store(),
)
Each user gets a deterministic session key like bot_telegram_12345, stored in the same ~/.praisonai/sessions/ directory as agent sessions.

​
Building a Custom Store

from typing import Any, Dict, List, Optional

class InMemorySessionStore:
    """Fast in-memory store for unit tests."""

    def __init__(self):
        self._data: Dict[str, List[Dict]] = {}

    def add_message(
        self, session_id: str, role: str, content: str,
        metadata: Optional[Dict[str, Any]] = None,
    ) -> bool:
        self._data.setdefault(session_id, []).append(
            {"role": role, "content": content}
        )
        return True

    def get_chat_history(
        self, session_id: str, max_messages: Optional[int] = None,
    ) -> List[Dict[str, str]]:
        msgs = self._data.get(session_id, [])
        return msgs[-max_messages:] if max_messages else list(msgs)

    def clear_session(self, session_id: str) -> bool:
        self._data[session_id] = []
        return True

    def delete_session(self, session_id: str) -> bool:
        self._data.pop(session_id, None)
        return True

    def session_exists(self, session_id: str) -> bool:
        return session_id in self._data

from praisonaiagents.session import SessionStoreProtocol

store = InMemorySessionStore()

# Runtime check — no registration needed
assert isinstance(store, SessionStoreProtocol)

# Use it anywhere a SessionStoreProtocol is expected
store.add_message("test", "user", "Hello")
history = store.get_chat_history("test")
assert history == [{"role": "user", "content": "Hello"}]

​
Architecture Overview

​
Next Steps

Learn about session persistence details

Sessions & remote agents overview