Hermes: 备份与迁移

核心内容

备份

hermes backup 将 ~/.hermes 打包为 zip：

hermes backup                          # 默认输出 ~/hermes-backup-<timestamp>.zip
hermes backup --output ~/backups/      # 指定目录
hermes backup --quick                  # 仅备份关键状态文件

包含：config.yaml、.env、auth.json、state.db、memory_store.db、skills/、memories/、sessions/、cron/jobs.json、scripts/、plugins/

排除：hermes-agent/、__pycache__、.git、node_modules、*.pyc、gateway.pid、cron.pid

数据库采用 SQLite backup() API 安全拷贝，支持 WAL 模式。

恢复

hermes import 将 zip 解压至 ~/.hermes：

hermes import hermes-backup-2026-04-23-080000.zip
hermes import backup.zip --force       # 覆盖现有文件，不确认

导入前验证 zip 是否包含 config.yaml、.env 或 state.db。若检测到 .hermes/ 前缀，自动剥离。

卸载

hermes uninstall 提供两级清理：

hermes uninstall                       # 仅移除代码，保留 ~/.hermes 数据
hermes uninstall --full                # 删除代码 + 数据 + 服务注册

卸载流程：停止 gateway 进程、清理 systemd/launchd 服务、移除 shell PATH 配置、删除 wrapper 脚本、移除安装目录。

迁移流程

# 旧机器
hermes backup --output ~/hermes-migration.zip

# 传输至新机器（scp / 移动硬盘 / 云盘）

# 新机器
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
hermes import ~/hermes-migration.zip
hermes update                          # 确保代码仓库最新

不可默认迁移项

类别	说明	处理方式
代码修改	`hermes-agent/` 被排除	手动导出 `git diff` 或 `git bundle`
系统依赖	`ripgrep`、`ffmpeg`、`Node.js`、`Playwright`	新机器重新安装
服务注册	`systemd`/`launchd` plist	重新运行 `hermes gateway install`
Shell PATH	`~/.zshrc`、`~/.bashrc` 中的 `PATH` 行	`install.sh` 自动重新添加
绝对路径	`config.yaml` 中硬编码的旧机器路径	手动修正

实践验证

测试项	结果	说明
`hermes backup` 生成 zip	✅ 通过	包含 600+ 文件，自动排除 `hermes-agent/`
`hermes import` 恢复数据	✅ 通过	自动识别备份格式，恢复 `skills/`、`sessions/`
`hermes uninstall --full` 清理	✅ 通过	删除代码、数据、服务、`PATH` 配置
重装后 gateway 启动	⚠️ 需补步	需重新 `hermes gateway install` 注册服务
代码修改保留	❌ 不保留	需手动导出 `git diff`

总结

关键要点：

hermes backup + hermes import 覆盖 100% 数据与配置迁移
代码仓库（hermes-agent/）被设计为排除项，应通过 git 重新 clone
系统依赖（ripgrep、ffmpeg、Node.js）不在备份范围内
服务注册与 Shell PATH 由 install/uninstall 脚本自动管理
若修改过源码，迁移前务必手动导出 patch

适用场景： 换机、重装、VPS 部署、配置快照

不适用场景： 仅迁移代码修改（需 git 工具）、跨操作系统迁移（系统依赖不同）

参考

CLI Commands Reference — 官方 CLI 命令文档
Release v0.9.0 Notes — hermes backup & hermes import 功能发布说明（PR #7997）
hermes backup --help — 内置帮助：备份范围与排除项
hermes import --help — 内置帮助：恢复流程与验证机制
hermes uninstall --help — 内置帮助：卸载选项与服务清理