AI-CLI Advanced Usage

Advanced Configuration

Fine-Tuning Importance Threshold

The default importance threshold is 6.0 (out of 10). Sessions scoring below this are not automatically stored. Adjust based on your needs:

• Lower threshold (5.0-5.5) - Capture more conversations, good for research or learning
• Default threshold (6.0) - Balanced approach, captures meaningful discussions
• Higher threshold (7.0-8.0) - Only critical conversations, keeps library very focused

To adjust the threshold, pass --threshold when manually processing sessions, or modify your hook configuration to use a custom threshold.

Optimizing Token Budget

The context injection token budget controls how much memory context is injected:

• Small budget (1000-1500) - Fast, minimal context, good for quick queries
• Default budget (2000) - Balanced, works for most use cases
• Large budget (4000-6000) - Comprehensive context, good for complex tasks

Set via hook configuration (--max-tokens) or environment variable (TRIX_AI_CLI_TOKEN_BUDGET).

Memory Limits

Control how many memories are injected with --max-memories:

• Few memories (3-5) - Focused, high-relevance context
• Default (5) - Good balance
• Many memories (10-15) - Broader context, may include less relevant items

Git Context Integration

How Git Detection Works

The AI-CLI integration automatically detects git repositories by:

1. Walking up from your current working directory
2. Looking for a .git folder
3. Extracting the repository name from the directory path
4. Using this as context for semantic search

This means memories are project-aware. Working in ~/projects/my-app? You'll get memories tagged with "my-app" preferentially.

Project-Based Memory Isolation

For stronger project isolation, use spaces:

# Create a space for your project
trix spaces create "project_alpha"

# Process sessions into this space
trix process-session --file session.jsonl --space "project_alpha"

# Inject context from this space only
trix inject-context "authentication" --space "project_alpha"

This ensures memories for different projects don't cross-contaminate.

Custom Workflows

Batch Processing Old Sessions

Process multiple historical transcripts:

