背景

Hermes Agent 默认将所有数据存储在 ~/.hermes/，包括程序本体（venv、node_modules）和用户数据（sessions、memories、skills 等）。随着使用，这个目录会持续增长。本教程记录如何将其迁移到外部硬盘以节省内置 SSD 空间。

前提条件

• 外部硬盘格式为 APFS 或 Mac OS Extended (HFS+)（不支持 NTFS/exFAT，因为需要符号链接和 Unix 权限）
• 外部硬盘有足够可用空间（当前 Hermes 占 ~1 GB，随使用会增长）

迁移步骤

Step 1: 停止 Hermes

# 检查 Hermes 是否在运行
ps aux | grep -i hermes | grep -v grep
# 如果在运行，停止它
hermes stop
# 或者强制终止
pkill -f hermes

重要：必须在 Hermes 完全停止后再操作，否则可能导致数据损坏。

Step 2: 确认外部硬盘状态

# 查看已挂载的外部卷
ls /Volumes/

# 确认文件系统类型（必须是 APFS 或 HFS+）
diskutil info /Volumes/你的硬盘名 | grep "File System"

# 确认可用空间
df -h /Volumes/你的硬盘名

Step 3: 移动数据到外部硬盘

# 将 ~/.hermes 整体移动到外部硬盘（目录名可自定义）
mv ~/.hermes /Volumes/你的硬盘名/.hermes

为什么用 mv 而不是 cp？

mv 在同一文件系统上是瞬间完成的（只改指针）。跨文件系统时等同于 cp + rm，但更简洁。

Step 4: 创建符号链接

# 在原位置创建指向外部硬盘的符号链接
ln -s /Volumes/你的硬盘名/.hermes ~/.hermes

为什么用符号链接而不是 HERMES_HOME 环境变量？

Hermes 的 Python 虚拟环境（venv）中所有脚本的 shebang 都硬编码了#!/Users/你的用户名/.hermes/hermes-agent/venv/bin/python3 这样的路径。

如果用 HERMES_HOME 指向新位置，venv 内部的路径全部断裂，导致 hermes 命令无法运行。

符号链接让系统"以为"数据还在 ~/.hermes/，所有硬编码路径都能正常解析。

Step 5: 验证

# 确认符号链接正确
ls -la ~/.hermes
# 应输出: ~/.hermes -> /Volumes/你的硬盘名/.hermes

# 确认 hermes 命令可用
hermes --version

# 确认配置文件可访问
cat ~/.hermes/config.yaml

推出外部硬盘前的操作

必须先停止 Hermes 再推出硬盘！ 否则会导致：

• 进程崩溃或挂起（无法读写数据文件）
• macOS 可能拒绝推出硬盘（提示"磁盘正在使用中"）
• 最坏情况：数据库文件（state.db）损坏

安全推出流程

# 1. 停止 Hermes
hermes stop 2>/dev/null
pkill -f hermes 2>/dev/null

# 2. 确认没有进程在访问外部硬盘
lsof +D /Volumes/你的硬盘名/.hermes 2>/dev/null

# 如果有输出，说明还有进程在使用，需要逐一关闭或 kill
# 例如：kill 

# 3. 安全推出
diskutil eject /Volumes/你的硬盘名
# 或者在 Finder 中点击推出按钮

重新插入硬盘后

插入硬盘后 Hermes 会自动恢复可用（因为符号链接会重新生效），直接运行 hermes 即可。

回滚（迁移回内置硬盘）

如果需要将数据迁回内置硬盘：

# 1. 停止 Hermes
hermes stop 2>/dev/null && pkill -f hermes 2>/dev/null

# 2. 删除符号链接
rm ~/.hermes

# 3. 移回数据
mv /Volumes/你的硬盘名/.hermes ~/.hermes

# 4. 验证
hermes --version

目录结构参考

~/.hermes/                          → 符号链接到外部硬盘
├── hermes-agent/                   (程序本体 ~1 GB)
│   ├── venv/                       (Python 虚拟环境, ~538 MB)
│   ├── ui-tui/                     (TUI 界面, ~191 MB)
│   ├── node_modules/               (Node.js 依赖, ~146 MB)
│   ├── skills/                     (内置技能)
│   └── agent/                      (核心代&理逻辑)
├── skills/                         (自定义/学习到的技能, 会增长)
├── sessions/                       (会话历史, 会增长)
├── memories/                       (跨会话记忆, 会增长)
├── audio_cache/                    (语音缓存, 会增长)
├── image_cache/                    (图片缓存, 会增长)
├── config.yaml                     (配置文件)
├── SOUL.md                         (Agent 人格定义)
├── auth.json                       (API 密钥)
└── state.db                        (状态数据库)

重命名外部硬盘上的目录

如果你对外部硬盘上的目录名不满意（比如想从 hermes-data 改为 .hermes），可以随时重命名：

# 1. 停止 Hermes
hermes stop 2>/dev/null && pkill -f hermes 2>/dev/null

# 2. 删除旧的符号链接
rm ~/.hermes

# 3. 重命名外部硬盘上的目录
mv /Volumes/你的硬盘名/旧目录名 /Volumes/你的硬盘名/新目录名

# 4. 重新创建符号链接指向新名称
ln -s /Volumes/你的硬盘名/新目录名 ~/.hermes

# 5. 验证
ls -la ~/.hermes
hermes --version

注意：. 开头的目录在 Finder 中默认隐藏。按 Cmd + Shift + . 可以切换显示隐藏文件。

操作记录

初次迁移 (2026-04-22)

• 源路径: ~/.hermes/ (1.0 GB, 71213 个文件)
• 目标路径: /Volumes/WDBlueSN5000/hermes-data/
• 外部硬盘: WD Blue SN5000 (931 GB APFS)
• 方案: 符号链接（~/.hermes → 外部硬盘）
• 验证: rsync 复制后对比文件数量一致，hermes v0.10.0 正常运行

目录重命名 (2026-04-22)

• 操作: 将外部硬盘上的 hermes-data 重命名为 .hermes
• 步骤: 删除符号链接 → mv 重命名 → 重建符号链接
• 最终路径: ~/.hermes → /Volumes/WDBlueSN5000/.hermes
• 验证: hermes v0.10.0 正常运行

踩坑记录：为什么不能用 HERMES_HOME 环境变量

• 最初尝试设置 export HERMES_HOME="/Volumes/WDBlueSN5000/hermes-data" 并直接 mv 整个目录
• 结果: hermes 命令无法运行，因为 venv 内脚本的 shebang 硬编码了 #!/Users/cc/.hermes/hermes-agent/venv/bin/python3
• 解决: 改用符号链接方案，让所有硬编码路径透明解析到外部硬盘