AI SUITE GUIDE

ai-admin Guide

Maintenance toolbox for the Kodachi AI system: SQLite database diagnostics, backup and restore, integrity checks, performance tuning, and schema migration.

Diagnostics Backup & restore DB tuning Migrations

ai-admin at a glance

ai-admin is the maintenance toolbox for the entire Kodachi AI system. It manages the SQLite database that stores training data, feedback, predictions, and learning history, providing diagnostics, backup and restore, optimization, and cleanup operations.

Version 9.8.4 3.9 MB binary Rust 1.82.0 SQLite maintenance

Reference and verification

This is a scenario-first guide: operational workflows, real run order, and troubleshooting. For the full autogenerated command and flag catalog, use the ai-admin CLI Reference, or read the raw signer JSON.

SHA256 (v9.8.4): 62b1961ea3cc086f3c429d446db5d94f9dbca82997eed3d234b0c1c2e47affd2

What ai-admin Does

ai-admin is the maintenance toolbox for the entire AI system. It manages the SQLite database that stores training data, feedback, predictions, and learning history. It provides diagnostics, backup/restore, optimization, and cleanup operations.

Key Capabilities

Feature	Description
Diagnostics	Full system health check for all AI components
Database Backup/Restore	Protect AI data with backups and recovery
Integrity Checks	Verify database consistency
Performance Tuning	Optimize queries, rebuild indexes, clean old data
Migration	Update database schema across versions

Scenario 1: Daily AI Health Check

Quick daily check to ensure the AI system is running correctly.

# Step 1: Run quick diagnostics
ai-admin diagnostics

# Step 2: If issues detected, run full diagnostics
ai-admin diagnostics --full

# Step 3: Check database integrity
ai-admin db integrity-check

# Step 4: View database statistics
ai-admin db info

# Step 5: Analyze recent learning trends
sudo ai-learner analyze

Cross-binary workflow: ai-admin + ai-learner

When to run: Daily, or immediately after noticing ai-cmd accuracy issues.

Scenario 2: Weekly Maintenance Routine

Keep the AI database healthy with regular maintenance.

# Step 1: Create a timestamped backup before any maintenance
ai-admin db backup --output ./backup-$(date +%Y%m%d).db

# Step 2: Check database integrity
ai-admin db integrity-check

# Step 3: Optimize database performance (VACUUM, analyze)
ai-admin tune optimize

# Step 4: Rebuild search indexes for faster queries
ai-admin tune rebuild-index

# Step 5: Clean data older than 30 days
ai-admin tune cleanup --days 30

# Step 6: Verify health after maintenance
ai-admin diagnostics --full

# Step 7: Confirm ai-cmd still works correctly
ai-cmd query "check network status"

Cross-binary workflow: ai-admin + ai-cmd + ai-scheduler

Automate this with ai-scheduler:

# Weekly maintenance on Sundays at 4 AM
ai-scheduler add --name "weekly-backup" \
  --command "ai-admin db backup --output ./backup-weekly.db" \
  --cron "0 4 * * 0"

ai-scheduler add --name "weekly-optimize" \
  --command "ai-admin tune optimize" \
  --cron "0 5 * * 0"

ai-scheduler add --name "weekly-cleanup" \
  --command "ai-admin tune cleanup --days 30" \
  --cron "0 6 * * 0"

Scenario 3: Recovery After Database Corruption

When the AI database becomes corrupted, restore from backup and rebuild.

# Step 1: Assess the damage
ai-admin diagnostics --full --json

# Step 2: If integrity check fails, restore from backup
ai-admin db restore --backup ./backup-20260209.db

# Step 3: Run migrations to ensure schema is current
ai-admin db migrate

# Step 4: Verify integrity after restore
ai-admin db integrity-check

# Step 5: Rebuild indexes
ai-admin tune rebuild-index

# Step 6: Retrain the model (embeddings may need refresh)
sudo ai-trainer train --data ./data/training-data.json

# Step 7: Validate the model
ai-trainer validate --test-data ./data/test-commands.json

# Step 8: Verify ai-cmd works end-to-end
ai-cmd query "check system health"

# Step 9: Check accuracy is restored
sudo ai-learner analyze

