词元广场TOKPUB.COM - 欢迎您，支持一个 Key 调用近 600+ 海内外模型，限时特价模型低至 1 折，欢迎上岸！
会话存储
~/.hermes/state.db）跨 CLI 和 gateway 会话持久化会话元数据、完整消息历史及模型配置。这替代了早期的逐会话 JSONL 文件方案。hermes_state.py架构概览
~/.hermes/state.db (SQLite, WAL mode)
├── sessions — 会话元数据、token 计数、计费信息
├── messages — 每个会话的完 整消息历史
├── messages_fts — FTS5 虚拟表（content + tool_name + tool_calls）
├── messages_fts_trigram — 使用 trigram tokenizer 的 FTS5 虚拟表（CJK / 子串搜索）
├── state_meta — 键值元数据表
└── schema_version — 单行表，跟踪迁移状态parent_session_id 链实现（压缩触发的会话分割）cli、telegram、discord 等）：用于平台过滤SQLite Schema
Sessions 表
Messages 表
tool_calls 以 JSON 字符串存储（序列化的 tool call 对象列表）reasoning_details、codex_reasoning_items 和 codex_message_items 以 JSON 字符串存储reasoning 存储提供商暴露的原始推理文本time.time()）FTS5 全文搜索
messages 表保持同步，分别在 INSERT、UPDATE 和 DELETE 时触发：Schema 版本与迁移
schema_version 表存储单个整数。简单的列添加由 _reconcile_columns() 声明式处理（对比实时列与 SCHEMA_SQL 并 ADD 缺失列）。版本门控链保留用于无法声明式表达的数据迁移及索引/FTS 变更：| 版本 | 变更 |
|---|---|
| 1 | 初始 schema（sessions、messages、FTS5） |
| 2 | 向 messages 添加 finish_reason 列 |
| 3 | 向 sessions 添加 title 列 |
| 4 | 在 title 上添加唯一索引（允许 NULL，非 NULL 必须唯一） |
| 5 | 添加计费列：cache_read_tokens、cache_write_tokens、reasoning_tokens、billing_provider、billing_base_url、billing_mode、estimated_cost_usd、actual_cost_usd、cost_status、cost_source、pricing_version |
| 6 | 向 messages 添加推理列：reasoning 、reasoning_details、codex_reasoning_items |
| 7 | 向 messages 添加 reasoning_content 列 |
| 8 | 向 sessions 添加 api_call_count 列 |
| 9 | 向 messages 添加 codex_message_items 列，用于 Codex Responses 消息 id/phase 重放 |
| 10 | 添加 messages_fts_trigram 虚拟表（trigram tokenizer，用于 CJK / 子串搜索）并回填现有行 |
| 11 | 重新索引 messages_fts 和 messages_fts_trigram 以覆盖 tool_name + tool_calls，从外部内容模式切换为内联模式；删除旧触发器并回填所有消息行 |
ALTER TABLE ADD COLUMN，包裹在 try/except 中以处理列已存在的情况（幂等）。每个成功的迁移块完成后版本号递增。写入竞争处理
state.db。SessionDB 类通过以下方式处理写入竞争：_WRITE_MAX_RETRIES = 15
_WRITE_RETRY_MIN_S = 0.020 # 20ms
_WRITE_RETRY_MAX_S = 0.150 # 150ms
_CHECKPOINT_EVERY_N_WRITES = 50常用操作
初始化
创建和管理会话
存储消息
检索消息
会话标题
全文搜索
search_messages() 方法支持 FTS5 查询语法，并自动对用户输入进行清理。基本搜索
FTS5 查询语法
| 语法 | 示例 | 含义 |
|---|---|---|
| 关键词 | docker deployment | 两个词均包含（隐式 AND） |
| 引号短语 | "exact phrase" | 精确短语匹配 |
| 布尔 OR | docker OR kubernetes | 任一词 |
| 布尔 NOT | python NOT java | 排除词 |
| 前缀 | deploy* | 前缀匹配 |
过滤搜索
搜索结果格式
id、session_id、role、timestampsnippet — FTS5 生成的片段，带 >>>match<<< 标记context — 匹配前后各 1 条消息（内容截断至 200 字符）source、model、session_started — 来自父会话_sanitize_fts5_query() 方法处理边缘情况：chat-send → "chat-send"）hello AND → hello）会话血缘
parent_session_id 形成链。这发生在 gateway 中上下文压缩触发会话分割时。查询：查找会话血缘
查询：带预览的最近会话
查询：Token 使用统计
导出与清理
数据库位置
~/.hermes/state.dbhermes_constants.get_hermes_home() 推导，默认解析为 ~/.hermes/，或 HERMES_HOME 环境变量的值。state.db-wal）和共享内存文件（state.db-shm）均创建于同一目录。