知识引擎/Hermes 知识引擎/会话存储

返回分馆所属主题：开发者指南更新于 2026年4月16日官方来源

Hermes Agent 使用 SQLite 数据库（ /.hermes/state.db）来持久化会话元数据、完整消息历史和模型配置，覆盖 CLI 和网关会话。这取代了早期基于每个会话 JSONL 文件的方式。源文件：hermes state.py 关键设计决策： - WAL 模式用于并发读取 + 单个写入器（网

> 📖 本文档翻译自 Session Storage > 最后更新：2026-04-16

会话存储

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

源文件：hermes_state.py

架构概览

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

关键设计决策：

WAL 模式用于并发读取 + 单个写入器（网关多平台场景）
FTS5 虚拟表用于跨所有会话消息的快速文本搜索
会话世系通过 parent_session_id 链实现（压缩触发的分割）
来源标记（cli、telegram、discord 等）用于平台过滤
批量运行器和 RL 轨迹不存储在此（独立系统）

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,
    cache_read_tokens INTEGER DEFAULT 0,
    cache_write_tokens INTEGER DEFAULT 0,
    reasoning_tokens INTEGER DEFAULT 0,
    billing_provider TEXT,
    billing_base_url TEXT,
    billing_mode TEXT,
    estimated_cost_usd REAL,
    actual_cost_usd REAL,
    cost_status TEXT,
    cost_source TEXT,
    pricing_version TEXT,
    title TEXT,
    FOREIGN KEY (parent_session_id) REFERENCES sessions(id)
);

CREATE INDEX IF NOT EXISTS idx_sessions_source ON sessions(source);
CREATE INDEX IF NOT EXISTS idx_sessions_parent ON sessions(parent_session_id);
CREATE INDEX IF NOT EXISTS idx_sessions_started ON sessions(started_at DESC);
CREATE UNIQUE INDEX IF NOT EXISTS idx_sessions_title_unique
    ON sessions(title) WHERE title IS NOT NULL;

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,
    reasoning_details TEXT,
    codex_reasoning_items TEXT
);

CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id, timestamp);

注意：

tool_calls 以 JSON 字符串存储（工具调用对象列表的序列化）
reasoning_details 和 codex_reasoning_items 以 JSON 字符串存储
reasoning 存储暴露推理内容的 Provider 的原始推理文本
时间戳是 Unix 纪元浮点数（time.time()）

FTS5 全文搜索

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

FTS5 表通过三个触发器与 messages 表的 INSERT、UPDATE 和 DELETE 操作保持同步：

CREATE TRIGGER IF NOT EXISTS messages_fts_insert AFTER INSERT ON messages BEGIN
    INSERT INTO messages_fts(rowid, content) VALUES (new.id, new.content);
END;

CREATE TRIGGER IF NOT EXISTS messages_fts_delete AFTER DELETE ON messages BEGIN
    INSERT INTO messages_fts(messages_fts, rowid, content)
        VALUES('delete', old.id, old.content);
END;

CREATE TRIGGER IF NOT EXISTS messages_fts_update AFTER UPDATE ON messages BEGIN
    INSERT INTO messages_fts(messages_fts, rowid, content)
        VALUES('delete', old.id, old.content);
    INSERT INTO messages_fts(rowid, content) VALUES (new.id, new.content);
END;

Schema 版本和迁移

当前 Schema 版本：6

schema_version 表存储一个整数。初始化时，_init_schema() 检查当前版本并按顺序应用迁移：

