세션 스토리지

기준일: 2026-07-26
난이도: 중급
공식 기준: Session Storage

개요

SQLite 세션 스키마, FTS5, 마이그레이션, 쓰기 경합, 공통 API를 정리합니다.

핵심 개념

구성	설명
sessions / messages	메타·메시지
FTS5	전문 검색
migrations	스키마 버전
title lineage	자동 제목 #N

상세

아키텍처 개요

원문 절: Architecture Overview

• WAL mode
• FTS5 virtual table
• Session lineage
• Source tagging

~/.hermes/state.db (SQLite, WAL mode)
├── sessions              — Session metadata, token counts, billing
├── messages              — Full message history per session
├── messages_fts          — FTS5 virtual table (content + tool_name + tool_calls)
├── messages_fts_trigram  — FTS5 virtual table with trigram tokenizer (CJK / substring search)
├── state_meta            — Key/value metadata table
└── schema_version        — Single-row table tracking migration state

SQLite 스키마

원문 절: SQLite Schema

• Sessions Table — 공식 하위 절. 구현·설정 세부 원문 참조.
• Messages Table — 공식 하위 절. 구현·설정 세부 원문 참조.
• FTS5 Full-Text Search — 공식 하위 절. 구현·설정 세부 원문 참조.

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);

스키마 버전과 마이그레이션

원문 절: Schema Version and Migrations

• 이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Version	Change
1	Initial schema (sessions, messages, FTS5)
2	Add finish_reason column to messages
3	Add title column to sessions
4	Add unique index on title (NULLs allowed, non-NULL must be unique)
5	Add billing columns: 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	Add reasoning columns to messages: reasoning, reasoning_details, codex_reasoning_items
7	Add reasoning_content column to messages
8	Add api_call_count column to sessions
9	Add codex_message_items column to messages for Codex Responses message id/phase replay
10	Add messages_fts_trigram virtual table (trigram tokenizer for CJK / substring search) and backfill existing rows
11	Re-index messages_fts and messages_fts_trigram to cover tool_name + tool_calls and switch from external-content to inline mode; drop old triggers and backfill every message row
16	Tag delegate subagent rows in model_config ($._delegate_from) so session pickers stay clean after parent deletes orphan them
18	Gateway metadata consolidation — backfill display_name / origin_json / expiry_finalized from sessions.json
20	Per-model usage attribution — seed session_model_usage rows from historical per-session aggregate totals

쓰기 경합 처리

원문 절: Write Contention Handling

• Short SQLite timeout
• Application-level retry
• BEGIN IMMEDIATE
• Periodic WAL checkpoints

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

공통 연산

원문 절: Common Operations

• Initialize — 공식 하위 절. 구현·설정 세부 원문 참조.
• Create and Manage Sessions — 공식 하위 절. 구현·설정 세부 원문 참조.
• Store Messages — 공식 하위 절. 구현·설정 세부 원문 참조.
• Retrieve Messages — 공식 하위 절. 구현·설정 세부 원문 참조.
• Session Titles — 공식 하위 절. 구현·설정 세부 원문 참조.

from hermes_state import SessionDB

db = SessionDB()                           # Default: ~/.hermes/state.db
db = SessionDB(db_path=Path("/tmp/test.db"))  # Custom path

전문 검색

원문 절: Full-Text Search

• Basic Search — 공식 하위 절. 구현·설정 세부 원문 참조.
• FTS5 Query Syntax — 공식 하위 절. 구현·설정 세부 원문 참조.
• Filtered Search — 공식 하위 절. 구현·설정 세부 원문 참조.
• Search Results Format — 공식 하위 절. 구현·설정 세부 원문 참조.

Syntax	Example	Meaning
Keywords	docker deployment	Both terms (implicit AND)
Quoted phrase	"exact phrase"	Exact phrase match
Boolean OR	docker OR kubernetes	Either term
Boolean NOT	python NOT java	Exclude term
Prefix	deploy*	Prefix match

results = db.search_messages("docker deployment")

Session Lineage

• Query: Find Session Lineage — 공식 하위 절. 구현·설정 세부 원문 참조.
• Query: Recent Sessions with Preview — 공식 하위 절. 구현·설정 세부 원문 참조.
• Query: Token Usage Statistics — 공식 하위 절. 구현·설정 세부 원문 참조.

-- Find all ancestors of a session
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;

-- Find all descendants of a session
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;

Export and Cleanup

• 이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

# Export a single session with messages
data = db.export_session("sess_abc123")

# Export all sessions (with messages) as list of dicts
all_data = db.export_all(source="cli")

# Delete old sessions (only ended sessions)
deleted_count = db.prune_sessions(older_than_days=90)
deleted_count = db.prune_sessions(older_than_days=30, source="telegram")

# Clear messages but keep the session record
db.clear_messages("sess_abc123")

# Delete session and all messages
db.delete_session("sess_abc123")

Database Location

• 이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

체크리스트

• 공식 원문 Session Storage과 대조했다
• 관련 코드·설정·권한을 로컬에서 확인했다
• 보안·opt-in·allowlist 정책을 지켰다
• 스모크 테스트 또는 단계 검증을 수행했다

다음 단계

• 공식 문서: Session Storage
• Hermes Agent 소개
• 트러블슈팅

---

기준일: 2026-07-26 — 공식 문서 동기화 코퍼스