跳到主要内容

会话存储

Hermes Agent 使用 SQLite 数据库（~/.hermes/state.db）持久化会话元数据、完整消息历史和跨 CLI 和网关会话的模型配置。这取代了早期每个会话一个 JSONL 文件的方法。

源文件：hermes_state.py

架构概述​

~/.hermes/state.db (SQLite, WAL mode)
├── sessions          — 会话元数据、token 计数、计费
├── messages          — 每个会话的完整消息历史
├── messages_fts      — 用于全文搜索的 FTS5 虚拟表
└── schema_version    — 跟踪迁移状态的单行表

关键设计决策：

  • WAL 模式 用于并发读取 + 一个写入（网关多平台）
  • FTS5 虚拟表 用于跨所有会话消息的快速文本搜索
  • 会话谱系 通过 parent_session_id 链（压缩触发的分割）
  • 源标记（cli、telegram、discord 等）用于平台过滤

SQLite Schema​

Sessions 表​

CREATE TABLE IF NOT EXISTS sessions (
    id TEXT PRIMARY KEY,
    source TEXT NOT NULL,
    user_id TEXT,
    model TEXT,
    model_config TEXT,
    system_prompt TEXT,
    parent_session_id TEXT,
    started_at REAL NOT NULL,
    ended_at REAL,
    end_reason TEXT,
    message_count INTEGER DEFAULT 0,
    tool_call_count INTEGER DEFAULT 0,
    input_tokens INTEGER DEFAULT 0,
    output_tokens INTEGER DEFAULT 0,
    billing_provider TEXT,
    title TEXT,
    FOREIGN KEY (parent_session_id) REFERENCES sessions(id)
);

Messages 表​

CREATE TABLE IF NOT EXISTS messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT NOT NULL REFERENCES sessions(id),
    role TEXT NOT NULL,
    content TEXT,
    tool_call_id TEXT,
    tool_calls TEXT,
    tool_name TEXT,
    timestamp REAL NOT NULL,
    token_count INTEGER,
    finish_reason TEXT,
    reasoning TEXT
);

FTS5 全文搜索​

CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
    content,
    content=messages,
    content_rowid=id
);

Schema 版本和迁移​

当前 schema 版本：6

版本更改
1初始 schema（sessions, messages, FTS5）
2向 messages 添加 finish_reason 列
3向 sessions 添加 title 列
4添加 title 上的唯一索引（允许 NULL，NULL 必须唯一）
5添加计费列
6向 messages 添加推理列

写入竞争处理​

多个 hermes 进程（网关 + CLI 会话 + worktree agents）共享一个 state.db。SessionDB 类处理写入竞争：

  • 短 SQLite 超时（1 秒）代替默认的 30 秒
  • 应用级重试 带有随机抖动（20-150ms，最多 15 次重试）
  • BEGIN IMMEDIATE 事务在事务开始时暴露锁竞争
  • 定期 WAL 检查点 每 50 次成功写入（PASSIVE 模式）

常见操作​

初始化​

from hermes_state import SessionDB

db = SessionDB()                           # 默认：~/.hermes/state.db
db = SessionDB(db_path=Path("/tmp/test.db"))  # 自定义路径

创建和管理会话​

db.create_session(
    session_id="sess_abc123",
    source="cli",
    model="anthropic/claude-sonnet-4.6",
    user_id="user_1",
)
db.end_session("sess_abc123", end_reason="user_exit")

存储消息​

msg_id = db.append_message(
    session_id="sess_abc123",
    role="assistant",
    content="Here's the answer...",
    tool_calls=[{"id": "call_1", "function": {"name": "terminal", "arguments": "{}"}}],
    token_count=150,
)

检索消息​

messages = db.get_messages("sess_abc123")
conversation = db.get_messages_as_conversation("sess_abc123")

全文搜索​

results = db.search_messages("docker deployment")

FTS5 查询语法​

| 语法 | 示例 | 含义 | |--------|--------|---------|---------| | 关键词 | docker deployment | 两个术语（隐含 AND） | | 引号短语 | "exact phrase" | 精确短语匹配 | | 布尔 OR | docker OR kubernetes | 任一术语 | | 布尔 NOT | python NOT java | 排除术语 | | 前缀 | deploy* | 前缀匹配 |

会话谱系​

会话可以通过 parent_session_id 形成链。这发生在网关中上下文压缩触发会话分割时。

导出和清理​

data = db.export_session("sess_abc123")
all_data = db.export_all(source="cli")
deleted_count = db.prune_sessions(older_than_days=90)
db.delete_session("sess_abc123")

数据库位置​

默认路径：~/.hermes/state.db