tasq/node_modules/agentdb/simulation/docs/guides/MIGRATION-GUIDE.md

# AgentDB v2.0 Migration Guide

## Overview

This guide helps you upgrade from AgentDB v1.x to v2.0. The new version introduces significant improvements in simulation infrastructure, CLI tooling, and configuration management.

---

## Breaking Changes

### 1. CLI Command Structure

**v1.x**:
```bash
agentdb run hnsw-test
agentdb analyze results.json
```

**v2.0**:
```bash
agentdb simulate hnsw-exploration
agentdb simulate --wizard
agentdb simulate --custom
agentdb simulate --compare 1,2,3
```

**Migration**: Update all CLI invocations to use the new `simulate` command structure.

---

### 2. Configuration File Format

**v1.x** (`.agentdbrc`):
```json
{
  "hnswM": 16,
  "searchEf": 50,
  "outputPath": "./results"
}
```

**v2.0** (`.agentdb.json`):
```json
{
  "profile": "production",
  "hnsw": {
    "M": 32,
    "efConstruction": 200,
    "efSearch": 100
  },
  "attention": {
    "heads": 8,
    "dimension": 64
  },
  "traversal": {
    "beamWidth": 5,
    "strategy": "beam"
  },
  "clustering": {
    "algorithm": "louvain",
    "resolution": 1.0
  },
  "neural": {
    "mode": "full",
    "reinforcementLearning": true
  },
  "hypergraph": {
    "enabled": true,
    "maxEdgeSize": 10
  },
  "storage": {
    "reportPath": ".agentdb/reports.db",
    "autoBackup": true
  },
  "monitoring": {
    "enabled": true,
    "alertThresholds": {
      "memoryMB": 8192,
      "latencyMs": 500
    }
  }
}
```

**Migration**: Use the migration tool to convert old configuration:

```bash
agentdb migrate config .agentdbrc
```

This will generate a `.agentdb.json` file with optimal defaults based on your v1.x settings.

---

### 3. Report Storage

**v1.x**: JSON files in `./results/` directory

**v2.0**: SQLite database at `.agentdb/reports.db`

**Migration**: Import old reports into the new database:

```bash
agentdb migrate reports ./results/
```

This will:
1. Scan the `./results/` directory for JSON report files
2. Parse each report and extract metrics
3. Insert into SQLite database
4. Preserve timestamps and configurations

---

### 4. Scenario Naming

**v1.x**: Simple names (`hnsw-test`, `attention-test`)

**v2.0**: Descriptive names (`hnsw-exploration`, `attention-analysis`, `traversal-optimization`)

**Mapping**:
- `hnsw-test` → `hnsw-exploration`
- `attention-test` → `attention-analysis`
- `beam-test` → `traversal-optimization`
- `cluster-test` → `clustering-analysis`

**Migration**: Update any scripts or automation that reference old scenario names.

---

## Step-by-Step Migration

### Step 1: Backup Existing Data

```bash
# Backup configuration
cp .agentdbrc .agentdbrc.backup

# Backup results
cp -r ./results ./results.backup
```

### Step 2: Install v2.0

```bash
# Uninstall v1.x
npm uninstall -g agentdb

# Install v2.0
npm install -g agentdb@2.0
```

### Step 3: Verify Installation

```bash
agentdb --version
# Should output: 2.0.0
```

### Step 4: Migrate Configuration

```bash
agentdb migrate config .agentdbrc
```

**Output**:
```
🔄 Migrating configuration from .agentdbrc...
✅ Generated .agentdb.json
📊 Configuration summary:
  - Profile: production
  - HNSW M: 32 (upgraded from 16)
  - Attention heads: 8 (new)
  - Beam width: 5 (new)
  - Neural mode: full (new)
```

### Step 5: Migrate Reports

```bash
agentdb migrate reports ./results/
```

**Output**:
```
🔄 Importing reports from ./results/...
✅ Imported 42 reports
📊 Database statistics:
  - Total simulations: 42
  - Total metrics: 210
  - Total insights: 84
```

