User Class

Overview

The User class represents a user in your RecallrAI project. It provides methods for managing sessions, memories, messages, and merge conflicts.

Properties

string

Unique identifier for the user.

object

User metadata as an object.

boolean | undefined

Per-user merge conflict override. true = always raise merge conflicts for this user. false = never raise. undefined = inherit the project-level setting.

datetime

UTC timestamp when the user was created.

datetime

UTC timestamp of the user’s last activity.

User Management Methods

update()

import { UserAlreadyExistsError } from "recallrai";

try {
  const user = await client.getUser("user123");
  await user.update({
    newMetadata: { name: "John Doe", role: "admin" },
    newUserId: "john_doe",
    mergeConflictEnabled: true, // optional: override merge conflict behaviour
  });
  console.log(`Updated user ID: ${user.userId}`);
} catch (error) {
  if (error instanceof UserAlreadyExistsError) {
    console.log(`New user ID already exists: ${error.message}`);
  }
}

object

New metadata to replace the existing metadata.

string

Optional new user ID. Must be unique within your project.

boolean

Per-user merge conflict override. true = always raise merge conflicts for this user. false = never raise. Set undefined to reset to the project-level default (omit the field from the call).

Returns: void Raises: UserNotFoundError, UserAlreadyExistsError

refresh()

const user = await client.getUser("john_doe");
await user.refresh();
console.log(`Latest metadata:`, user.metadata);

Returns: void Raises: UserNotFoundError

delete()

const user = await client.getUser("john_doe");
await user.delete();

This permanently deletes the user and all associated sessions, memories, and messages.

Returns: void Raises: UserNotFoundError

Session Management Methods

createSession()

const user = await client.getUser("user123");
const session = await user.createSession({
  autoProcessAfterSeconds: 600,
  metadata: { type: "chat", channel: "web" },
});

console.log(`Created session: ${session.sessionId}`);

number

Seconds of inactivity before auto-processing. Default: 600.

object

Optional metadata for the session.

getSession()

import { SessionNotFoundError } from "recallrai";

try {
  const user = await client.getUser("user123");
  const session = await user.getSession("session-uuid");
  console.log(`Session status: ${session.status}`);
} catch (error) {
  if (error instanceof SessionNotFoundError) {
    console.log(`Error: ${error.message}`);
  }
}

string

required

The UUID of the session to retrieve.

boolean

default:"true"

Whether to validate session existence via API before creating the instance. Set false only when userId and sessionId are already trusted.

Returns: Session Raises: UserNotFoundError, SessionNotFoundError

Set { validate: false } to skip the SDK lookup request (GET /api/v1/users/{userId}/sessions/{sessionId}) when IDs are already trusted.

When { validate: false } is used, fields that require an API lookup (for example status, createdAt, and metadata) are set to UNAVAILABLE until you call refresh(). Import UNAVAILABLE from recallrai when checking these values.

Memory Management Methods

listMemories()

List user memories with optional filtering.

import { UserNotFoundError, InvalidCategoriesError } from "recallrai";

try {
  const user = await client.getUser("user123");
  const memories = await user.listMemories({
    categories: ["food_preferences", "allergies"],
    sessionIdFilter: ["session-uuid-1", "session-uuid-2"],
    sessionMetadataFilter: { environment: "production" },
    offset: 0,
    limit: 20,
    includePreviousVersions: true,
    includeConnectedMemories: true,
  });

  for (const mem of memories.items) {
    console.log(`Memory: ${mem.content}`);
    console.log(`Categories: ${mem.categories}`);
    console.log(`Version: ${mem.versionNumber} of ${mem.totalVersions}`);
    console.log(`Event occurred: ${mem.eventDateStart} to ${mem.eventDateEnd}`);
    console.log(`Recorded at: ${mem.createdAt}`);
  }
} catch (error) {
  if (error instanceof InvalidCategoriesError) {
    console.log(`Invalid categories: ${error.invalidCategories}`);
  }
}

string[]

Filter by memory categories. Only memories matching these categories are returned.

string[]

Filter by specific session IDs.

object

Filter by session metadata.

number

Number of memories to skip. Default: 0

number

Maximum number of memories to return. Range: 1-200. Default: 20

boolean

Include version history for each memory. Default: true

boolean

