Session Class

Overview

The Session class represents a conversation session. It provides methods for adding messages, retrieving context, and processing sessions to update user memories.

Properties

string

Unique identifier for the session.

string

ID of the user this session belongs to.

SessionStatus

Current session status: PENDING, PROCESSING, PROCESSED, or FAILED

dict

Session metadata as a dictionary.

datetime

UTC timestamp when the session was created. Can be customized using custom_created_at_utc during session creation for benchmarking or importing historical data.

datetime | None

UTC timestamp when the session was processed, or None if not yet processed.

integer | None

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

dict

required

New metadata to replace the existing metadata. Completely replaces the old metadata.

Returns: None (mutates the instance in place) Raises: 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}")

Returns: None (updates the instance in place) Raises: UserNotFoundError, SessionNotFoundError

delete()

Delete this session and all associated data permanently.

from recallrai.exceptions import UserNotFoundError, SessionNotFoundError

try:
    session = user.get_session("session-uuid")
    session.delete()
    print("Session deleted successfully")
except SessionNotFoundError as e:
    print(f"Session not found: {e}")
except UserNotFoundError as e:
    print(f"User not found: {e}")

This action is irreversible. Deleting a session permanently removes its messages, memories, memory connections, memory categories, and merge conflicts that were created from it.

Returns: None Raises: 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}")

MessageRole

required

Message role: MessageRole.USER or MessageRole.ASSISTANT

string

required

The message content text.

MessageRole.USER: Messages from the user/human
MessageRole.ASSISTANT: Messages from the AI assistant

Returns: None Raises: 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}")

integer

Number of messages to skip. Default: 0

integer

Maximum number of messages to return. Default: 50

Returns: MessageList object with:

messages: List of message objects with role, content, and timestamp fields
total: Total number of messages in the session
has_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_response = session.get_context()
print(f"Context: {context_response.context}")

# Get context with memory and session IDs
context_response = session.get_context(
    include_metadata_ids=True
)
if context_response.metadata:
    print(f"Memory IDs: {context_response.metadata.memory_ids}")
    print(f"Session IDs: {context_response.metadata.session_ids}")

# Get context with specific recall strategy
context_response = session.get_context(recall_strategy=RecallStrategy.LOW_LATENCY)

# Get context with custom parameters
context_response = 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,
    include_metadata_ids=True
)

Trusted IDs Fast Path

If your system already trusts the IDs, you can skip SDK pre-validation calls and go directly to context retrieval:

trusted_user = client.get_user("user123", validate=False)
trusted_session = trusted_user.get_session(session_id="session-uuid", validate=False)

context_response = trusted_session.get_context()
print(context_response.context)

This skips SDK lookup requests only. It removes extra latency from get_user() and get_session() when IDs are already validated in your own system.

Use this only with trusted IDs. The context endpoint still performs server-side validation and can still return UserNotFoundError or SessionNotFoundError.

get_context_stream()

Stream context events with status updates and structured metadata.

from recallrai.models import RecallStrategy

for event in session.get_context_stream(
    recall_strategy=RecallStrategy.BALANCED,
    timezone="America/New_York",
    include_metadata_ids=True
):
    if event.status_update_message:
        print("Status:", event.status_update_message)
    if event.is_final:
        if event.error_message:
            print("Error:", event.error_message)
        else:
            print("Final context:", event.context)
            if event.metadata:
                print("Memory IDs:", event.metadata.memory_ids)
                print("Session IDs:", event.metadata.session_ids)
                print("Vector Queries:", event.metadata.vector_search_queries)
                print("Keywords:", event.metadata.keywords)
                print("Summary Queries:", event.metadata.session_summaries_search_queries)
                print("Date Filters:", event.metadata.date_range_filters)
    if event.metadata.agent_reasoning:
        print("Agent Reasoning:", event.metadata.agent_reasoning)

RecallStrategy

Strategy for memory retrieval: LOW_LATENCY, BALANCED, AGENTIC, or AUTO.

string

Timezone for formatting timestamps (e.g., America/New_York).

boolean

default:"False"

Whether to include context metadata (IDs, queries, filters, and agent reasoning in status events) in the response.

Yields: ContextResponse objects with the following fields:

RecallStrategy

Strategy for memory retrieval:

LOW_LATENCY: Fast retrieval with basic relevance
BALANCED: Good balance of speed and quality (default)
AGENTIC: Agentic exploration for complex queries

integer

Minimum number of memories to return. Range: 5-50. Default: 15

integer

Maximum number of memories to return. Range: 10-100. Default: 50

float

Similarity threshold for memories. Range: 0.2-0.8. Default: 0.6

float

Similarity threshold for summaries. Range: 0.2-0.8. Default: 0.5

integer

Number of last messages to include in context. Range: 1-100. Optional.

integer

Number of last summaries to include in context. Range: 1-20. Optional.

string

default:"UTC"

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.

boolean

Whether to include the default RecallrAI system prompt. Default: True

boolean

default:"False"

Whether to include context metadata. When True, the response includes a metadata field with IDs, queries, filters, and agent reasoning when available.

Enable this to track which specific memories and sessions were used to generate the context, useful for debugging, auditing, or building UI features that show sources.

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.

Returns: ContextResponse object with the following fields:

boolean

Always True for non-streaming responses.

string

The formatted context string containing relevant memories and conversation history.

ContextMetadata

Only present when include_metadata_ids=True. Contains:

memory_ids: List of memory IDs that contributed to the context
session_ids: List of session IDs that contributed to the context
agent_reasoning: (Optional) Agent’s reasoning process, only populated when using agentic recall strategy
vector_search_queries: (Optional) Vector search queries generated for recall
keywords: (Optional) Keywords extracted for recall
session_summaries_search_queries: (Optional) Queries used to search session summaries
date_range_filters: (Optional) Date range filters extracted from the query (balanced recall only)

When using the agentic recall strategy, the agent_reasoning field will contain a step-by-step summary of the agent’s exploration through your knowledge graph, showing how it arrived at the final context.

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.

Returns: None Raises: 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_response = session.get_context()

# Create system prompt with context
system_prompt = "You are a helpful assistant" + context_response.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()

Python

Node.js

Overview

Properties

Session Management Methods

update()

refresh()

delete()

Message Methods

add_message()

get_messages()

Context Retrieval

get_context()

Trusted IDs Fast Path

get_context_stream()

Processing

process()

Usage Example with LLM

Async Session

​Overview

​Properties

​Session Management Methods

​update()

​refresh()

​delete()

​Message Methods

​add_message()

​get_messages()

​Context Retrieval

​get_context()

​Trusted IDs Fast Path

​get_context_stream()

​Processing

​process()

​Usage Example with LLM

​Async Session

Overview

Properties

Session Management Methods

update()

refresh()

delete()

Message Methods

add_message()

get_messages()

Context Retrieval

get_context()

Trusted IDs Fast Path

get_context_stream()

Processing

process()

Usage Example with LLM

Async Session