session-maintenance

Session Maintenance

Diagnose, repair, and maintain the CASS installation including the search index, analytics rollup tables, semantic search models, and remote sources.

Quick Diagnostics

Health Check

Fast pre-flight check (<50ms):

cass health --json

Exit 0 = healthy, 1 = unhealthy. Use this before any search operation.

Detailed Status

cass status --json

Returns: index freshness, database stats, pending sessions, recommended action.

Full Diagnostics

cass diag --json --verbose

Returns: version, platform, database size, index size, connector status, paths.

Index Management

Rebuild the Index

# Incremental update (new sessions only)
cass index --json

# Full rebuild from scratch
cass index --full --json

# Build with semantic embeddings
cass index --full --semantic --json

# Build HNSW index for fast approximate search
cass index --full --semantic --build-hnsw --json

# Watch mode (re-index on changes)
cass index --watch --json

When to Rebuild

• cass health returns unhealthy
• cass status shows stale: true
• Search results seem incomplete or missing recent sessions
• After installing/updating CASS

Analytics Maintenance

Check Analytics Health

cass analytics status --json

Look at:

• data.coverage.api_token_coverage_pct — should be > 0% for meaningful token analytics
• data.drift.signals — any drift indicates inconsistency
• data.recommended_action — follow this

Validate Analytics Data

# Check for issues
cass analytics validate --json

# Auto-fix safe issues (Track A rollups only)
cass analytics validate --fix --json

Rebuild Analytics Rollups

# Rebuild when rollups are stale or corrupt
cass analytics rebuild --json

# Force rebuild even if rollups appear fresh
cass analytics rebuild --force --json

Repair Workflow

When analytics data is wrong:

# 1. Validate to identify issues
cass analytics validate --json

# 2. If errors found, try auto-fix first
cass analytics validate --fix --json

# 3. If auto-fix insufficient, force rebuild
cass analytics rebuild --force --json

# 4. Re-validate to confirm
cass analytics validate --json

Doctor

Automated diagnosis and repair:

# Diagnose issues (safe, read-only)
cass doctor

# Apply automatic repairs (rebuilds derived data, preserves sources)
cass doctor --fix

Doctor is safe by default — it never deletes user session data. The --fix flag only rebuilds derived data (index, rollups).

Semantic Search Models

List Available Models

cass models status --json

Model Setup

Semantic search requires embedding models. After downloading a model:

# Build semantic index
cass index --semantic --json

# Build HNSW for fast approximate search
cass index --semantic --build-hnsw --json

Daemon Management

For faster repeated semantic queries, use the daemon:

# Start the daemon (Unix only)
cass daemon

# Searches will auto-use daemon when available
cass search "concept" --mode semantic --daemon --json

Remote Sources

Setup Remote Sources

Interactive wizard for configuring multi-machine search:

# Interactive setup (recommended)
cass sources setup

# Specific hosts
cass sources setup --hosts css,csd

# Preview without changes
cass sources setup --dry-run

# Non-interactive (for scripting)
cass sources setup --non-interactive --hosts css,csd

Manage Sources

# List configured sources
cass sources list

# Sync data from all sources
cass sources sync

# Discover available hosts
cass sources discover

# Add a source manually
cass sources add user@hostname

Troubleshooting

Search Returns No Results

1. cass health --json — check if healthy
2. cass stats --json — check conversation/message counts
3. If counts are 0: cass index --full --json
4. If counts > 0 but no results: try broader query, remove filters

Analytics Shows No Data

1. cass analytics status --json — check coverage
2. If api_token_coverage_pct is 0: API tokens not available for your agents (content estimates still work)
3. If tables missing: cass analytics rebuild --json

Stale Index Warning

# Check how stale
cass status --json

# Refresh
cass index --json

# Or set up watch mode for automatic updates
cass index --watch

Database Errors (Exit Code 9)

# If retryable=true: transient lock, retry after 1s
# If retryable=false: schema issue
cass doctor --fix
cass index --full --json

Exit Codes

Code	Meaning	Action
0	Success	-
2	Usage error	Fix command flags
3	Missing database	Run cass index --full
9	Database error	Run cass doctor --fix

Best Practices

• Run cass health --json as a pre-flight check before search operations.
• Use cass doctor --fix as the first response to any CASS issue.
• Rebuild analytics after significant indexing: cass analytics rebuild --json.
• Set up cass index --watch for always-fresh index during active development.
• Use cass sources setup for multi-machine search — it handles SSH config discovery automatically.

Additional Resources

• Command Reference - Complete CASS CLI v0.2.7 reference