Include related memories. Default: true

Returns: UserMemoriesList object Raises: UserNotFoundError, InvalidCategoriesError

getMemory()

Retrieve a single memory by its ID.

import { RecallrAIError } from "recallrai";

try {
  const user = await client.getUser("user123");
  const memory = await user.getMemory("memory-uuid", {
    includePreviousVersions: true,
    includeConnectedMemories: true,
  });
  console.log(`Content: ${memory.content}`);
  console.log(`Categories: ${memory.categories}`);
  console.log(`Version: ${memory.versionNumber} of ${memory.totalVersions}`);
} catch (error) {
  if (error instanceof RecallrAIError) {
    console.log(`Error: ${error.message}`);
  }
}

string

required

UUID of the memory to retrieve.

boolean

Include version history for the memory. Default: true

boolean

Include related memories. Default: true

Returns: UserMemoryItem Raises: RecallrAIError

deleteMemory()

Delete a specific memory version, with an option to also remove all previous versions in the chain.

import { RecallrAIError } from "recallrai";

try {
  const user = await client.getUser("user123");

  // Delete only the specified memory version
  await user.deleteMemory("memory-uuid");

  // Delete the specified version and all previous versions
  await user.deleteMemory("memory-uuid", true);
} catch (error) {
  if (error instanceof RecallrAIError) {
    console.log(`Error: ${error.message}`);
  }
}

string

required

UUID of the memory to delete. Can be any version in the version chain.

boolean

If true, deletes the specified version and all previous versions in the chain. If false (default), deletes only the specified version.

Deletion is permanent and cannot be undone. When deletePreviousVersions is true, the entire version history up to and including the specified version is removed.

Returns: void Raises: RecallrAIError

UserMemoryItem Fields

Each memory item contains:

memoryId: Unique identifier for the current version
categories: Array of category strings
content: Current version’s content text
eventDateStart: UTC Date when the event started (actual event time, not when it was recorded)
eventDateEnd: UTC Date when the event ended (actual event time, not when it was recorded)
createdAt: UTC Date when this memory version was created (when it was recorded in the system)
expiredAt: UTC Date when this version expired — only set when viewing an expired/previous version
expirationReason: Why this version was superseded (MERGE_CONFLICT, ADDITION_TO_EXISTING_MEMORY, TEMPORAL_CONFLICT) — only set for expired versions
sessionId: ID of the session that created this version
versionNumber: Current version number
totalVersions: Total number of versions
hasPreviousVersions: Boolean indicating multiple versions exist
previousVersions: Array of MemoryVersionInfo objects (optional)
connectedMemories: Array of MemoryRelationship objects (optional)
mergeConflictInProgress: Boolean indicating an active (unresolved) conflict on this memory
mergeConflictId: ID of the merge conflict that caused this memory to expire — only set when expirationReason is MERGE_CONFLICT and a conflict record exists (manually resolved conflicts only)

Each MemoryVersionInfo object in previousVersions contains:

memoryId: ID of that specific version (can be passed to getMemory() for full details)
versionNumber: Version number (1 = oldest)
content: Content of that version
eventDateStart / eventDateEnd: Event timestamps for that version
createdAt: When that version was created
expiredAt: When that version expired
expirationReason: Why it was superseded
mergeConflictId: Conflict that caused expiration, if applicable

The difference between eventDateStart/eventDateEnd and createdAt:

Event dates represent when the event actually occurred in the real world (e.g., “I met John on Monday”)
Created at represents when the memory was extracted and stored in the system

This distinction allows for better temporal reasoning when extracting memories from past conversations.

Python

Node.js

Overview

Properties

User Management Methods

update()

refresh()

delete()

Session Management Methods

createSession()

getSession()

Memory Management Methods

listMemories()

getMemory()

deleteMemory()

UserMemoryItem Fields

​Overview

​Properties

​User Management Methods

​update()

​refresh()

​delete()

​Session Management Methods

​createSession()

​getSession()

​Memory Management Methods

​listMemories()

​getMemory()

​deleteMemory()

​UserMemoryItem Fields

Overview

Properties

User Management Methods

update()

refresh()

delete()

Session Management Methods

createSession()

getSession()

Memory Management Methods

listMemories()

getMemory()

deleteMemory()

UserMemoryItem Fields