Skip to main content

​
Overview

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

​
Properties

​
sessionId
string
Unique identifier for the session.
​
status
SessionStatus
Current session status: PENDING, PROCESSING, PROCESSED, or FAILED.
​
metadata
object
Session metadata as an object.
​
createdAt
datetime
UTC timestamp when the session was created.

​
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!");
​
role
MessageRole
required
Message role: USER or ASSISTANT.
​
content
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);
}
​
recallStrategy
RecallStrategy
Strategy for memory retrieval: LOW_LATENCY, BALANCED, AGENTIC, or AUTO.
​
minTopK
number
default:"15"
Minimum number of memories to return. Range: 5-50.
​
maxTopK
number
default:"50"
Maximum number of memories to return. Range: 10-100.
​
memoriesThreshold
number
default:"0.6"
Similarity threshold for memories. Range: 0.2-0.8.
​
summariesThreshold
number
default:"0.5"
Similarity threshold for summaries. Range: 0.2-0.8.
​
lastNMessages
number
Number of last messages to include in context. Range: 1-100.
​
lastNSummaries
number
Number of last summaries to include in context. Range: 1-20.
​
timezone
string
default:"UTC"
Timezone for formatting timestamps (e.g., “America/New_York”).
​
includeSystemPrompt
boolean
default:"true"
Whether to include the default RecallrAI system prompt.
​
includeMetadataIds
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:
​
isFinal
boolean
Always true for non-streaming responses.
​
context
string
The formatted context string containing relevant memories and conversation history.
​
metadata
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);
  }
}
​
includeMetadataIds
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:
​
isFinal
boolean
Indicates whether this is the final event or a status update.
​
statusUpdateMessage
string
Human-readable status update message (only present when isFinal is false).
​
errorMessage
string
Error message if an error occurred during context generation.
​
context
string
The formatted context string (only present when isFinal is true).
​
metadata
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)