Sessions

Hermes Agent 会自动将每一次对话保存为一个 session。Session 支持对话续接、跨 session 搜索，以及完整的对话历史管理。

Session 的工作方式

每一段对话——无论来自 CLI、Telegram、Discord、Slack、WhatsApp、Signal、Matrix，还是任何其他消息平台——都会作为一个 session 保存，并包含完整的消息历史。Session 会在两个互补的系统中进行追踪：

1. SQLite database（~/.hermes/state.db）——包含结构化的 session 元数据，并支持 FTS5 全文搜索
2. JSONL transcripts（~/.hermes/sessions/）——原始对话转录，包含 tool calls（gateway）

SQLite database 会存储以下内容：

• Session ID、来源平台、用户 ID
• Session title（唯一、便于阅读的人类可读名称）
• Model 名称和配置
• System prompt 快照
• 完整消息历史（role、content、tool calls、tool results）
• Token 计数（input/output）
• 时间戳（started_at、ended_at）
• Parent session ID（用于因 compression 触发的 session 拆分）

Session 来源

每个 session 都会带有其来源平台标签：

CLI Session Resume

可以通过 --continue 或 --resume 在 CLI 中恢复之前的对话：

继续上一个 Session

# 恢复最近的 CLI session
hermes --continue
hermes -c
# 或使用 chat 子命令
hermes chat --continue
hermes chat -c

这会从 SQLite database 中查找最近的 cli session，并加载其完整的对话历史。

按名称恢复

如果你已经为某个 session 设置了 title（见下方的 Session Naming），就可以按名称恢复它：

# 恢复一个已命名的 session
hermes -c "my project"
# 如果存在 lineage 变体（my project、my project #2、my project #3），
# 会自动恢复最近的那个
hermes -c "my project"   # → 恢复 "my project #3"

恢复指定 Session

# 通过 ID 恢复指定 session
hermes --resume 20250305_091523_a1b2c3d4
hermes -r 20250305_091523_a1b2c3d4
# 通过 title 恢复
hermes --resume "refactoring auth"
# 或使用 chat 子命令
hermes chat --resume 20250305_091523_a1b2c3d4

Session ID 会在你退出 CLI session 时显示，也可以通过 hermes sessions list 找到。

恢复时的对话摘要

当你恢复一个 session 时，Hermes 会在输入提示符出现之前，以一个带样式的面板展示上一段对话的紧凑摘要：

Resume 模式会显示一个紧凑的摘要面板，展示最近的 user 和 assistant 回合，然后再返回实时输入提示。

该摘要会：

• 显示 user messages（金色 ●）和 assistant responses（绿色 ◆）
• 对长消息进行 截断（user 为 300 个字符，assistant 为 200 个字符 / 3 行）
• 将 tool calls 折叠为数量加 tool 名称（例如 [3 tool calls: terminal, web_search]）
• 隐藏 system messages、tool results 和内部推理
• 最多 只显示最后 10 轮交互，并用 ... N earlier messages ... 提示更早的消息
• 使用 dim styling 来区别于当前激活中的对话

如果想禁用该摘要，并保留最简的一行式行为，可以在 ~/.hermes/config.yaml 中设置：

display:
  resume_display: minimal   # 默认值：full

Session Naming

为 session 设置便于阅读的 title，这样你就能更轻松地查找和恢复它们。

自动生成的 Title

Hermes 会在第一轮对话后，自动为每个 session 生成一个简短且具有描述性的 title（3–7 个词）。这项工作会在后台线程中通过一个快速的辅助 model 完成，因此不会增加延迟。你可以在使用 hermes sessions list 或 hermes sessions browse 浏览 session 时看到这些自动生成的 title。

自动命名只会在每个 session 中触发一次；如果你已经手动设置过 title，则会跳过。

手动设置 Title

在任意 chat session（CLI 或 gateway）中使用 /title slash command：

/title my research project

Title 会立即生效。如果该 session 还没有在 database 中创建（例如你在发送第一条消息前就执行了 /title），该 title 会先排队，待 session 开始后再应用。

你也可以通过命令行重命名已有 session：

hermes sessions rename 20250305_091523_a1b2c3d4 "refactoring auth module"

Title 规则

• 唯一——不能有两个 session 使用相同的 title
• 最长 100 个字符——便于保持列表输出整洁
• 已清洗——控制字符、零宽字符和 RTL overrides 会被自动移除
• 普通 Unicode 可用——emoji、CJK、带重音字符都支持

Compression 后的自动 Lineage

当某个 session 的上下文被压缩时（手动通过 /compress，或自动触发），Hermes 会创建一个新的 continuation session。如果原 session 有 title，新 session 会自动获得一个带编号的 title：

"my project" → "my project #2" → "my project #3"

当你通过名称恢复时（hermes -c "my project"），系统会自动选择该 lineage 中最新的 session。

消息平台中的 /title

/title 命令在所有 gateway 平台中都可用（Telegram、Discord、Slack、WhatsApp）：

• /title My Research —— 设置 session title
• /title —— 显示当前 title

Session 管理命令

Hermes 通过 hermes sessions 提供完整的 session 管理命令集：

列出 Session

# 列出最近的 session（默认：最近 20 个）
hermes sessions list
# 按平台过滤
hermes sessions list --source telegram
# 显示更多 session
hermes sessions list --limit 50

当 session 带有 title 时，输出会显示 title、预览和相对时间戳：

