Overview
The Session class represents a conversation session. It provides methods for adding messages, retrieving context, and processing sessions to update user memories.
Properties
Unique identifier for the session.
ID of the user this session belongs to.
Current session status: PENDING, PROCESSING, PROCESSED, or FAILED
Session metadata as a dictionary.
UTC timestamp when the session was created. Can be customized using custom_created_at_utc during session creation for benchmarking or importing historical data.
UTC timestamp when the session was processed, or None if not yet processed.
auto_process_after_seconds
Seconds of inactivity before auto-processing, or None if disabled.
Session Management Methods
update()
Update the session metadata.
from recallrai.exceptions import SessionNotFoundError
try:
user = client.get_user("user123")
session = user.get_session("session-uuid")
session.update(new_metadata={"type": "support_chat", "priority": "high"})
print(f"Updated metadata: {session.metadata}")
except SessionNotFoundError as e:
print(f"Error: {e}")
New metadata to replace the existing metadata. Completely replaces the old metadata.
UserNotFoundError, SessionNotFoundError
refresh()
Refresh the session instance with the latest data from the server.
session = user.get_session("session-uuid")
session.refresh()
print(f"Current status: {session.status}")
print(f"Processed at: {session.processed_at}")
UserNotFoundError, SessionNotFoundError
Message Methods
add_message()
Add a message to the session.
from recallrai.models import MessageRole
from recallrai.exceptions import InvalidSessionStateError
try:
session = user.get_session("session-uuid")
# Add a user message
session.add_message(
role=MessageRole.USER,
content="Hello! How are you?"
)
# Add an assistant message
session.add_message(
role=MessageRole.ASSISTANT,
content="I'm doing well, thank you! How can I help you today?"
)
except InvalidSessionStateError as e:
print(f"Cannot add messages to a processed session: {e}")
Message role: MessageRole.USER or MessageRole.ASSISTANT
The message content text.
MessageRole.USER: Messages from the user/human
MessageRole.ASSISTANT: Messages from the AI assistant
UserNotFoundError, SessionNotFoundError, InvalidSessionStateError
You cannot add messages to a session that has already been processed.
get_messages()
Retrieve messages from the session with pagination.
session = user.get_session("session-uuid")
messages = session.get_messages(offset=0, limit=50)
print(f"Total messages: {messages.total}")
print(f"Has more: {messages.has_more}")
for msg in messages.messages:
print(f"{msg.role.value.upper()} (at {msg.timestamp}): {msg.content}")
Number of messages to skip. Default: 0
Maximum number of messages to return. Default: 50
MessageList object with:
messages: List of message objects with role, content, and timestamp fieldstotal: Total number of messages in the sessionhas_more: Boolean indicating if more messages are available
Raises: UserNotFoundError, SessionNotFoundError
Context Retrieval
get_context()
Retrieve contextual information for the session based on user memories and conversation history.
from recallrai.models import RecallStrategy
# Get context with default parameters
context = session.get_context()
print(f"Context: {context.context}")
# Get context with specific recall strategy
context = session.get_context(recall_strategy=RecallStrategy.LOW_LATENCY)
# Get context with custom parameters
context = session.get_context(
recall_strategy=RecallStrategy.BALANCED,
min_top_k=10,
max_top_k=100,
memories_threshold=0.6,
summaries_threshold=0.5,
last_n_messages=20,
last_n_summaries=5,
timezone="America/New_York",
include_system_prompt=True
)
Strategy for memory retrieval:
LOW_LATENCY: Fast retrieval with basic relevanceBALANCED: Good balance of speed and quality (default)AGENTIC: Agentic exploration for complex queries
Minimum number of memories to return. Range: 5-50. Default: 15
Maximum number of memories to return. Range: 10-100. Default: 50
Similarity threshold for memories. Range: 0.2-0.8. Default: 0.6
Similarity threshold for summaries. Range: 0.2-0.8. Default: 0.5
Number of last messages to include in context. Range: 1-100. Optional.
Number of last summaries to include in context. Range: 1-20. Optional.
Timezone for formatting timestamps in the context (e.g., “America/New_York”, “Europe/London”, “Asia/Tokyo”). All timestamps in the retrieved memories and summaries will be formatted according to this timezone. Defaults to UTC.Use the user’s local timezone for better temporal context. For example, showing “Today at 2:30 PM” is more meaningful than a UTC timestamp.
Whether to include the default RecallrAI system prompt. Default: True
Timestamps in the context are formatted using the specified timezone parameter (defaults to UTC). This ensures temporal information like “Last updated on Monday, January 6th at 3:45 PM EST” is presented in a user-friendly, localized format.
context field containing the formatted context string
Raises: UserNotFoundError, SessionNotFoundError
Use the context string as part of your system prompt when calling your LLM. This provides the AI with relevant memories and conversation history.
Processing
process()
Process the session to update user memories.
from recallrai.exceptions import InvalidSessionStateError
try:
session = user.get_session("session-uuid")
session.process()
print("Session processing started")
# Check status later
session.refresh()
print(f"Status: {session.status}")
except InvalidSessionStateError as e:
print(f"Cannot process session: {e}")
Processing extracts memories from the conversation and updates the user’s memory store. This is an asynchronous operation - the session status will change to PROCESSING and then PROCESSED when complete.
UserNotFoundError, SessionNotFoundError, InvalidSessionStateError
You can only process a session once. After processing, you cannot add more messages to the session.
Usage Example with LLM
Here’s how to use sessions with an LLM like OpenAI:
import openai
from recallrai import RecallrAI
from recallrai.models import MessageRole
# Initialize clients
rai_client = RecallrAI(api_key="rai_yourapikey", project_id="project-uuid")
oai_client = openai.OpenAI(api_key="your-openai-api-key")
# Get user and create session
user = rai_client.get_user("user123")
session = user.create_session(auto_process_after_seconds=1800)
# Get user input
user_message = input("You: ")
# Add to RecallrAI
session.add_message(role=MessageRole.USER, content=user_message)
# Get context from RecallrAI
context = session.get_context()
# Create system prompt with context
system_prompt = "You are a helpful assistant" + context.context
# Get conversation history
messages = session.get_messages(limit=50)
previous_messages = [
{"role": msg.role, "content": msg.content}
for msg in messages.messages
]
# Call LLM
response = oai_client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": system_prompt},
*previous_messages,
]
)
assistant_message = response.choices[0].message.content
print(f"Assistant: {assistant_message}")
# Add assistant response to RecallrAI
session.add_message(role=MessageRole.ASSISTANT, content=assistant_message)
# Process session when conversation ends
session.process()
Async Session
For async applications, use AsyncSession:
from recallrai import AsyncRecallrAI
from recallrai.models import MessageRole
client = AsyncRecallrAI(api_key="rai_yourapikey", project_id="project-uuid")
user = await client.get_user("user123")
session = await user.create_session()
# All methods are the same, just use await
await session.add_message(role=MessageRole.USER, content="Hello")
context = await session.get_context()
messages = await session.get_messages(limit=10)
await session.process()
