Session Archivist — 会话生命周期管理
Overview
Session Archivist 解决 Hermes Agent 的已知问题：session 文件无限增长导致 Web UI 卡死、上下文压缩失效、API 配额耗尽。
核心能力：
- 大 session 检测 — 自动扫描超过阈值的 session 文件
- 重要性评分 — 不是所有消息都值得保留，智能评分筛选
- 压缩前记忆刷新 — 压缩前先存档关键信息，防止丢失
- 结构化摘要 — 提取意图/决策/待办/引用，不是简单的文本压缩
- 去重/冲突检测 — 避免重复记忆，矛盾事实自动更新
- 会话边界检测 — 话题切换时自动分割归档
- session 裁剪 — 归档后裁剪到目标大小
无外部依赖也能用：摘要保存为本地 markdown 文件。 有 Hindsight 增强：自动存入向量记忆库，支持跨会话召回。
When to Use
- Web UI 点击对话没反应（session 文件太大）
- 上下文压缩不触发（模型上下文长度识别错误）
- 想要自动管理 session 生命周期
- 长期运行的会话需要归档整理
Don't use for:
- 新建 session（用
/new） - 简单的 session 切换（用
hermsessions browse）
Quick Start
# 1. 一键安装（配置 cron 定时任务）
bash ~/.hermes/skills/productivity/session-archivist/scripts/setup_cron.sh
# 2. 手动执行一次归档
python3 ~/.hermes/skills/productivity/session-archivist/scripts/session_archiver.py
# 3. 只检测不修改（dry-run）
python3 ~/.hermes/skills/productivity/session-archivist/scripts/session_archiver.py --dry-run
Configuration
在 config.yaml 中添加（可选，有默认值）：
session_archivist:
enabled: true
max_session_size_kb: 1024 # 超过 1MB 触发归档
target_session_size_kb: 512 # 归档后目标大小
importance_threshold: 0.5 # 重要性评分阈值（0-1）
archive_dir: ~/.hermes/session-archives
hindsight_enabled: auto # auto/true/false
cron_schedule: "0 3 * * *" # 每天凌晨3点执行
summary_template: structured # structured/compact/raw
How It Works
┌──────────────────────────────────────────────────────────┐
│ Session Archivist 流程 │
├──────────────────────────────────────────────────────────┤
│ │
│ 1. 扫描阶段 │
│ └─ 遍历 ~/.hermes/sessions/*.json │
│ └─ 找出 > max_session_size_kb 的文件 │
│ │
│ 1.5 安全检查（每个 session） │
│ ├─ 活跃检测：最近 5 分钟有更新 → 跳过 │
│ ├─ Agent 运行检测：gateway 日志中有活跃 session → 跳过 │
│ ├─ Gateway 繁忙检测：有 run_agent 进程 → 跳过 │
│ └─ 文件锁：fcntl.LOCK_EX 防止并发写入 │
│ │
│ 2. 分析阶段 │
│ ├─ 加载 session JSON │
│ ├─ 会话边界检测（话题切换点） │
│ └─ 逐条消息重要性评分 │
│ │
│ 3. 提取阶段 │
│ ├─ 高分消息 → 提取关键信息 │
│ ├─ 结构化摘要生成 │
│ └─ 去重检测（vs 已有记忆） │
│ │
│ 4. 存档阶段 │
│ ├─ 本地 markdown 存档（始终） │
│ ├─ Hindsight 存档（如果可用） │
│ └─ 保留 session_id 元数据 │
│ │
│ 5. 裁剪阶段 │
│ ├─ 保留最近 N 条消息 │
│ ├─ 插入摘要上下文 │
│ └─ 写回 session 文件 │
│ │
└──────────────────────────────────────────────────────────┘
Importantance Scoring
消息评分维度（0-1 分）：
| 维度 | 权重 | 示例 |
|---|---|---|
| 包含决策 | 0.3 | "我们决定用 X 方案" |
| 包含代码 | 0.2 | code blocks |
| 包含错误修复 | 0.25 | "问题是 X，解决方案是 Y" |
| 包含用户偏好 | 0.15 | "我喜欢/不喜欢 X" |
| 包含待办事项 | 0.1 | "TODO: 还需要做 X" |
| 工具调用结果 | 0.1 | 包含 file_path, command 等 |
| 简单问候 | 0.0 | "你好", "OK" |
Archive Format
# Session Archive: {title}
## Metadata
- **Session ID**: {session_id}
- **Archived At**: {timestamp}
- **Original Size**: {size} messages
- **Importance Threshold**: {threshold}
- **Source**: gateway/webui/cli
## User Intent
> {用户原始意图引用}
## Key Decisions
1. {决策1} — {原因}
2. {决策2} — {原因}
## Completed Work
- [x] {任务1} — {结果}
- [x] {任务2} — {结果}
## Errors & Solutions
| Error | Solution |
|-------|----------|
| {错误1} | {解决方案1} |
## Pending Tasks
- [ ] {待办1}
- [ ] {待办2}
## Key References
- File: {path}
- Config: {key} = {value}
- API: {endpoint}
Hindsight Integration
如果 Hindsight 可用，归档时自动：
- 创建/使用 bank（按项目名）
- 存入结构化摘要作为 memory
- 添加元数据：session_id, archived_at, importance_score
- 添加标签：session-archive, {project_name}
召回时：
- 搜索返回结果包含 session_id
- 可用
hermes --resume <session_id>恢复
Common Pitfalls
-
压缩前没存档就裁剪 — 导致信息永久丢失。Session Archivist 的 memory_flush 机制确保先存后删。
-
重要性阈值设太低 — 保留太多低价值消息，裁剪效果差。建议 0.5 起步。
-
Hindsight 不可用时没降级 — 脚本自动检测，不可用时只存本地 markdown。
-
cron 任务和 hermes gateway 压缩冲突 — 内置 4 层安全防护：①跳过最近 5 分钟有更新的 session ②检测 gateway 日志中的活跃 session ③检测 run_agent 进程是否运行 ④fcntl 文件锁防止并发写入。cron 建议在凌晨执行，避开活跃使用时段。
-
裁剪后 session 无法恢复 — 原始 session 备份在
~/.hermes/session-archives/backups/，保留 7 天。
Verification Checklist
-
session_archiver.py --dry-run能正确检测大 session - 归档 markdown 文件包含完整结构化摘要
- 裁剪后 session 文件 < target_session_size_kb
- Hindsight 可用时自动存入（检查 bank）
- cron 任务正常执行（
hermes cron list） - Web UI 能正常加载裁剪后的 session