Sessions

Organize work and conversations into trackable sessions with lifecycle management.

Updated Oct 6, 2026

What are Sessions?

Sessions provide a way to organize and track related work, conversations, or tasks over time. Each session has a lifecycle (active, paused, completed) and automatically tracks associated memories, making it easy to maintain context and review past work.

Use Cases

Track AI agent conversations with full context
Organize project work into trackable sessions
Manage task-specific memory contexts
Review and analyze past work sessions
Maintain separate contexts for different workflows

Key Features

Automatic memory counting and tracking
Lifecycle management (active -> paused -> completed)
Session-scoped memory operations
Retention policies for automatic cleanup
Tagging and search capabilities

Session Types

Trix supports four session types, each optimized for different use cases:

Type	Description	Best For
`conversation`	Multi-turn AI agent conversations	Chatbots, assistants, dialogue systems
`project`	Long-running work efforts	Software projects, research, long-term initiatives
`task`	Specific objectives with clear endpoints	Bug fixes, feature requests, discrete work items
`temporary`	Short-lived contexts that auto-cleanup	Demos, experiments, temporary testing

Session Lifecycle

Every session goes through a lifecycle from creation to completion or archival:

active -> paused -> active -> completed -> archived
  v         v        v         v           v
created   work    resume    finish    cleanup

Session Statuses

Status	Description	Memory Operations
`active`	Currently in use, accepting new memories	Create, read, update, delete
`paused`	Temporarily inactive, can be resumed	Read-only (no new memories)
`completed`	Finished with optional summary	Read-only (no modifications)
`archived`	Long-term storage, reduced visibility	Read-only (no modifications)

Only active sessions accept new memories. Pause a session to temporarily prevent new memories from being added while preserving the ability to resume later.

SDK Usage

Sessions can be managed programmatically using the Trix SDKs (TypeScript, Python, C#). All SDKs provide the same comprehensive API for session management.

Creating Sessions

Create a session with the SDK:

// Create a simple conversation session
const session = await trix.sessions.create({
  name: "Customer Support Chat",
  type: "conversation"
});

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

Create a project session with full metadata:

// Create a project session with full metadata
const session = 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
});

Listing and Filtering

List all sessions:

// List all sessions
const sessions = await trix.sessions.list();

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

Filter sessions by status, type, tags, and more:

// List with filters
const sessions = await trix.sessions.list({
  status: "active",
  type: "project",
  tags: "q4,frontend",
  limit: 20,
  sortBy: "last_active_at",
  sortOrder: "desc"
});

Managing Lifecycle

Pause a session:

// Pause an active session
const paused = await trix.sessions.pause("sess_abc123");

console.log(`Status: ${paused.status}`); // "paused"

Resume a paused session:

// Resume a paused session
const resumed = await trix.sessions.resume("sess_abc123");

console.log(`Status: ${resumed.status}`); // "active"

Complete a session with a summary:

// Complete a session with summary
const completed = await trix.sessions.complete("sess_abc123", {
  summary: "Successfully launched all Q4 campaigns with 15% increase in engagement"
});

console.log(`Status: ${completed.status}`); // "completed"

Working with Session Memories

Get all memories associated with a session:

// Get memories in a session
const memories = await trix.sessions.getMemories("sess_abc123", {
  limit: 50
});

console.log(`Found ${memories.data.length} memories`);
memories.data.forEach(m => console.log(m.content));

Getting Statistics

Retrieve aggregate statistics across all sessions:

// Get session statistics
const stats = await trix.sessions.getStats();

console.log(`Total: ${stats.total}`);
console.log(`Active: ${stats.byStatus.active}`);
console.log(`Completed: ${stats.byStatus.completed}`);

Complete Workflow Example

Here's a complete example of managing a project session from creation to completion:

// Complete project workflow
// 1. Create project session
const session = await trix.sessions.create({
  name: "Mobile App Redesign",
  type: "project",
  description: "Redesign iOS and Android apps",
  tags: ["mobile", "ui", "q1-2024"]
});

// 2. Add memories during work
await trix.memories.create({
  content: "Design system uses Material 3",
  sessionId: session.id
});

// 3. Pause when taking a break
await trix.sessions.pause(session.id);

// 4. Resume work later
await trix.sessions.resume(session.id);

// 5. Complete with summary
await trix.sessions.complete(session.id, {
  summary: "Successfully launched redesigned apps with 95% positive feedback"
});

Getting Started (CLI)

Creating Your First Session

Create a session with a descriptive name and optional metadata:

# Create a simple conversation session
trix session create "Customer Support Chat"

# Create a project session with metadata
trix session create "Q4 Feature Development" \
  --type project \
  --description "New analytics dashboard features" \
  --tags "q4,analytics,frontend"

# Create a temporary session (auto-cleanup)
trix session create "Demo Session" \
  --type temporary \
  --retention temporary

