Skip to main content
/ Docs
Quickstart API SDKs

TypeScript SDK: Sessions

Manage CLI sessions with full lifecycle control using the TypeScript SDK.

Updated

Overview

The sessions resource provides complete lifecycle management for CLI sessions. Sessions organize memories into trackable contexts with states (active, paused, completed) and automatic memory counting.

Sessions were added in SDK v1.5.0. Ensure you're using the latest version to access this functionality.

Create Session

create-session.ts 
const session = await trix.sessions.create({
  name: 'Customer Support Chat',
  type: 'conversation'
});

console.log(session.id);
console.log(session.status);

const project = await trix.sessions.create({
  name: 'Q4 Feature Development',
  type: 'project',
  description: 'New analytics dashboard features',
  tags: ['q4', 'analytics', 'frontend'],
  spaceId: 'spc_abc123',
  retentionPolicy: 'permanent',
  isPrivate: false,
  metadata: {
    team: 'engineering',
    priority: 'high'
  }
});

Create Options

OptionTypeDescription
namestringSession name (required, max 200 chars)
typeSessionType'conversation', 'project', 'task', or 'temporary'
descriptionstringDetailed description (max 1000 chars)
tagsstring[]Tags for organization (max 10 tags)
spaceIdstringAssociate session with a space
retentionPolicyRetentionPolicy'permanent', 'temporary', 'auto_delete', 'on_completion'
retentionDaysnumberDays before auto-deletion (for auto_delete policy)
isPrivatebooleanPrivate sessions visible only to creator
metadataobjectCustom key-value metadata

List and Filter Sessions

list-sessions.ts 
const { data, pagination } = await trix.sessions.list();

console.log(`Found ${data.length} sessions`);

const activeSessions = await trix.sessions.list({
  status: 'active',
  type: 'project',
  limit: 20
});

const found = await trix.sessions.list({
  search: 'customer support',
  tags: 'q4,frontend'
});

const recent = await trix.sessions.list({
  sortBy: 'last_active_at',
  sortOrder: 'desc',
  limit: 10
});

List Options

OptionTypeDescription
statusSessionStatusFilter by status: 'active', 'paused', 'completed', 'archived'
typeSessionTypeFilter by session type
spaceIdstringFilter by space
tagsstringComma-separated tags
searchstringSearch name and description
limitnumberResults per page (default: 20, max: 100)
sortBystring'created_at', 'updated_at', 'last_active_at', 'name'
sortOrderstring'asc' or 'desc'

Get Session

get-session.ts 
const session = await trix.sessions.get('sess_abc123');

console.log(session.name);
console.log(`Status: ${session.status}`);
console.log(`Memories: ${session.memoryCount}`);
console.log(`Messages: ${session.messageCount}`);

console.log(`Created: ${session.createdAt}`);
console.log(`Last active: ${session.lastActiveAt}`);

Update Session

update-session.ts 
const updated = await trix.sessions.update('sess_abc123', {
  description: 'Updated project description',
  tags: ['q4', 'analytics', 'frontend', 'high-priority'],
  metadata: {
    status: 'in-progress',
    assignee: 'engineering-team'
  }
});

console.log('Session updated:', updated.name);

Only provided fields are updated. Omitted fields remain unchanged.

Lifecycle Management

Manage session state transitions: active → paused → active → completed

Pause Session

pause-session.ts 
const paused = await trix.sessions.pause('sess_abc123');

console.log(paused.status);
console.log(paused.pausedAt);

Paused sessions cannot accept new memories. Pause sessions when taking a break to prevent accidental additions.

Resume Session

resume-session.ts 
const resumed = await trix.sessions.resume('sess_abc123');

console.log(resumed.status);
console.log(resumed.pausedAt);

Complete Session

complete-session.ts 
const completed = await trix.sessions.complete('sess_abc123', {
  summary: 'Successfully launched Q4 campaigns with 15% increase in engagement'
});

console.log(completed.status);
console.log(completed.completedAt);
console.log(completed.summary);

const done = await trix.sessions.complete('sess_def456');

Completed sessions are read-only. They cannot be reopened or modified.

Delete Session