版本	变更
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`

每次迁移使用 ALTER TABLE ADD COLUMN 并包装在 try/except 中以处理列已存在的情况（幂等）。版本号在每次成功迁移块后递增。

写入争用处理

多个 Hermes 进程（网关 + CLI 会话 + worktree Agent）共享一个 state.db。SessionDB 类通过以下方式处理写入争用：

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

这避免了"车队效应"——SQLite 的确定性内部退避会导致所有竞争写入器在相同间隔重试。

_WRITE_MAX_RETRIES = 15
_WRITE_RETRY_MIN_S = 0.020   # 20ms
_WRITE_RETRY_MAX_S = 0.150   # 150ms
_CHECKPOINT_EVERY_N_WRITES = 50

常见操作

初始化

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",
    parent_session_id=None,  # 或先前会话 ID 用于世系
)

# 结束会话
db.end_session("sess_abc123", end_reason="user_exit")

# 重新打开会话（清除 ended_at/end_reason）
db.reopen_session("sess_abc123")

存储消息

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,
    finish_reason="stop",
    reasoning="Let me think about this...",
)

检索消息

# 带所有元数据的原始消息
messages = db.get_messages("sess_abc123")

# OpenAI 对话格式（用于 API 回放）
conversation = db.get_messages_as_conversation("sess_abc123")
# 返回: [{"role": "user", "content": "..."}, {"role": "assistant", ...}]

会话标题

# 设置标题（在非 NULL 标题中必须唯一）
db.set_session_title("sess_abc123", "Fix Docker Build")

# 按标题解析（返回世系中最新的）
session_id = db.resolve_session_by_title("Fix Docker Build")

# 自动生成世系中的下一个标题
next_title = db.get_next_title_in_lineage("Fix Docker Build")
# 返回: "Fix Docker Build #2"

全文搜索

search_messages() 方法支持 FTS5 查询语法，并自动清理用户输入。

基本搜索

results = db.search_messages("docker deployment")

FTS5 查询语法

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

过滤搜索

# 仅搜索 CLI 会话
results = db.search_messages("error", source_filter=["cli"])

# 排除网关会话
results = db.search_messages("bug", exclude_sources=["telegram", "discord"])

# 仅搜索用户消息
results = db.search_messages("help", role_filter=["user"])

搜索结果格式

每条结果包括：

id、session_id、role、timestamp
snippet——FTS5 生成的带 >>>match<<< 标记的摘要
context——匹配前后各 1 条消息（内容截断到 200 字符）
source、model、session_started——来自父会话

_sanitize_fts5_query() 方法处理边界情况：

剥离不匹配的引号和特殊字符
将连字符术语包装在引号中（chat-send → "chat-send"）
移除悬空的布尔运算符（hello AND → hello）

会话世系

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

查询：查找会话世系

-- 查找会话的所有祖先
WITH RECURSIVE lineage AS (
    SELECT * FROM sessions WHERE id = ?
    UNION ALL
    SELECT s.* FROM sessions s
    JOIN lineage l ON s.id = l.parent_session_id
)
SELECT id, title, started_at, parent_session_id FROM lineage;

-- 查找会话的所有后代
WITH RECURSIVE descendants AS (
    SELECT * FROM sessions WHERE id = ?
    UNION ALL
    SELECT s.* FROM sessions s
    JOIN descendants d ON s.parent_session_id = d.id
)
SELECT id, title, started_at FROM descendants;

查询：最近会话及预览

SELECT s.*,
    COALESCE(
        (SELECT SUBSTR(m.content, 1, 63)
         FROM messages m
         WHERE m.session_id = s.id AND m.role = 'user' AND m.content IS NOT NULL
         ORDER BY m.timestamp, m.id LIMIT 1),
        ''
    ) AS preview,
    COALESCE(
        (SELECT MAX(m2.timestamp) FROM messages m2 WHERE m2.session_id = s.id),
        s.started_at
    ) AS last_active
FROM sessions s
ORDER BY s.started_at DESC
LIMIT 20;

查询：Token 使用统计

-- 按模型的 Token 总量
SELECT model,
       COUNT(*) as session_count,
       SUM(input_tokens) as total_input,
       SUM(output_tokens) as total_output,
       SUM(estimated_cost_usd) as total_cost
FROM sessions
WHERE model IS NOT NULL
GROUP BY model
ORDER BY total_cost DESC;

-- Token 使用量最高的会话
SELECT id, title, model, input_tokens + output_tokens AS total_tokens,
       estimated_cost_usd
FROM sessions
ORDER BY total_tokens DESC
LIMIT 10;

导出和清理

# 导出单个会话及其消息
data = db.export_session("sess_abc123")

# 导出所有会话（带消息）为字典列表
all_data = db.export_all(source="cli")

# 删除旧会话（仅已结束的会话）
deleted_count = db.prune_sessions(older_than_days=90)
deleted_count = db.prune_sessions(older_than_days=30, source="telegram")

# 清除消息但保留会话记录
db.clear_messages("sess_abc123")

# 删除会话及所有消息
db.delete_session("sess_abc123")

数据库位置

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

这来自 hermes_constants.get_hermes_home()，默认解析为 ~/.hermes/，或 HERMES_HOME 环境变量的值。

数据库文件、WAL 文件（state.db-wal）和共享内存文件（state.db-shm）都创建在同一目录中。

Continue Exploring

继续探索

这不是课程式的上一篇下一篇，而是从当前节点向外继续漫游。

开发者指南

面向二次开发者，解释架构、运行时、上下文引擎、插件、工具与扩展机制。

20 篇文档20 个节点

当前节点

会话存储

返回分馆回到知识引擎

同主题继续探索

架构

贡献指南

Agent 循环内部机制

提示词组装

上下文压缩与缓存

网关内部机制

会话存储

架构概览

SQLite Schema(模式)

Sessions 表

Messages 表

FTS5 全文搜索

Schema 版本和迁移

写入争用处理

常见操作

初始化

创建和管理会话

存储消息

检索消息

会话标题

全文搜索

基本搜索

FTS5 查询语法

过滤搜索

搜索结果格式

会话世系

查询：查找会话世系

查询：最近会话及预览

查询：Token 使用统计

导出和清理

数据库位置

继续探索

架构

贡献指南

Agent 循环内部机制

提示词组装

上下文压缩与缓存

网关内部机制

开发者指南

知识引擎 AI 问答