<!-- Source: https://hermesbible.com/docs/developer-guide/session-storage -->

會話儲存

Hermes Agent 使用 SQLite 資料庫（~/.hermes/state.db）來持久化 CLI 和閘道器會話的會話中繼資料、完整訊息歷史和模型設定。這取代了早期的每會話 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 分詞器的 FTS5 虛擬表格（CJK / 子字串搜尋）
├── state_meta            — 鍵/值中繼資料表格
└── 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,
    api_call_count INTEGER DEFAULT 0,
    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_content TEXT,
    reasoning_details TEXT,
    codex_reasoning_items TEXT,
    codex_message_items TEXT
);

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

備註：

• tool_calls 以 JSON 字串儲存（工具呼叫物件的序列化列表）
• reasoning_details、codex_reasoning_items 和 codex_message_items 以 JSON 字串儲存
• reasoning 儲存公開它的供應商的原始推理文字
• 時間戳為 Unix epoch 浮點數（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 版本：11

schema_version 表格儲存一個整數。簡單的欄位新增由 _reconcile_columns() 以宣告方式處理（它比較即時欄位與 SCHEMA_SQL 並 ADD 任何缺少的）。版本閘控的鏈保留給無法以宣告方式表達的資料遷移和索引/FTS 變更：

宣告式的欄位新增使用 ALTER TABLE ADD COLUMN 包裝在 try/except 中以處理欄位已存在的情況（冪等）。版本號在每次成功的遷移區塊後遞增。

寫入競爭處理

多個 hermes 程序（閘道器 + CLI 會話 + 工作樹 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 查詢語法

帶過濾的搜尋

# 僅搜尋 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）都在同一目錄中建立。

---

---

供應商執行時解析