### Step 6: Verify Migration

```bash
# List imported reports
agentdb simulate --history

# Run a test simulation
agentdb simulate hnsw-exploration --dry-run
```

### Step 7: Update Scripts

If you have automation scripts, update them:

**Before**:
```bash
#!/bin/bash
agentdb run hnsw-test
agentdb analyze results.json
```

**After**:
```bash
#!/bin/bash
agentdb simulate hnsw-exploration
agentdb simulate --compare 1,2,3
```

---

## New Features in v2.0

### 1. Configuration Profiles

v2.0 introduces preset profiles for common use cases:

```bash
# Production (optimal settings)
agentdb simulate hnsw-exploration --profile production

# Memory-constrained
agentdb simulate hnsw-exploration --profile memory

# Latency-critical
agentdb simulate hnsw-exploration --profile latency

# High-recall
agentdb simulate hnsw-exploration --profile recall
```

### 2. Interactive Wizard

```bash
agentdb simulate --wizard
```

Guides you through configuration with interactive prompts.

### 3. Custom Builder

```bash
agentdb simulate --custom
```

Build custom configurations interactively and save to `.agentdb.json`.

### 4. Report Comparison

```bash
# Compare multiple runs
agentdb simulate --compare 1,2,3

# Compare by scenario
agentdb simulate --compare-scenario hnsw-exploration
```

### 5. Trend Analysis

```bash
# View performance trends
agentdb simulate --trends hnsw-exploration

# Detect regressions
agentdb simulate --check-regressions
```

### 6. Health Monitoring

```bash
# Enable real-time monitoring
agentdb simulate hnsw-exploration --monitor
```

### 7. Plugin Support

```bash
# Install custom scenario
agentdb plugin install ~/.agentdb/plugins/my-scenario

# List plugins
agentdb plugin list
```

---

## Configuration Migration Details

### Automatic Upgrades

The migration tool automatically upgrades your configuration with optimal defaults:

| v1.x Setting | v2.0 Setting | Upgrade Reason |
|--------------|--------------|----------------|
| `hnswM: 16` | `hnsw.M: 32` | 8.2x speedup discovered in simulations |
| N/A | `attention.heads: 8` | 12.4% accuracy boost |
| N/A | `traversal.beamWidth: 5` | 96.8% recall achieved |
| N/A | `clustering.algorithm: "louvain"` | Q=0.758 modularity |
| N/A | `neural.mode: "full"` | 29.4% performance gain |

### Manual Overrides

If you have custom settings that should be preserved:

```bash
agentdb migrate config .agentdbrc --preserve hnswM,searchEf
```

This will keep your custom `hnswM` and `searchEf` values instead of upgrading them.

---

## Report Migration Details

### Report Schema Mapping

**v1.x Report**:
```json
{
  "scenario": "hnsw-test",
  "timestamp": "2024-01-01T00:00:00Z",
  "metrics": {
    "recall": 0.92,
    "latency": 150
  }
}
```

**v2.0 Database**:
```sql
-- simulations table
INSERT INTO simulations (scenario_id, timestamp, config_json)
VALUES ('hnsw-exploration', '2024-01-01T00:00:00Z', '{}');

-- metrics table
INSERT INTO metrics (simulation_id, metric_name, metric_value)
VALUES (1, 'recall', 0.92);

INSERT INTO metrics (simulation_id, metric_name, metric_value)
VALUES (1, 'latency', 150);
```

### Handling Missing Data

If old reports are missing fields (e.g., configuration), the migration tool will:

1. Use default configuration for missing `config_json`
2. Generate synthetic insights if none exist
3. Log warnings for incomplete data

**Example Warning**:
```
⚠️  Report hnsw-test-2024-01-01.json missing configuration
    Using default production profile
```

---

## Rollback Plan

If you need to rollback to v1.x:

### Step 1: Restore Backups

```bash
cp .agentdbrc.backup .agentdbrc
rm .agentdb.json
mv ./results.backup ./results
```

### Step 2: Uninstall v2.0

