> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recallrai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Class

> Manage conversation sessions, messages, and context retrieval

## Overview

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

## Properties

<ResponseField name="sessionId" type="string">
  Unique identifier for the session.
</ResponseField>

<ResponseField name="status" type="SessionStatus">
  Current session status: `PENDING`, `PROCESSING`, `PROCESSED`, or `FAILED`.
</ResponseField>

<ResponseField name="metadata" type="object">
  Session metadata as an object.
</ResponseField>

<ResponseField name="createdAt" type="datetime">
  UTC timestamp when the session was created.
</ResponseField>

## Session Management Methods

### delete()

Delete this session and all associated data permanently.

```typescript theme={null}
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}`);
  }
}
```

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

**Returns:** `Promise<void>`

**Throws:** `UserNotFoundError`, `SessionNotFoundError`

## Message Methods

### addMessage()

```typescript theme={null}
import { MessageRole } from "recallrai";

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

<ParamField path="role" type="MessageRole" required>
  Message role: `USER` or `ASSISTANT`.
</ParamField>

<ParamField path="content" type="string" required>
  Message content text.
</ParamField>

## Context Retrieval

### getContext()

```typescript theme={null}
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:

```typescript theme={null}
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);
```

<Tip>
  This skips SDK lookup requests only. It removes extra latency from `getUser()` and `getSession()` when IDs are already validated in your own system.
</Tip>

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

<ParamField path="recallStrategy" type="RecallStrategy">
  Strategy for memory retrieval: `LOW_LATENCY`, `BALANCED`, `AGENTIC`, or `AUTO`.
</ParamField>

<ParamField path="minTopK" type="number" default="15">
  Minimum number of memories to return. Range: 5-50.
</ParamField>

<ParamField path="maxTopK" type="number" default="50">
  Maximum number of memories to return. Range: 10-100.
</ParamField>

<ParamField path="memoriesThreshold" type="number" default="0.6">
  Similarity threshold for memories. Range: 0.2-0.8.
</ParamField>

<ParamField path="summariesThreshold" type="number" default="0.5">
  Similarity threshold for summaries. Range: 0.2-0.8.
</ParamField>

<ParamField path="lastNMessages" type="number" optional>
  Number of last messages to include in context. Range: 1-100.
</ParamField>

<ParamField path="lastNSummaries" type="number" optional>
  Number of last summaries to include in context. Range: 1-20.
</ParamField>

<ParamField path="timezone" type="string" default="UTC">
  Timezone for formatting timestamps (e.g., "America/New\_York").
</ParamField>

<ParamField path="includeSystemPrompt" type="boolean" default="true">
  Whether to include the default RecallrAI system prompt.
</ParamField>

<ParamField path="includeMetadataIds" type="boolean" default="false">
  Whether to include memory IDs and session IDs that contributed to the context.

  <Tip>
    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.
  </Tip>
</ParamField>

**Returns:** `ContextResponse` object with:

<ResponseField name="isFinal" type="boolean">
  Always `true` for non-streaming responses.
</ResponseField>

<ResponseField name="context" type="string">
  The formatted context string containing relevant memories and conversation history.
</ResponseField>

<ResponseField name="metadata" type="ContextMetadata" optional>
  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)

  <Tip>
    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.
  </Tip>
</ResponseField>

### getContextStream()

Stream context events with status updates and structured metadata.

```typescript theme={null}
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);
  }
}
```

<ParamField path="includeMetadataIds" type="boolean" default="false">
  Whether to include context metadata (IDs, queries, filters, and agent reasoning in status events) in the response.
</ParamField>

**Yields:** `ContextResponse` objects with the following fields:

<ResponseField name="isFinal" type="boolean">
  Indicates whether this is the final event or a status update.
</ResponseField>

<ResponseField name="statusUpdateMessage" type="string" optional>
  Human-readable status update message (only present when `isFinal` is `false`).
</ResponseField>

<ResponseField name="errorMessage" type="string" optional>
  Error message if an error occurred during context generation.
</ResponseField>

<ResponseField name="context" type="string" optional>
  The formatted context string (only present when `isFinal` is `true`).
</ResponseField>

<ResponseField name="metadata" type="ContextMetadata" optional>
  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)
</ResponseField>