delete-session.ts 
await trix.sessions.delete('sess_abc123');

console.log('Session deleted');

Deleting a session permanently removes it and all associated memories. Consider completing or archiving instead.

Get Active Sessions

get-active-sessions.ts 
const { data } = await trix.sessions.getActive();

console.log(`${data.length} active sessions`);

for (const session of data) {
  console.log(`${session.name}: ${session.memoryCount} memories`);
}

Session Memories

get-session-memories.ts 
const { data, pagination } = await trix.sessions.getMemories('sess_abc123', {
  limit: 50
});

console.log(`Found ${data.length} memories`);

for (const memory of data) {
  console.log(`[${memory.createdAt}] ${memory.content}`);
}

Creating Memories in Sessions

create-memory-in-session.ts 
await trix.memories.create({
  content: 'Design system uses Material 3',
  sessionId: 'sess_abc123'
});

const session = await trix.sessions.get('sess_abc123');
console.log(`Memory count: ${session.memoryCount}`);

Complete Workflow Example

complete-workflow.ts 
async function manageProject() {
  const session = await trix.sessions.create({
    name: 'Mobile App Redesign',
    type: 'project',
    description: 'Redesign iOS and Android apps',
    tags: ['mobile', 'ui', 'q1-2024'],
    spaceId: 'spc_engineering'
  });

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

  await trix.memories.create({
    content: 'Design system uses Material 3',
    sessionId: session.id
  });

  await trix.memories.create({
    content: 'Target: iOS 15+ and Android 12+',
    sessionId: session.id
  });

  await trix.sessions.pause(session.id);
  console.log('Session paused');

  await trix.sessions.resume(session.id);
  console.log('Session resumed');

  await trix.memories.create({
    content: 'Added dark mode support',
    sessionId: session.id
  });

  const completed = await trix.sessions.complete(session.id, {
    summary: 'Successfully launched redesigned apps with 95% positive feedback'
  });

  console.log(`Project completed with ${completed.memoryCount} memories`);
}

manageProject();

TypeScript Types

types.ts 
import type {
  CLISession,
  SessionType,
  SessionStatus,
  SessionRetentionPolicy,
  CreateCLISessionParams,
  UpdateCLISessionParams,
  CompleteCLISessionParams,
  ListCLISessionsParams,
  CLISessionsResponse,
  CLISessionStats
} from '@trixdb/client';

type SessionType = 'conversation' | 'project' | 'task' | 'temporary';

type SessionStatus = 'active' | 'paused' | 'completed' | 'archived';

type SessionRetentionPolicy =
  | 'permanent'
  | 'temporary'
  | 'auto_delete'
  | 'on_completion';

interface CLISession {
  id: string;
  accountId: string;
  userId: string;
  createdBy: string;
  name: string;
  description?: string;
  type: SessionType;
  status: SessionStatus;
  spaceId?: string;
  originType?: string;
  tags?: string[];
  retentionPolicy: SessionRetentionPolicy;
  retentionDays?: number;
  summary?: string;
  isPrivate: boolean;
  messageCount: number;
  memoryCount: number;
  metadata?: Record<string, any>;
  createdAt: string;
  updatedAt: string;
  lastActiveAt: string;
  pausedAt?: string;
  completedAt?: string;
  archivedAt?: string;
}

Error Handling

error-handling.ts 
import { TrixError } from '@trixdb/client';

try {
  await trix.sessions.pause('sess_abc123');
} catch (error) {
  if (error instanceof TrixError) {
    if (error.statusCode === 409) {
      console.error('Invalid state transition');
      console.error('Session may already be paused or completed');
    } else if (error.statusCode === 404) {
      console.error('Session not found');
    }
  }
}

Best Practices

  • Descriptive names: Use clear, searchable session names
  • Use appropriate types: Choose the session type that matches your use case
  • Tag consistently: Establish tagging conventions for your team
  • Pause inactive sessions: Prevent accidental memory additions
  • Add summaries: Include completion summaries for future reference
  • Set retention policies: Use temporary sessions for ephemeral work
  • Use spaces: Combine sessions with spaces for better organization

Next Steps