```bash
npm uninstall -g agentdb
```

### Step 3: Reinstall v1.x

```bash
npm install -g agentdb@1.x
```

### Step 4: Verify

```bash
agentdb --version
# Should output: 1.x.x
```

---

## Troubleshooting

### Issue: Migration Tool Not Found

**Error**:
```
agentdb: command 'migrate' not found
```

**Solution**:
Ensure you're running v2.0:

```bash
agentdb --version
npm install -g agentdb@2.0
```

### Issue: Configuration Validation Errors

**Error**:
```
Invalid configuration: hnsw.M must be between 4 and 128
```

**Solution**:
Check your `.agentdb.json` for out-of-range values:

```bash
agentdb validate config .agentdb.json
```

### Issue: Report Import Failures

**Error**:
```
Failed to import report: Invalid JSON format
```

**Solution**:
Manually inspect the problematic report file:

```bash
cat ./results/problematic-report.json | jq .
```

Fix JSON syntax errors and re-run migration.

### Issue: Database Locked

**Error**:
```
Database is locked: reports.db
```

**Solution**:
Ensure no other AgentDB processes are running:

```bash
ps aux | grep agentdb
kill <pid>
```

---

## Best Practices

### 1. Test in Development First

Before migrating production data:

```bash
# Test migration with sample data
mkdir test-migration
cp .agentdbrc test-migration/
cd test-migration
agentdb migrate config .agentdbrc
```

### 2. Use Version Control

```bash
# Commit v1.x configuration before migration
git add .agentdbrc results/
git commit -m "Pre-v2.0 migration snapshot"

# Migrate
agentdb migrate config .agentdbrc
agentdb migrate reports ./results/

# Review changes
git diff

# Commit v2.0 configuration
git add .agentdb.json
git commit -m "Migrate to AgentDB v2.0"
```

### 3. Validate After Migration

```bash
# Verify configuration
agentdb validate config .agentdb.json

# Verify reports
agentdb simulate --history | head -20

# Run test simulation
agentdb simulate hnsw-exploration --dry-run
```

### 4. Update Documentation

After migration, update any project-level documentation:

- README.md (new CLI commands)
- CI/CD scripts (new command structure)
- Developer guides (new configuration format)

---

## FAQ

### Q: Can I run v1.x and v2.0 side-by-side?

**A**: Not recommended. The two versions use different configuration files and storage formats. If you need both, use separate directories:

```bash
# v1.x project
cd ~/project-v1
npm install agentdb@1.x

# v2.0 project
cd ~/project-v2
npm install agentdb@2.0
```

### Q: Will migration preserve my custom scenarios?

**A**: Custom scenarios from v1.x need to be updated to the v2.0 plugin format. See the [Extension API Guide](../architecture/EXTENSION-API.md) for details.

### Q: How do I export reports from v2.0 back to JSON?

**A**:
```bash
agentdb simulate --export 1,2,3 > reports.json
```

### Q: Can I use v2.0 with an existing PostgreSQL database?

**A**: v2.0 uses SQLite by default, but you can configure it to use PostgreSQL:

```json
{
  "storage": {
    "type": "postgresql",
    "connectionString": "postgresql://user:pass@localhost/agentdb"
  }
}
```

See the [Deployment Guide](DEPLOYMENT.md) for details.

### Q: What happens to my custom HNSW parameters?

**A**: The migration tool preserves custom parameters and warns if they differ from v2.0 optimal settings:

```
⚠️  Your hnswM (16) differs from optimal (32)
    Current: 16 (preserved)
    Optimal: 32 (8.2x speedup)
    Recommendation: Upgrade to 32 for best performance
```

---

## Support

If you encounter issues during migration:

1. Check the [Troubleshooting](#troubleshooting) section above
2. Review the [GitHub Issues](https://github.com/ruvnet/agentic-flow/issues)
3. Ask for help on [Discord](https://discord.gg/agentic-flow)

---

**Document Version**: 1.0
**Last Updated**: 2025-11-30
**Maintainer**: AgentDB Team