Sessions API

Overview

Sessions track which memories are accessed together during a conversation or task. This co-activation data powers Trix's learning system, helping it understand which memories are contextually related and should be retrieved together.

List Sessions

GET /sessions — List activation sessions

Returns a paginated list of activation sessions, showing which memories were accessed together.

Query Parameters

Response (200)

Returns { data: [...], pagination: { total, limit, offset, has_more } }.

curl -X GET "https://api.trixdb.com/v1/sessions?limit=10" \
  -H "Authorization: Bearer $TRIX_API_KEY"

{
  "data": [
    {
      "id": "<uuid>",
      "session_key": "conversation_12345",
      "started_at": "2026-04-10T10:30:00Z",
      "last_activity_at": "2026-04-10T10:45:00Z",
      "memory_count": 3,
      "is_closed": false
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Get Active Sessions

GET /sessions/active — Get currently active sessions

Returns all sessions that are still open (not yet closed). Useful for monitoring ongoing conversations.

Query Parameters

Response (200)

Returns { data: [...], pagination: { total, limit, offset, has_more } } ordered by most recent activity.

{
  "data": [
    {
      "id": "<uuid>",
      "session_key": "agent_task_789",
      "started_at": "2026-04-14T10:30:00Z",
      "last_activity_at": "2026-04-14T10:55:00Z",
      "memory_count": 2,
      "is_closed": false
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Get Session

GET /sessions/:id — Get session details

Retrieves detailed information about a specific activation session.

Path Parameters

Response (200)

Returns the session object with full details (including the memory_ids array).

{
  "id": "<uuid>",
  "session_key": "conversation_12345",
  "started_at": "2026-04-10T10:30:00Z",
  "last_activity_at": "2026-04-10T10:45:00Z",
  "memory_ids": ["<uuid>", "<uuid>", "<uuid>"],
  "is_closed": true,
  "api_key_id": "<uuid>"
}

Get Session Memories

GET /sessions/:id/memories — Get memories from a session

Returns the full memory objects that were accessed during a session, ordered by access time.

Path Parameters

Query Parameters

Response (200)

Returns { data: [...], pagination: { total, limit, offset, has_more } }.

{
  "data": [
    {
      "id": "<uuid>",
      "content": "User prefers dark mode and compact layouts",
      "content_type": "text",
      "tags": [],
      "created_at": "2026-04-04T09:00:00Z"
    },
    {
      "id": "<uuid>",
      "content": "Project uses React with TypeScript",
      "content_type": "text",
      "tags": [],
      "created_at": "2026-04-06T14:00:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Export & Report

GET /sessions/:id/export — Export session data

Exports session metadata, memories, and relationships in Markdown, JSON, CSV or HTML.

Query Parameters

GET /sessions/:id/report — Get a session report

Returns a structured report summarising the session's memories and optional relationships.

Query Parameters

Session Object

The session object contains the following fields:

How Sessions Work

Automatic Session Management

Sessions are managed automatically by the Trix API:

• A new session starts when you make a search or recall request with a session parameter
• Each memory returned in the search results is added to the session
• Sessions close automatically after a period of inactivity (default: 30 minutes)
• Co-accessed memories strengthen their relationships over time

Using Sessions in Your App

Pass a consistent session identifier to track memory access patterns:

// Each conversation gets a unique session
const sessionId = `conversation_${conversationId}`;

// All searches in this conversation share the session
const memories = await trix.search("user preferences", {
  session: sessionId
});

Use Cases

Conversation Memory

Track which memories are accessed together in a conversation to improve future recall:

• Memories frequently accessed together get higher co-activation scores
• Future searches prioritize memories that commonly appear together

Agent Task Learning

Track memory patterns during agent tasks to learn successful strategies:

• Identify which knowledge combinations lead to successful task completion
• Replay sessions to understand agent decision-making

Analytics

Analyze session data to understand memory usage patterns:

• Which memories are most frequently accessed together
• Average session duration and memory count
• Identify underutilized or orphaned memories