Session Store Protocol

Swap session backends with a unified protocol interface

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:

Method	Returns	Purpose
add_message(session_id, role, content, metadata)	bool	Store a single message
get_chat_history(session_id, max_messages)	list[dict]	Retrieve messages in LLM format
clear_session(session_id)	bool	Remove all messages (keep metadata)
delete_session(session_id)	bool	Delete session completely
session_exists(session_id)	bool	Check 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

Full example: In-memory store for testing

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

Verifying protocol conformance

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