CLI: Cluster Management

Manage and monitor automatic memory clustering with the Trix CLI.

Updated Oct 6, 2026

Overview

Trix automatically groups related memories into clusters at multiple scales. The cluster commands let you view, manage, and trigger clustering operations. Use clusters to discover patterns and navigate large memory collections.

Command aliases: cluster, clusters, cl

Checking Cluster Status

View the current status of the clustering system:

# Check clustering status
trix cluster status

Example output:

Clustering Status
  Status: completed
  Algorithm: auto
  Min cluster size: 5

  Total memories: 156
  Memories clustered: 142
  Clusters found: 23

  Last run: 2 hours ago
  Next scheduled: Jan 16 00:00

Clustering runs automatically when you have enough memories. Use status to see if your memories are being clustered and when the next run is scheduled.

Listing Clusters

View clusters at different scales:

# List clusters at default scale
trix cluster list

# List at different scales
trix cluster list --scale fine      # Small, specific clusters (3-10 memories)
trix cluster list --scale medium    # Balanced clusters (10-50 memories)
trix cluster list --scale coarse    # Large, thematic clusters (50+ memories)

# Limit results
trix cluster list --scale fine --limit 10

# JSON output
trix cluster list -o json

Example output:

Clusters at medium scale (23 total):

1. Project Architecture (15 memories)
   Tags: adr, architecture, design
   Top topics: database, microservices, API design

2. Team Meetings (12 memories)
   Tags: meeting, standup, planning
   Top topics: Q1 planning, sprint reviews

3. API Documentation (9 memories)
   Tags: api, docs, reference
   Top topics: REST endpoints, authentication

...

Cluster Scales

Scale	Size	Use Case
`fine`	3-10 memories	Tightly related items, specific topics
`medium`	10-50 memories	Project-level groupings, balanced view
`coarse`	50+ memories	High-level themes, broad categories

Viewing Cluster Details

# Get cluster details
trix cluster get clus_abc123

# Include member memories
trix cluster get clus_abc123 --include-memories

# JSON output
trix cluster get clus_abc123 -o json

Example output:

Cluster: Project Architecture
ID: clus_abc123
Scale: medium
Members: 15 memories

Description: Architectural decisions and design documentation
             for the main application platform.

Top Tags: adr (12), architecture (15), design (8)
Top Topics: microservices, database selection, API patterns

Memories:
  1. mem_a1b2c3 - "ADR-001: Use PostgreSQL for..."
  2. mem_d4e5f6 - "Microservices vs Monolith decision..."
  3. mem_g7h8i9 - "API Gateway pattern selection..."
  ...

Triggering Clustering

Manually trigger clustering when you want immediate results:

# Trigger clustering for all memories
trix cluster trigger

# Trigger for a specific space
trix cluster trigger --space work

# Trigger for specific memories
trix cluster trigger --ids mem_abc123,mem_def456,mem_ghi789

# Check status after triggering
trix cluster status

Example output:

Clustering job queued
  Job ID: job_xyz789

Run 'trix cluster status' to check progress.

Clustering runs in the background. For large memory sets, it may take a few minutes to complete. Use trix cluster status to monitor progress.

Configuring Clustering

View and update clustering configuration:

# View current configuration
trix cluster config

# Update minimum cluster size
trix cluster config --min-size 5

# Change algorithm
trix cluster config --algorithm auto

# Update multiple settings
trix cluster config --min-size 3 --algorithm auto

Example configuration output:

Clustering Configuration
  Algorithm: auto
  Min cluster size: 5
  Auto-clustering: enabled
  Schedule: daily at 00:00 UTC

To update:
  trix cluster config --min-size=<n>
  trix cluster config --algorithm=<name>

When No Clusters Exist

If you don't have enough memories yet, the cluster list will show helpful guidance:

$ trix cluster list
No clusters found.

  Clustering Info:
    Status: Not yet run
    Minimum memories required: 50
    Your memories: 23

Add 27 more memories to enable automatic clustering.

When you have enough memories but clustering hasn't run:

$ trix cluster list
No clusters found.

  Clustering Info:
    Status: Pending
    Minimum memories required: 50
    Your memories: 75

  To trigger clustering manually:
    trix cluster trigger

  To check clustering status:
    trix cluster status

Searching with Clusters

Use cluster awareness when searching:

# Search with cluster expansion
trix recall "project ideas" --expand
trix recall "quarterly goals" --expand

# Get a memory with its details
trix memories get mem_abc123

Command Reference

Command	Description
`cluster list`	List clusters at specified scale
`cluster get <id>`	Get cluster details
`cluster status`	Show clustering status and statistics
`cluster trigger`	Manually trigger clustering
`cluster config`	View or update clustering configuration

List Options

Option	Description
`--scale`	Cluster scale: `fine`, `medium`, `coarse`
`--limit`	Maximum number of clusters to return
`--include-memories`	Include member memories in output

Config Options

Option	Description
`--min-size`	Minimum memories required to form a cluster
`--algorithm`	Clustering algorithm (e.g., auto)

Next Steps

Graph Export - Visualize cluster relationships
Memory Commands - Work with memories in clusters
Cluster Concepts - Understanding multi-scale clustering