Title                  Preview                                  Last Active   ID
────────────────────────────────────────────────────────────────────────────────────────────────
refactoring auth       Help me refactor the auth module please   2h ago        20250305_091523_a
my project #3          Can you check the test failures?          yesterday     20250304_143022_e
—                      What's the weather in Las Vegas?          3d ago        20250303_101500_f

当没有 session 带有 title 时，会使用更简单的格式：

Preview                                            Last Active   Src    ID
──────────────────────────────────────────────────────────────────────────────────────
Help me refactor the auth module please             2h ago        cli    20250305_091523_a
What's the weather in Las Vegas?                    3d ago        tele   20250303_101500_f

导出 Session

# 将所有 session 导出到一个 JSONL 文件
hermes sessions export backup.jsonl
# 导出某个平台的 session
hermes sessions export telegram-history.jsonl --source telegram
# 导出单个 session
hermes sessions export session.jsonl --session-id 20250305_091523_a1b2c3d4

导出的文件每一行都包含一个 JSON object，其中包含完整的 session 元数据和全部消息。

删除一个 Session

# 删除指定 session（带确认）
hermes sessions delete 20250305_091523_a1b2c3d4
# 无需确认直接删除
hermes sessions delete 20250305_091523_a1b2c3d4 --yes

重命名一个 Session

# 设置或更改 session 的 title
hermes sessions rename 20250305_091523_a1b2c3d4 "debugging auth flow"
# 在 CLI 中，多词 title 不需要加引号
hermes sessions rename 20250305_091523_a1b2c3d4 debugging auth flow

如果 title 已被另一个 session 占用，会显示错误。

清理旧 Session

# 删除超过 90 天的已结束 session（默认）
hermes sessions prune
# 自定义时间阈值
hermes sessions prune --older-than 30
# 只清理某个平台的 session
hermes sessions prune --source telegram --older-than 60
# 跳过确认
hermes sessions prune --older-than 30 --yes

Session 统计

hermes sessions stats

输出：

Total sessions: 142
Total messages: 3847
  cli: 89 sessions
  telegram: 38 sessions
  discord: 15 sessions
Database size: 12.4 MB

若需要更深入的分析——例如 token usage、cost estimates、tool breakdown 和 activity patterns——请使用 hermes insights。

Session Search Tool

Agent 内置了一个 session_search tool，它使用 SQLite 的 FTS5 engine 对所有历史对话执行全文搜索。

它的工作方式

1. FTS5 搜索匹配的消息，并按相关性排序
2. 按 session 对结果分组，取前 N 个唯一 session（默认 3 个）
3. 加载每个 session 的对话内容，并以匹配点为中心截断到约 100K 字符
4. 发送给一个快速 summarization model，生成聚焦摘要
5. 返回每个 session 的摘要、元数据以及周边上下文

FTS5 查询语法

搜索支持标准的 FTS5 查询语法：

• 简单关键词：docker deployment
• 短语："exact phrase"
• 布尔表达式：docker OR kubernetes、python NOT java
• 前缀：deploy*

何时使用

Agent 会被提示自动使用 session search：

“当用户提到过去某次对话中的内容，或者你怀疑存在相关的历史上下文时，应先使用 session_search 进行回忆，而不是让用户重复说明。”

按平台进行 Session Tracking

Gateway Sessions

在消息平台上，session 会根据由消息来源构建的确定性 session key 进行标识：

当 Hermes 无法为共享 chat 获取参与者标识符时，它会退回为该 room 使用一个共享 session。

共享与隔离的 Group Sessions

默认情况下，Hermes 在 config.yaml 中使用 group_sessions_per_user: true。这意味着：

• Alice 和 Bob 可以在同一个 Discord channel 中分别与 Hermes 对话，而不会共享转录历史
• 一个用户执行冗长且包含大量 tool 的任务，不会污染另一个用户的上下文窗口
• 中断处理也会保持按用户隔离，因为 running-agent key 与隔离后的 session key 相匹配

如果你希望改为一个共享的“room brain”，可以设置：

group_sessions_per_user: false

这样就会把 group / channel 恢复为每个 room 一个共享 session，从而保留共享的对话上下文，但也会共享 token 成本、中断状态和上下文增长。

Session Reset 策略

Gateway sessions 会根据可配置的策略自动 reset：

• idle —— 在无活动 N 分钟后 reset
• daily —— 每天在指定小时 reset
• both —— 两者中先到者触发 reset（idle 或 daily）
• none —— 永不自动 reset

在 session 自动 reset 之前，agent 会先获得一个回合，用于保存该对话中的重要 memories 或 skills。

带有 active background processes 的 sessions 永远不会被自动 reset，无论使用何种策略。

存储位置

SQLite database 使用 WAL mode，以支持并发 reader 和单个 writer，这非常适合 gateway 的多平台架构。

Database Schema

state.db 中的关键表包括：

• sessions —— session 元数据（id、source、user_id、model、title、timestamps、token counts）。Title 带有唯一索引（允许 NULL title，仅非 NULL 值必须唯一）。
• messages —— 完整消息历史（role、content、tool_calls、tool_name、token_count）
• messages_fts —— FTS5 virtual table，用于对 message content 执行全文搜索

Session 过期与清理

自动清理

• Gateway sessions 会根据配置的 reset policy 自动 reset
• 在 reset 之前，agent 会保存即将过期 session 中的重要 memories 和 skills
• 已结束的 sessions 会一直保留在 database 中，直到被 prune

手动清理

# 清理超过 90 天的 session
hermes sessions prune
# 删除指定 session
hermes sessions delete <session_id>
# 清理前先导出（备份）
hermes sessions export backup.jsonl
hermes sessions prune --older-than 30 --yes