Skip to main content
/ Docs
Quickstart API SDKs

Python SDK

Complete reference for the official Trix Python SDK.

Updated

Overview

The official Trix Python SDK provides a fully-typed client for integrating memory capabilities into your Python applications. Built on httpx and pydantic, it offers both synchronous and asynchronous clients with comprehensive type hints and automatic validation.

Key Features

  • Full type hints - Complete type annotations with Pydantic models
  • Sync and async - Both Trix and AsyncTrix clients
  • Automatic retries - Exponential backoff with jitter
  • Auto-pagination - Iterate through results with iter() methods
  • Context managers - Proper resource cleanup with with statements
  • Interceptors - Hook into request/response lifecycle

If you're using TypeScript or C#, check out the TypeScript SDK or C# SDK. For direct HTTP access, see the REST API.

Installation

Install the SDK using pip or your preferred package manager:

pip install trixdb

Requirements

  • Python 3.9+
  • httpx >= 0.25.0
  • pydantic >= 2.0.0

Initialization

Basic Setup

basic.py 
from trix import Trix

client = Trix(api_key="gdb_your_api_key")

From Environment Variables

The SDK can automatically read configuration from environment variables:

from_env.py 
from trix import Trix

# Uses TRIX_API_KEY environment variable
client = Trix.from_env()

# Or specify a custom environment variable
client = Trix.from_env(env_var="MY_TRIX_KEY")

Context Manager

Use the context manager for automatic resource cleanup:

context_manager.py 
from trix import Trix

with Trix(api_key="gdb_your_api_key") as client:
    memory = client.memories.create(content="Hello, Trix!")
    # Connection automatically closed when exiting the block

Full Configuration

full_config.py 
from trix import Trix, RetryConfig, PoolConfig

client = Trix(
    # Authentication (one required)
    api_key="gdb_your_api_key",
    # jwt_token="your_jwt_token",      # Alternative: JWT auth

    # Optional settings
    base_url="https://api.trixdb.com",    # API endpoint
    timeout=30.0,                       # Request timeout in seconds
    max_retries=3,                      # Retry attempts for failed requests

    # Development options
    allow_insecure=False,               # Allow HTTP (local dev only)

    # Custom retry configuration
    retry_config=RetryConfig(
        max_retries=5,
        initial_delay=1.0,
        max_delay=60.0,
        exponential_base=2.0,
        jitter=True
    ),

    # Connection pool configuration
    pool_config=PoolConfig(
        max_connections=100,
        max_keepalive_connections=20,
        keepalive_expiry=5.0
    )
)

Configuration Options

Complete list of configuration options:

OptionTypeDefaultDescription
api_keystrNoneYour Trix API key (starts with gdb_)
jwt_tokenstrNoneJWT token for user-based auth
base_urlstr"https://api.trixdb.com"Base URL for API requests
timeoutfloat30.0Request timeout in seconds
max_retriesint3Maximum retry attempts
allow_insecureboolFalseAllow HTTP (development only)

Resources

The Trix client provides access to 33 resource managers:

resources.py 
client.memories        # Memory objects
client.relationships   # Connections between memories
client.clusters        # Groups of related memories
client.spaces          # Isolated knowledge spaces
client.graph           # Knowledge graph traversal
client.search          # Semantic search and embeddings
client.webhooks        # Event webhooks
client.agent           # Agent sessions and operations
client.feedback        # User feedback management
client.highlights      # Text highlights within memories
client.personas        # Persona management
client.sessions        # Session lifecycle management
client.resources       # Resource management
client.facts           # Fact storage and retrieval
client.entities        # Entity extraction and management
client.enrichments     # Memory enrichment operations
client.tasks           # Task management
client.goals           # Goal tracking
client.habits          # Habit tracking
client.bots            # Bot management
client.space_config    # Space configuration
client.workflows       # Workflow orchestration
client.invites         # Invite management
client.notes           # Note management
client.skills          # Skill management
client.templates       # Template management
client.crews           # Crew management
client.hubs            # Hub management
client.hub_roles       # Hub role management
client.files           # File management
client.presets         # Preset management
client.calendar        # Calendar integration

Quick Example

Here's a quick example to get you started:

quick_example.py 
from trix import Trix, MemoryType

# Initialize the client
with Trix.from_env() as client:
    # Create a memory
    memory = client.memories.create(
        content="Python is excellent for data science",
        type=MemoryType.TEXT,
        tags=["python", "data-science"]
    )
    print(f"Created: {memory.id}")

    # Search memories
    results = client.memories.list(
        q="data science",
        limit=5
    )
    for mem in results.data:
        print(f"Found: {mem.content[:50]}...")

SDK Reference

The Python SDK documentation is organized into the following sections:

Memories

Create, search, update, and delete memories
Graph & Relationships

Knowledge graph traversal and connections
Spaces & Clusters

Organize memories into spaces and clusters
Advanced

Async, error handling, and best practices

Next Steps