session-archivist

Use when session files grow too large (>1MB), context compression fails to trigger, or you need to manage long-running session lifecycle. Auto-archives old sessions, scores message importance, flushes memory before compression, and keeps session files small.

Audits

Pass

ClawScanPass

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install session-archivist

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