Switching Between Sessions

Set a session as "current" to automatically associate new memories with it:

# Switch to a session by ID
trix session switch sess_abc123

# Switch by name (searches for match)
trix session switch "Customer Support"

# Check which session is current
trix session current

# Create a memory in the current session
trix mem create "User prefers email notifications"
# Automatically associated with current session!

Working with Session Memories

All memory operations support the --session flag:

# Create memory in specific session
trix mem create "Important finding" --session sess_abc123

# Use current session automatically
trix mem create "Another note" --session current

# List memories from a session
trix mem list --session current

# Search within a session
trix mem search "query" --session sess_abc123

# Combine with space filtering
trix mem list --space research --session current

Common Workflows

Project Workflow

Track a long-running project from start to completion:

# 1. Start a new project
trix session create "Mobile App Redesign" \
  --type project \
  --description "Redesign iOS and Android apps" \
  --tags "mobile,ui,q1-2024"

# 2. Switch to it and work
trix session switch "Mobile App Redesign"
trix mem create "Design system uses Material 3"
trix mem create "Target: iOS 15+ and Android 12+"

# 3. Take a break (prevents accidental additions)
trix session pause

# 4. Resume work later
trix session resume sess_abc123
trix mem create "Added dark mode support"

# 5. Complete the project with summary
trix session complete --summary "Successfully launched redesigned apps with 95% positive feedback"

Task Workflow

Quick task tracking for focused work:

# Create and switch in one go
trix session create "Fix login bug #1234" --type task
trix session switch "Fix login bug"

# Do the work
trix mem create "Bug caused by expired JWT tokens"
trix mem create "Solution: Added token refresh logic"

# Complete when done
trix session complete --summary "Fixed JWT expiration handling"

Conversation Workflow

Track AI assistant conversations:

# Create conversation session
trix session create "Support Chat - User #5678" \
  --type conversation \
  --origin-type "zendesk"

# Log conversation memories
trix mem create "User reported slow page loads" --session current
trix mem create "Recommended clearing browser cache" --session current
trix mem create "Issue resolved after cache clear" --session current

# Complete with resolution summary
trix session complete --summary "Cache issue resolved successfully"

Best Practices

Session Naming

Be descriptive: "Q4 Marketing Campaign" not "Project 1"
Include context: "Support Chat - Customer #1234" helps filtering
Use consistent patterns: Team conventions make searching easier
Add dates when relevant: "Weekly Standup 2024-01-15"

Organizing Sessions

Use tags: Group related sessions with tags like "q4", "frontend", "bugs"
Choose appropriate types: Session type affects filtering and display
Link to spaces: Use --space to organize by project/team
Add origin metadata: Track where sessions came from (CLI, API, integration)

Lifecycle Management

Pause inactive sessions: Prevents accidental memory additions
Complete finished work: Add summaries for future reference
Use retention policies: Automatically cleanup temporary sessions
Review before archiving: Archived sessions are hidden from default views

Privacy Considerations

Use private sessions: Add --private for sensitive work
Set retention policies: Temporary sessions auto-delete after completion
Review session metadata: Ensure descriptions don't leak sensitive info

Private sessions and their memories are only visible to the creator and account admins. Use this for personal work or sensitive conversations.

Retention Policies

Control how long sessions and their memories persist:

Policy	Behavior	Best For
`permanent`	Never auto-delete (default)	Important projects, long-term conversations
`temporary`	Delete after completion	Demos, experiments, one-off tasks
`auto_delete`	Delete after N days of inactivity	Short-term projects, temporary contexts
`on_completion`	Archive immediately when completed	Support tickets, task tracking

# Permanent session (default)
trix session create "Important Project" --retention permanent

# Auto-delete after 30 days of inactivity
trix session create "Temp Work" \
  --retention auto_delete \
  --retention-days 30

# Delete immediately after completion
trix session create "Demo Session" --retention temporary

Finding and Filtering Sessions

List and filter sessions to find what you need:

# List all sessions
trix session list

# Filter by status
trix session list --status active
trix session list --status completed

# Filter by type
trix session list --type project
trix session list --type conversation

# Filter by tags
trix session list --tags "q4,frontend"

# Search by name/description
trix session list --search "customer support"

# Combine filters
trix session list --type project --status active --tags "frontend"

# Sort and paginate
trix session list --sort created_at --order desc --limit 50

# Get session details
trix session get sess_abc123

# View session memories
trix mem list --session sess_abc123

Next Steps

TypeScript SDK - Sessions API for Node.js/TypeScript
Python SDK - Sessions API for Python applications
C# SDK - Sessions API for .NET applications
CLI Sessions Reference - Complete command documentation
Sessions API Reference - REST API endpoints
Memory Commands - Session-aware memory operations
Spaces - Combine sessions with spaces for organization