Skip to main content

​
Overview

The memory system stores routing decisions, learns user preferences, and provides analytics for intelligent model selection. All data is stored locally with optional compression.

​
Commands

​
init

Initialize the memory system and create required directory structure. 
switchAILocal memory init
Output: 
Initializing switchAILocal memory system...
✓ Memory system initialized successfully
  Base directory: ~/.switchailocal/memory
  Retention: 90 days
  Compression: true
  Max log size: 100 MB

Directory structure created:
  ~/.switchailocal/memory/
  ├── routing-history.jsonl
  ├── provider-quirks.md
  ├── user-preferences/
  ├── daily/
  └── analytics/

Memory system is ready to use!
Run this command once before using other memory features. The server will also auto-initialize on first use.

​
status

Show memory system health, disk usage, and statistics. 
switchAILocal memory status
Output: 
switchAILocal Memory System Status
==================================
Status: ✓ Healthy
Base Directory: ~/.switchailocal/memory
Enabled: true

Statistics:
  Total Routing Decisions: 15,847
  Total Users: 23
  Total Provider Quirks: 12
  Disk Usage: 45.3 MB
  Newest Decision: 2026-03-09T14:32:18Z
  Oldest Decision: 2026-01-15T09:12:03Z

Configuration:
  Retention Days: 90
  Compression Enabled: true
  Last Cleanup: 2026-03-08T03:00:00Z

Daily Logs:
  Total Files: 53
  Total Entries: 15,847
  Disk Usage: 38.2 MB

Last Analytics Update: 2026-03-09T12:00:00Z

​
history

View recent routing decisions with detailed outcome information. 
switchAILocal memory history [--limit N] [--api-key-hash HASH]
​
--limit
integer
default:"100"
Maximum number of routing decisions to display.
​
--api-key-hash
string
Filter decisions by API key hash (specific user).
# Show last 100 decisions
switchAILocal memory history
Output: 
Recent Routing Decisions (limit: 100)
=====================================

[1] 2026-03-09T14:32:18Z
    API Key: sha256:a1b2c3d4...
    Model: gpt-4 → claude-sonnet-4
    Intent: code_generation
    Tier: premium (confidence: 0.92)
    Latency: 145ms
    Outcome: ✓ Success: true, Response: 2341ms, Quality: 0.95

[2] 2026-03-09T14:28:03Z
    API Key: sha256:e5f6g7h8...
    Model: gpt-3.5-turbo → gemini-pro
    Intent: chat
    Tier: standard (confidence: 0.78)
    Latency: 89ms
    Outcome: ✓ Success: true, Response: 1102ms, Quality: 0.88

[3] 2026-03-09T14:25:47Z
    API Key: sha256:a1b2c3d4...
    Model: claude-3-opus → claude-sonnet-4
    Intent: analysis
    Tier: premium (confidence: 0.85)
    Latency: 112ms
    Outcome: ✗ Success: false, Error: Rate limit exceeded

Showing 3 of 3 decisions

​
preferences

View learned user preferences for model selection. 
switchAILocal memory preferences --api-key KEY | --api-key-hash HASH
​
--api-key
string
API key to look up preferences. The key is hashed internally for security.
​
--api-key-hash
string
Pre-computed API key hash (SHA-256 format).
Either --api-key or --api-key-hash is required.
switchAILocal memory preferences --api-key sk-test-abc123xyz
Output: 
User Preferences for API Key: sha256:a1b2c3d4...
==========================================
Last Updated: 2026-03-09T12:00:00Z

Model Preferences:
  code_generation → claude-sonnet-4
  chat → gemini-pro
  analysis → gpt-4-turbo
  creative_writing → claude-opus-4

Provider Bias:
  anthropic: +0.15
  google: +0.08
  openai: -0.05
  ollama: -0.12

Custom Rules:
  [1] temperature > 0.8 → claude-opus-4 (priority: 10)
  [2] max_tokens > 4000 → gpt-4-turbo (priority: 8)
  [3] tool_use == true → claude-sonnet-4 (priority: 9)
Preferences are learned automatically based on routing history. Higher confidence and success rates strengthen preferences.

​
reset

Permanently delete all memory data. Creates automatic backup before reset. 
switchAILocal memory reset --confirm
​
--confirm
boolean
required
Confirmation flag required to prevent accidental data loss.
Without --confirm: 
⚠️  WARNING: This will permanently delete all memory data including:
  • Routing history
  • User preferences
  • Provider quirks
  • Daily logs
  • Analytics data

Use --confirm flag to proceed with reset.

💡 Tip: Use 'switchAILocal memory export' to create a backup first.
With --confirm: 
Creating automatic backup before reset...
Backup file: memory-backup-before-reset-20260309-143218.tar.gz
✓ Backup created successfully: memory-backup-before-reset-20260309-143218.tar.gz

Proceeding with reset...
✓ Memory system reset successfully
  Removed directory: ~/.switchailocal/memory
  Backup available: memory-backup-before-reset-20260309-143218.tar.gz

💡 Run 'switchAILocal memory init' to reinitialize the memory system.
💡 To restore from backup: tar -xzf memory-backup-before-reset-20260309-143218.tar.gz -C ~/
This operation cannot be undone. All routing history, preferences, and analytics will be permanently deleted.

​
export

Create a compressed backup of all memory data. 
switchAILocal memory export [--output FILE]
​
--output
string
Output filename for the backup archive. Defaults to switchailocal-memory-YYYYMMDD-HHMMSS.tar.gz.
# Creates timestamped backup file
switchAILocal memory export
Output: 
Exporting memory data to: switchailocal-memory-20260309-143245.tar.gz
✓ Export completed successfully
  Archive size: 45.3 MB
  Contains all memory data from: ~/.switchailocal/memory
Restore from backup: 
# Extract backup to home directory
tar -xzf switchailocal-memory-20260309-143245.tar.gz -C ~/

​
Configuration

Memory settings are configured in config.yaml: 
memory:
  enabled: true
  retention_days: 90
  max_log_size_mb: 100
  compression: true
  base_dir: "~/.switchailocal/memory"
​
enabled
boolean
default:"true"
Enable or disable the memory system.
​
retention_days
integer
default:"90"
Number of days to keep routing history before automatic cleanup.
​
max_log_size_mb
integer
default:"100"
Maximum size of log files before rotation (MB).
​
compression
boolean
default:"true"
Enable gzip compression for daily logs.
​
base_dir
string
default:"~/.switchailocal/memory"
Base directory for all memory data.

​
Data Structure

The memory system organizes data as follows: 
~/.switchailocal/memory/
├── routing-history.jsonl       # Main routing decision log (JSONL)
├── provider-quirks.md          # Known provider-specific behaviors
├── user-preferences/           # Per-user learned preferences
│   ├── sha256_abc123.json
│   └── sha256_def456.json
├── daily/                      # Compressed daily logs
│   ├── 2026-03-08.jsonl.gz
│   ├── 2026-03-09.jsonl.gz
│   └── ...
└── analytics/                  # Aggregated analytics
    ├── provider-stats.json
    ├── model-performance.json
    └── user-patterns.json

​
Troubleshooting

# Initialize the memory system
switchAILocal memory init
Check current disk usage:
switchAILocal memory status
Reduce retention period in config:
memory:
  retention_days: 30  # Reduce from 90 to 30 days
Ensure write permissions:
# Check permissions
ls -la ~/.switchailocal/memory

# Fix if needed
chmod -R 700 ~/.switchailocal/memory