Session Class

Overview

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

Properties

string

Unique identifier for the session.

SessionStatus

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

object

Session metadata as an object.

datetime

UTC timestamp when the session was created.

Session Management Methods

delete()

Delete this session and all associated data permanently.

import { UserNotFoundError, SessionNotFoundError } from "recallrai";

try {
  const session = await user.getSession("session-uuid");
  await session.delete();
  console.log("Session deleted successfully");
} catch (error) {
  if (error instanceof SessionNotFoundError) {
    console.log(`Session not found: ${error.message}`);
  } else if (error instanceof UserNotFoundError) {
    console.log(`User not found: ${error.message}`);
  }
}

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: Promise<void> Throws: UserNotFoundError, SessionNotFoundError

Message Methods

addMessage()

import { MessageRole } from "recallrai";

await session.addMessage(MessageRole.USER, "Hello! How are you?");
await session.addMessage(MessageRole.ASSISTANT, "I am doing well, thanks!");

MessageRole

required

Message role: USER or ASSISTANT.

string

required

Message content text.

Context Retrieval

getContext()

import { RecallStrategy } from "recallrai";

const response = await session.getContext({
  recallStrategy: RecallStrategy.BALANCED,
  minTopK: 10,
  maxTopK: 100,
  memoriesThreshold: 0.6,
  summariesThreshold: 0.5,
  lastNMessages: 20,
  lastNSummaries: 5,
  timezone: "America/New_York",
  includeMetadataIds: true
});

console.log(response.context);

if (response.metadata) {
  console.log("Memory IDs:", response.metadata.memoryIds);
  console.log("Session IDs:", response.metadata.sessionIds);
}

Trusted IDs Fast Path

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

const trustedUser = await client.getUser("user123", { validate: false });
const trustedSession = await trustedUser.getSession("session-uuid", { validate: false });

const response = await trustedSession.getContext();
console.log(response.context);

This skips SDK lookup requests only. It removes extra latency from getUser() and getSession() 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.

RecallStrategy

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

number

default:"15"

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

number

default:"50"

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

number

default:"0.6"

Similarity threshold for memories. Range: 0.2-0.8.

number

default:"0.5"

Similarity threshold for summaries. Range: 0.2-0.8.

number

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

number

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

string

default:"UTC"

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

boolean

default:"true"

Whether to include the default RecallrAI system prompt.

boolean

default:"false"

Whether to include memory IDs and session IDs that contributed to the context.

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.

Returns: ContextResponse object with:

boolean

Always true for non-streaming responses.

string

The formatted context string containing relevant memories and conversation history.

ContextMetadata

Only present when includeMetadataIds=true. Contains:

memoryIds: Array of memory IDs that contributed to the context
sessionIds: Array of session IDs that contributed to the context
agentReasoning: (Optional) Agent’s reasoning process, only populated when using agentic recall strategy
vectorSearchQueries: (Optional) Vector search queries generated for recall
keywords: (Optional) Keywords extracted for recall
sessionSummariesSearchQueries: (Optional) Queries used to search session summaries
dateRangeFilters: (Optional) Date range filters extracted from the query (balanced recall only)

When using the agentic recall strategy, the agentReasoning 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.

getContextStream()

Stream context events with status updates and structured metadata.

for await (const event of session.getContextStream({
  recallStrategy: RecallStrategy.BALANCED,
  timezone: "America/New_York",
  includeMetadataIds: true
})) {
  if (event.statusUpdateMessage) {
    console.log("Status:", event.statusUpdateMessage);
  }
  if (event.isFinal) {
    if (event.errorMessage) {
      console.log("Error:", event.errorMessage);
    } else {
      console.log("Final context:", event.context);
      if (event.metadata) {
        console.log("Memory IDs:", event.metadata.memoryIds);
        console.log("Session IDs:", event.metadata.sessionIds);
        console.log("Vector Queries:", event.metadata.vectorSearchQueries);
        console.log("Keywords:", event.metadata.keywords);
        console.log("Summary Queries:", event.metadata.sessionSummariesSearchQueries);
        console.log("Date Filters:", event.metadata.dateRangeFilters);
      }
    }
  }
  if (event.metadata?.agentReasoning) {
    console.log("Agent Reasoning:", event.metadata.agentReasoning);
  }
}

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:

boolean

Indicates whether this is the final event or a status update.

string

Human-readable status update message (only present when isFinal is false).

string

Error message if an error occurred during context generation.

string

The formatted context string (only present when isFinal is true).

ContextMetadata

Only present when includeMetadataIds=true and isFinal=true. Contains:

memoryIds: Array of memory IDs that contributed to the context
sessionIds: Array of session IDs that contributed to the context
agentReasoning: (Optional) Agent’s reasoning process, only populated when using agentic recall strategy
vectorSearchQueries: (Optional) Vector search queries generated for recall
keywords: (Optional) Keywords extracted for recall
sessionSummariesSearchQueries: (Optional) Queries used to search session summaries
dateRangeFilters: (Optional) Date range filters extracted from the query (balanced recall only)

Python

Node.js

Overview

Properties

Session Management Methods

delete()

Message Methods

addMessage()

Context Retrieval

getContext()

Trusted IDs Fast Path

getContextStream()

​Overview

​Properties

​Session Management Methods

​delete()

​Message Methods

​addMessage()

​Context Retrieval

​getContext()

​Trusted IDs Fast Path

​getContextStream()

Overview

Properties

Session Management Methods

delete()

Message Methods

addMessage()

Context Retrieval

getContext()

Trusted IDs Fast Path

getContextStream()