Cross-binary workflow: ai-admin + ai-trainer + ai-cmd + ai-learner

Scenario 4: Investigating AI Performance Issues

When ai-cmd accuracy drops, use ai-admin to check if the database is the root cause.

# Step 1: Run full diagnostics
ai-admin diagnostics --full

# Step 2: Check database integrity (corruption can cause bad predictions)
ai-admin db integrity-check

# Step 3: View database statistics
ai-admin db info --json

# Step 4: Optimize database if fragmented
ai-admin tune optimize

# Step 5: Analyze learning trends
sudo ai-learner analyze

# Step 6: Rebuild indexes if database issues detected
ai-admin tune rebuild-index

# Step 7: If accuracy is still low, consider full retraining
sudo ai-trainer train --data ./data/training-data.json

# Step 8: Generate a report for tracking
sudo ai-learner report

Cross-binary workflow: ai-admin + ai-learner + ai-trainer

Scenario 5: Pre- and Post-Training Database Care

Always prepare the database before training and clean up after.

Before Training

# Backup before any training operation
ai-admin db backup --output ./pre-training-$(date +%Y%m%d).db

# Check integrity to avoid training on corrupt data
ai-admin db integrity-check

# Optimize for best training performance
ai-admin tune optimize

After Training

# Rebuild indexes after training writes new data
ai-admin tune rebuild-index

# Clean up temporary data (keep last 90 days)
ai-admin tune cleanup --days 90

# Run diagnostics to verify health
ai-admin diagnostics --full

# Create post-training backup
ai-admin db backup --output ./post-training-$(date +%Y%m%d).db

Cross-binary workflow: ai-admin + ai-trainer

Scenario 6: Automated Maintenance Pipeline

Set up ai-scheduler to automate all database maintenance tasks.

# Daily: Database integrity check (1:00 AM)
ai-scheduler add --name "daily-integrity" \
  --command "ai-admin db integrity-check" \
  --cron "0 1 * * *"

# Weekly: Backup + optimize (Sundays 3:00-4:00 AM)
ai-scheduler add --name "weekly-backup" \
  --command "ai-admin db backup --output ./backup-weekly.db" \
  --cron "0 3 * * 0"

ai-scheduler add --name "weekly-optimize" \
  --command "ai-admin tune optimize" \
  --cron "0 4 * * 0"

# Monthly: Cleanup + rebuild indexes (1st of month 5:00-6:00 AM)
ai-scheduler add --name "monthly-cleanup" \
  --command "ai-admin tune cleanup --days 30" \
  --cron "0 5 1 * *"

ai-scheduler add --name "monthly-rebuild" \
  --command "ai-admin tune rebuild-index" \
  --cron "0 6 1 * *"

# Verify all scheduled tasks
ai-scheduler list

Cross-binary workflow: ai-admin + ai-scheduler

Complete automation (combine with learning pipeline):

# Full daily pipeline: Integrity → Learn → Monitor
# 1:00 AM - Database integrity check
# 2:00 AM - Incremental learning
# 3:00 AM - Security checks
ai-scheduler add --name "integrity" --command "ai-admin db integrity-check" --cron "0 1 * * *"
ai-scheduler add --name "learning" --command "ai-learner learn" --cron "0 2 * * *"
ai-scheduler add --name "security" --command "health-control security-score" --cron "0 3 * * *"

Database Maintenance & Health, Weekly and recovery workflows
Troubleshooting AI Accuracy, Using diagnostics to find root causes
ai-trainer, Pre/post-training database care
ai-learner, Learning depends on healthy database
Full CLI Reference: ai-admin commands

Troubleshooting

Problem	Cause	Solution
"Database locked" error	Another AI process is using the DB	Stop other ai-* processes, then retry
Integrity check fails	Corrupt database	Restore from backup: `ai-admin db restore --backup <backup-path>`
Diagnostics show warnings	Missing tables or stale data	Run `ai-admin db migrate` then `ai-admin tune optimize`
Backup fails	Insufficient disk space or permissions	Check free space and run with `sudo`
Migration errors	Version mismatch	Ensure all AI binaries are the same version (check with `-e`)