REST API: Sessions

Manage activation sessions for tracking memory co-access patterns in the Trix REST API.

Updated Oct 6, 2026

Overview

Sessions track memory co-access patterns, grouping memories that are accessed together during a single interaction or workflow. Use sessions to understand which memories are frequently retrieved together and to export or report on memory activity.

Sessions are automatically created by the co-activation tracking system. Use the API to list, inspect, and export session data.

List Sessions

Retrieve a paginated list of sessions with optional filtering by status and date:

const sessions = await trix.sessions.list({ limit: 20, sort: 'started_at', order: 'desc' });

Query Parameters

limit — Number of results (1-100, default: 20)
offset — Pagination offset (default: 0)
is_closed — Filter by closed/active status (boolean)
since — Only sessions started after this ISO 8601 timestamp
sort — Sort field: started_at or last_activity_at
order — Sort direction: asc or desc

response.json

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "session_key": "session_abc123",
      "started_at": "2026-04-01T10:00:00Z",
      "last_activity_at": "2026-04-01T10:45:00Z",
      "memory_count": 12,
      "is_closed": false
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Get Active Sessions

Retrieve only currently active (unclosed) sessions:

get-active-sessions.sh

curl "https://api.trixdb.com/v1/sessions/active?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Session Details

Retrieve full details of a specific session, including the list of memory IDs:

const session = await trix.sessions.get('SESSION_ID');

response.json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "session_key": "session_abc123",
  "started_at": "2026-04-01T10:00:00Z",
  "last_activity_at": "2026-04-01T10:45:00Z",
  "memory_ids": ["mem_abc123", "mem_def456", "mem_ghi789"],
  "is_closed": false,
  "api_key_id": "key_xyz"
}

Get Session Memories

Retrieve the full memory objects associated with a session, with pagination:

const memories = await trix.sessions.memories('SESSION_ID', { limit: 50 });

response.json

{
  "data": [
    {
      "id": "mem_abc123",
      "content": "User discussed project deadlines for Q2",
      "tags": ["project", "deadlines"],
      "created_at": "2026-04-01T10:05:00Z",
      "content_type": "text"
    }
  ],
  "pagination": {
    "total": 12,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Soft-deleted memories are automatically excluded from session memory results.

Export Session

Export all session data including memories, relationships, facts, and entities. Supported formats: markdown, json, csv, and html.

export-session.sh

curl "https://api.trixdb.com/v1/sessions/SESSION_ID/export?format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o session-export.json

The export includes session metadata, a timeline of memories, extracted facts, entity profiles, enrichment status, and inter-memory relationships.

Generate Session Report

Generate a formatted report with auto-generated summary, timeline, statistics, and optional relationship data:

session-report.sh

curl "https://api.trixdb.com/v1/sessions/SESSION_ID/report?include_relationships=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

response.json

{
  "report": {
    "generated_at": "2026-04-02T12:00:00Z",
    "session": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "started_at": "2026-04-01T10:00:00Z",
      "ended_at": "2026-04-01T10:45:00Z",
      "is_closed": false,
      "duration_minutes": 45
    },
    "summary": {
      "description": "Session in progress with 12 memories recorded over 45 minutes.",
      "duration": "45 minutes",
      "key_topics": ["project", "deadlines"],
      "status": "active"
    },
    "statistics": {
      "total_memories": 12,
      "total_relationships": 3,
      "top_tags": [{ "tag": "project", "count": 8 }]
    }
  }
}