Marc Rejohn Castillano 5cb6561924 added ruflo

2026-04-09 19:01:53 +08:00

11 KiB

Raw Blame History

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:

agentdb run hnsw-test
agentdb analyze results.json

v2.0:

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):

{
  "hnswM": 16,
  "searchEf": 50,
  "outputPath": "./results"
}

v2.0 (.agentdb.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:

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:

agentdb migrate reports ./results/

This will:

Scan the ./results/ directory for JSON report files
Parse each report and extract metrics
Insert into SQLite database
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

# Backup configuration
cp .agentdbrc .agentdbrc.backup

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

Step 2: Install v2.0

# Uninstall v1.x
npm uninstall -g agentdb

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

Step 3: Verify Installation

agentdb --version
# Should output: 2.0.0

Step 4: Migrate Configuration

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

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

# 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:

#!/bin/bash
agentdb run hnsw-test
agentdb analyze results.json

After:

#!/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:

# 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

agentdb simulate --wizard

Guides you through configuration with interactive prompts.

3. Custom Builder

agentdb simulate --custom

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

4. Report Comparison

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

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

5. Trend Analysis

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

# Detect regressions
agentdb simulate --check-regressions

6. Health Monitoring

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

7. Plugin Support

# 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:

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:

{
  "scenario": "hnsw-test",
  "timestamp": "2024-01-01T00:00:00Z",
  "metrics": {
    "recall": 0.92,
    "latency": 150
  }
}

v2.0 Database:

-- 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:

Use default configuration for missing config_json
Generate synthetic insights if none exist
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

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

Step 2: Uninstall v2.0

npm uninstall -g agentdb

Step 3: Reinstall v1.x

npm install -g agentdb@1.x

Step 4: Verify

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:

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:

agentdb validate config .agentdb.json

Issue: Report Import Failures

Error:

Failed to import report: Invalid JSON format

Solution: Manually inspect the problematic report file:

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:

ps aux | grep agentdb
kill <pid>

Best Practices

1. Test in Development First

Before migrating production data:

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

2. Use Version Control

# 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

# 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:

# 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 for details.

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

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:

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

See the Deployment Guide 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:

Check the Troubleshooting section above
Review the GitHub Issues
Ask for help on Discord

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

11 KiB Raw Blame History

AgentDB v2.0 Migration Guide

Overview

Breaking Changes

1. CLI Command Structure

2. Configuration File Format

3. Report Storage

4. Scenario Naming

Step-by-Step Migration

Step 1: Backup Existing Data

Step 2: Install v2.0

Step 3: Verify Installation

Step 4: Migrate Configuration

Step 5: Migrate Reports

Step 6: Verify Migration

Step 7: Update Scripts

New Features in v2.0

1. Configuration Profiles

2. Interactive Wizard

3. Custom Builder

4. Report Comparison

5. Trend Analysis

6. Health Monitoring

7. Plugin Support

Configuration Migration Details

Automatic Upgrades

Manual Overrides

Report Migration Details

Report Schema Mapping

Handling Missing Data

Rollback Plan

Step 1: Restore Backups

Step 2: Uninstall v2.0

Step 3: Reinstall v1.x

Step 4: Verify

Troubleshooting

Issue: Migration Tool Not Found

Issue: Configuration Validation Errors

Issue: Report Import Failures

Issue: Database Locked

Best Practices

1. Test in Development First

2. Use Version Control

3. Validate After Migration

4. Update Documentation

FAQ

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

Q: Will migration preserve my custom scenarios?

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

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

Q: What happens to my custom HNSW parameters?

Support

11 KiB

Raw Blame History