Skip to content

Upgrade & Uninstall

Upgrade

pip install --upgrade echo-agent[all]

Upgrade to a specific version:

pip install echo-agent[all]==0.3.8

cd echo-agent
git pull origin master
pip install -e ".[all]"

Pre-upgrade Checklist

Upgrade Notes

Breaking changes may occur between Beta versions. Before upgrading:

  1. Read the CHANGELOG for details on changes
  2. Back up your data directory
  3. Run database migration if required

Back up data:

# Default data directory location
cp -r ~/.echo-agent ~/.echo-agent.backup.$(date +%Y%m%d)

Database Migration

If the database schema has changed between versions, run the migration command after upgrading:

echo-agent migrate

Automatic Migration Detection

echo-agent run checks the schema version on startup. If migration is needed, it displays a prompt and refuses to start — run echo-agent migrate to resolve.

Checkpoint Recovery

If issues arise after upgrading, roll back to a previous checkpoint:

# List available checkpoints
echo-agent checkpoint list

# Restore a specific checkpoint
echo-agent checkpoint restore <checkpoint-id>

Uninstall

Package Only

pip uninstall echo-agent

Full Cleanup

Uninstall the package and remove all data:

# Uninstall Python package
pip uninstall echo-agent

# Remove data directory (config, database, memory)
rm -rf ~/.echo-agent

# If installed via the one-line script, also remove the venv
rm -rf ~/.echo-agent/venv
rm -f ~/.local/bin/echo-agent

Data is Unrecoverable

Deleting ~/.echo-agent permanently removes all data, including:

  • Configuration file (config.yaml)
  • Conversation history and memory database
  • Accumulated skills and evolution records
  • Scheduled task configurations

Make sure to back up important data before deletion.

Clean Up Playwright Browsers

If Playwright browser dependencies were installed:

# List installed browsers
playwright install --list

# Remove all Playwright browsers
rm -rf ~/.cache/ms-playwright        # Linux
rm -rf ~/Library/Caches/ms-playwright # macOS

Clean Up Frontend Build Artifacts

If you installed from source and built the frontend:

cd echo-agent/web
rm -rf node_modules dist

Downgrade

If a new version has issues and you need to roll back:

# Install a specific older version
Install the specific older version:

```bash
pip install echo-agent[all]==0.3.6

If echo-agent migrate run was applied during the upgrade, undo it with the matching command:

echo-agent migrate rollback

Checkpoints do not contain the database

echo-agent checkpoint is a shadow Git snapshot of workspace files, and its exclusion list explicitly covers the SQLite database, the sessions directory, the memory directory and the logs directory (a file-level snapshot of a live SQLite file would be a torn read). checkpoint restore therefore cannot restore database state.

Data-layer rollback has exactly two routes: echo-agent migrate rollback, or a database file you copied yourself beforehand. Copy data/echo_agent.db before downgrading.