Upgrade & Migrations

Safely upgrade Echo Agent and migrate data between versions.

---

Upgrade Process

# 1. Check current version
echo-agent --version

# 2. Stop the service
echo-agent gateway stop

# 3. Back up data
cp -r ~/.echo-agent ~/.echo-agent.bak

# 4. Upgrade
pip install --upgrade echo-agent

# 5. Run migrations
echo-agent migrate status
echo-agent migrate run

# 6. Restart
echo-agent gateway start

# 7. Verify
echo-agent status

Migration Commands

# Check pending migrations
echo-agent migrate status

# Run all pending migrations
echo-agent migrate run

# Dry-run (preview only)
echo-agent migrate run --dry-run

# Rollback last migration
echo-agent migrate rollback

# Migrate memory.md format (legacy)
echo-agent migrate memory-md

Configuration Migration

Configuration fields may be renamed or restructured between versions. Echo Agent automatically migrates known field changes during config loading.

Deprecated fields generate warnings:

WARNING: 'service' command is deprecated, use 'gateway <action>' instead

Rollback

If issues arise after upgrade:

echo-agent gateway stop
pip install echo-agent==0.3.6  # previous version
cp -r ~/.echo-agent.bak/* ~/.echo-agent/
echo-agent migrate rollback
echo-agent gateway start

Downgrades rely on your own backup

During Beta, schema downgrade is not guaranteed. echo-agent migrate rollback undoes the migrations it applied, but a release that reshapes data may leave a rollback unable to reconstruct the original state exactly.

That is why the sequence above copies the backup back before rolling back: the file copy is what actually restores the data, and migrate rollback reconciles the schema version afterwards. Skipping the backup step leaves you with no way back.

See compatibility for what each version step does guarantee.