# Process all JSONL files in a directory
for file in ~/ai-transcripts/*.jsonl; do
  echo "Processing $file..."
  trix process-session --file "$file" --auto-store
done

# Or with specific space
for file in project-transcripts/*.jsonl; do
  trix process-session --file "$file" --space "project_alpha"
done

Selective Storage with Filtering

Process sessions but only store those matching criteria:

# Process and only store if score >= 7.0
trix process-session --file session.jsonl --verbose | \
  jq -r 'select(.importance_score >= 7.0) | .memory_id'

# Process multiple, log scores to file
for file in *.jsonl; do
  trix process-session --file "$file" --verbose >> scores.log
done

Scripting with AI-CLI Commands

Build custom automation:

#!/bin/bash
# Auto-categorize sessions by importance

SESSION_FILE="$1"

# Get importance score
SCORE=$(trix process-session --file "$SESSION_FILE" --auto-store=false | jq -r '.importance_score')

if (( $(echo "$SCORE >= 8.0" | bc -l) )); then
  echo "High-value session! Score: $SCORE"
  trix process-session --file "$SESSION_FILE" --space "critical"
elif (( $(echo "$SCORE >= 6.0" | bc -l) )); then
  echo "Normal session. Score: $SCORE"
  trix process-session --file "$SESSION_FILE"
else
  echo "Low-value session. Score: $SCORE - skipping"
fi

Performance Optimization

Async vs. Synchronous Processing

Session capture hooks run asynchronously by default (--async flag):

Async (default):

• Non-blocking - AI CLI returns immediately
• Processing happens in background
• Best for interactive sessions
• Errors logged but don't interrupt workflow

Synchronous (no --async flag):

• Blocking - waits for processing to complete
• Immediate feedback on success/failure
• Good for debugging or scripts
• May slow down AI CLI session end

Token Budget Tuning

Balance context richness vs. injection speed:

• Faster injection: Lower token budget (1000-1500), fewer memories (3)
• Richer context: Higher token budget (4000-6000), more memories (10)

Measure impact with timing:

# Time context injection
time trix inject-context "query" --max-tokens 2000 --max-memories 5

# Compare with larger budget
time trix inject-context "query" --max-tokens 4000 --max-memories 10

Memory Search Optimization

For large memory libraries (1000+ memories):

• Use spaces to partition memories by project/topic
• Keep token budget reasonable (2000-4000)
• Limit memories to 5-10 for faster search
• Consider using tags for filtering

Troubleshooting

Hooks Not Triggering

Symptoms: Sessions complete but no capture/injection happens

Diagnosis:

# Check hook installation
trix integrations ai-cli status

# Verify trix is in PATH
which trix

# Test hook manually (Claude Code)
echo '{"transcript_path": "test.jsonl"}' | trix capture-session-hook

# Check AI CLI config
cat ~/.config/claude/config.json  # Claude Code
cat ~/.gemini/config.yaml          # Gemini CLI

Solutions:

• Reinstall hooks: trix integrations ai-cli setup --force
• Verify JSON/YAML syntax in config files
• Ensure trix executable is in PATH
• Check file permissions on config files

Sessions Not Being Stored

Symptoms: Hooks trigger but memories don't appear

Diagnosis:

# Process manually with verbose output
trix process-session --file session.jsonl --verbose

# Check importance score
trix process-session --file session.jsonl --auto-store=false | jq -r '.importance_score'

# Verify API authentication
trix auth status

# Check for stored memories
trix recall "recent session" --limit 10

Solutions:

• Check importance score - must be ≥ 6.0 for auto-storage
• Verify API key is valid: trix auth status
• Lower threshold if needed (edit hook config)
• Check API rate limits or quota

Context Not Appearing

Symptoms: Sessions start but no context is injected

Diagnosis:

# Test inject command manually
trix inject-context "test query" --verbose

# Check if relevant memories exist
trix recall "your topic" --limit 5

# Verify git detection
git rev-parse --show-toplevel  # Should show repo root
basename $(git rev-parse --show-toplevel)  # Project name

Solutions:

• Ensure you have stored memories: trix recall --limit 10
• Check if memories match your query (semantic search)
• Increase --max-memories or --max-tokens
• Verify hook timeout is sufficient (3000ms default)

Debug Mode

Enable verbose logging for all AI-CLI operations:

# Set debug environment variable
export TRIX_DEBUG=1

# Run AI CLI session - will show detailed logs
claude chat

# Check logs
tail -f ~/.trix/logs/ai-cli.log

Log File Locations

• AI-CLI logs: ~/.trix/logs/ai-cli.log
• Hook errors: ~/.trix/logs/hooks-error.log
• API errors: ~/.trix/logs/api.log

Best Practices

Choosing the Right Threshold

• Learning/Research: 5.0-5.5 - capture exploratory conversations
• General Use: 6.0 - good balance of signal vs. noise
• Production/Critical: 7.0-8.0 - only actionable, high-value content

Organizing Memories

• Use spaces for projects, clients, or contexts
• Let git detection handle sub-projects automatically
• Use tags in manual storage for categorization
• Regular cleanup: review low-importance memories periodically

Memory Quality Over Quantity

• Don't lower threshold too much - noise reduces value
• 5-10 highly relevant memories > 20 loosely related ones
• Use --verbose to understand scoring
• Delete outdated memories when projects evolve

Regular Maintenance

# Weekly: Review recent captures
trix recall --limit 20 --since 7d

# Monthly: Clean up low-value memories
trix list --tags "temporary" | jq -r '.data[].id' | xargs -I {} trix delete {}

# Check storage usage
trix spaces list  # Shows memory counts per space

Integration with Other Tools

With MCP Server

Combine AI-CLI integration with MCP for multi-channel memory:

• AI-CLI captures command-line sessions automatically
• MCP Server provides memories to desktop/IDE AI assistants
• Both write to the same memory library
• Seamless context across all your AI tools

With Daemon

Use the Trix daemon for real-time file watching:

• Daemon watches code files for changes
• AI-CLI captures development conversations
• Combined: context from both code and discussions

With CI/CD

Process session transcripts in CI pipelines:

# GitHub Actions example
name: Process AI Sessions
on: [push]

jobs:
  process-sessions:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Trix CLI
        run: curl -fsSL https://install.trixdb.com | sh
      - name: Process sessions
        env:
          TRIX_API_KEY: ${{ secrets.TRIX_API_KEY }}
        run: |
          for file in sessions/*.jsonl; do
            trix process-session --file "$file" --space "ci-pipeline"
          done

Security & Privacy

What Data is Captured?

• Full conversation transcript (user messages + AI responses)
• Session metadata (timestamp, provider, git context)
• Extracted topics and entities
• Importance score and components

Where is Data Stored?

• Memories are stored in Trix cloud (encrypted at rest)
• Transcripts are processed via API (TLS in transit)
• Local transcripts are not deleted after processing
• You control retention via API

Controlling Sensitive Information

To prevent sensitive data from being captured:

• Disable auto-store: Review before storing manually
• Use project configs: Disable integration for sensitive projects
• Environment filtering: Only enable in development, not production
• Manual review: Use --auto-store=false and review scores

# Disable auto-store for sensitive projects
# Edit hook config to remove --async and review manually
trix process-session --file session.jsonl --auto-store=false --verbose

# Only store if you approve
trix process-session --file session.jsonl  # Stores if score >= 6.0

Data Retention

You control how long memories are kept:

• No automatic expiration - memories persist until deleted
• Delete manually: trix delete <memory-id>
• Bulk delete: Filter and delete multiple memories
• Space deletion: trix spaces delete <space-id> removes all memories

Next Steps

• Overview - Return to AI-CLI integration overview
• Setup & Configuration - Re-configure your integration
• Connection Management - Manage third-party integrations
• MCP Server - Add memory to desktop AI assistants
• Daemon - Automate memory capture from files