Armazenamento de Sessões

O Hermes Agent usa um banco SQLite (~/.hermes/state.db) para persistir metadados de sessão, o histórico completo de mensagens e a configuração de modelo entre sessões de CLI e de gateway. Isso substitui a abordagem anterior, de um arquivo JSONL por sessão.

Arquivo-fonte: hermes_state.py

Visão geral da arquitetura

~/.hermes/state.db (SQLite, modo WAL)
├── sessions              — Metadados de sessão, contagens de token, cobrança
├── messages              — Histórico completo de mensagens por sessão
├── session_model_usage   — Linhas de atribuição de uso por modelo/por tarefa
├── messages_fts          — Tabela virtual FTS5 (content + tool_name + tool_calls)
├── messages_fts_trigram  — Tabela virtual FTS5 com tokenizador de trigramas (CJK / busca por substring)
├── messages_fts_cjk      — Tabela virtual FTS5 com tokenizador cjk_unicode61
├── state_meta            — Tabela de metadados chave/valor
├── gateway_routing       — Metadados de roteamento do gateway
├── compression_locks     — Travamento de compressão entre processos
├── async_delegations     — Controle de delegações assíncronas
└── schema_version        — Tabela de uma linha só, acompanhando o estado das migrações

Decisões de projeto importantes:

• Modo WAL para leitores concorrentes + um escritor (gateway multiplataforma)
• Tabela virtual FTS5 para busca de texto rápida em todas as mensagens de sessão
• Linhagem de sessões via cadeias de parent_session_id (divisões disparadas por compressão)
• Marcação de origem (cli, telegram, discord, etc.) para filtragem por plataforma
• O executor de lotes e as trajetórias de RL NÃO ficam armazenados aqui (sistemas separados)

Schema do SQLite

Tabela sessions

Resumida — veja SCHEMA_SQL em hermes_state.py para a lista completa e atual de colunas (que também inclui metadados de roteamento do gateway como session_key, chat_id, chat_type, thread_id, display_name, origin_json, expiry_finalized, os campos de espaço de trabalho cwd / git_branch / git_repo_root, campos de passagem de bastão e de falha de compressão, profile_name, rewind_count, archived e pinned):

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,
    -- ... colunas adicionais de gateway/espaco de trabalho/passagem de bastao/compressao ...
    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;

Tabela messages

Resumida — o schema completo também inclui effect_disposition, platform_message_id, observed, active, compacted, api_content, display_kind e display_metadata:

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
    -- ... colunas adicionais de exibicao/compactacao ...
);

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

Observações:

• tool_calls é armazenado como string JSON (lista serializada de objetos de chamada de ferramenta)
• reasoning_details, codex_reasoning_items e codex_message_items são armazenados como strings JSON
• reasoning guarda o texto cru de raciocínio dos provedores que o expõem
• api_content é um arquivo paralelo com fidelidade de bytes: a string de conteúdo exata enviada à API para esta mensagem quando ela difere de content (injeções efêmeras de memória/plugin, sobrescritas persistidas). Ele preserva os bytes que foram para a rede, para reexecução estável em relação ao cache de prompt — armazenado como enviado, exceto surrogates solitários, que o sqlite3 não consegue vincular e que o laço da conversa remove de todo payload de saída de qualquer forma. NULL significa que o content foi enviado literalmente.
• Timestamps são floats de época Unix (time.time())

Busca de texto completo com FTS5

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

A tabela FTS5 é mantida em sincronia por três triggers que disparam no INSERT, no UPDATE e no DELETE da tabela messages. Os triggers atuais são condicionados aos marcadores fts_rebuild_high_water / fts_rebuild_progress em state_meta (para que uma reconstrução de FTS em segundo plano possa avançar sem indexar em dobro) e cobrem as três colunas indexadas — veja SCHEMA_SQL em hermes_state.py para o SQL exato.

Versão do schema e migrações

Versão atual do schema: 23

A tabela schema_version guarda um único inteiro. Adições simples de coluna são tratadas de forma declarativa por _reconcile_columns() (que compara as colunas vivas com o SCHEMA_SQL e faz ADD nas que faltam). A cadeia condicionada por versão é reservada para migrações de dados e mudanças de índice/FTS que não dão para expressar declarativamente:

Versão	Mudança
1	Schema inicial (sessions, messages, FTS5)
2	Adiciona a coluna finish_reason em messages
3	Adiciona a coluna title em sessions
4	Adiciona índice único em title (NULLs permitidos, os não-NULL precisam ser únicos)
5	Adiciona colunas de cobrança: 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	Adiciona colunas de raciocínio em messages: reasoning, reasoning_details, codex_reasoning_items
7	Adiciona a coluna reasoning_content em messages
8	Adiciona a coluna api_call_count em sessions
9	Adiciona a coluna codex_message_items em messages, para reexecução de id/fase de mensagem do Codex Responses
10	Adiciona a tabela virtual messages_fts_trigram (tokenizador de trigramas para CJK / busca por substring) e preenche as linhas existentes
11	Reindexa messages_fts e messages_fts_trigram para cobrir tool_name + tool_calls e troca do modo de conteúdo externo para o modo embutido; derruba os triggers antigos e preenche cada linha de mensagem
16	Marca as linhas de subagente delegado em model_config ($._delegate_from) para que os seletores de sessão fiquem limpos depois que exclusões no pai as deixam órfãs
18	Consolidação de metadados de gateway — preenche display_name / origin_json / expiry_finalized a partir de sessions.json
20	Atribuição de uso por modelo — semeia as linhas de session_model_usage a partir dos totais agregados históricos por sessão
22	Atribuição de uso com dimensão de tarefa — reconstrói session_model_usage para que a coluna task participe da PRIMARY KEY
23	Redesenho do armazenamento de FTS — tabelas FTS de conteúdo externo substituindo as cópias em modo embutido da v11 (transição opcional para bancos existentes)

As versões não listadas acima foram adições declarativas de coluna, tratadas por _reconcile_columns() (só o número da versão sobe, sem migração de dados).

As adições declarativas de coluna usam ALTER TABLE ADD COLUMN embrulhado em try/except para lidar com o caso de a coluna já existir (idempotente). O número da versão sobe depois de cada bloco de migração bem-sucedido.

Tratamento de contenção de escrita

Vários processos do hermes (gateway + sessões de CLI + agentes em worktree) compartilham um único state.db. A classe SessionDB lida com a contenção de escrita assim:

• Timeout curto do SQLite (1 segundo) em vez dos 30s padrão
• Nova tentativa no nível da aplicação com jitter aleatório (20-150ms, até 15 tentativas)
• Transações BEGIN IMMEDIATE para expor a contenção de trava no começo da transação
• Checkpoints periódicos de WAL a cada 50 escritas bem-sucedidas (modo PASSIVE)

Isso evita o "efeito comboio", em que o recuo interno determinístico do SQLite faz todos os escritores concorrentes tentarem de novo nos mesmos intervalos.

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

Operações comuns

Inicializar

from hermes_state import SessionDB

db = SessionDB()                           # Padrão: ~/.hermes/state.db
db = SessionDB(db_path=Path("/tmp/test.db"))  # Caminho personalizado

Criar e gerenciar sessões

# Cria uma nova sessão
db.create_session(
    session_id="sess_abc123",
    source="cli",
    model="anthropic/claude-sonnet-4.6",
    user_id="user_1",
    parent_session_id=None,  # ou o ID da sessão anterior, para linhagem
)

# Encerra uma sessão
db.end_session("sess_abc123", end_reason="user_exit")

# Reabre uma sessão (limpa ended_at/end_reason)
db.reopen_session("sess_abc123")

Armazenar mensagens

msg_id = db.append_message(
    session_id="sess_abc123",
    role="assistant",
    content="Aqui está a resposta...",
    tool_calls=[{"id": "call_1", "function": {"name": "terminal", "arguments": "{}"}}],
    token_count=150,
    finish_reason="stop",
    reasoning="Deixa eu pensar nisso...",
)

Recuperar mensagens

# Mensagens cruas com todos os metadados
messages = db.get_messages("sess_abc123")

# Formato de conversa da OpenAI (para reexecução via API)
conversation = db.get_messages_as_conversation("sess_abc123")
# Retorna: [{"role": "user", "content": "..."}, {"role": "assistant", ...}]

Títulos de sessão

# Define um título (precisa ser único entre os títulos não-NULL)
db.set_session_title("sess_abc123", "Corrigir o build do Docker")

# Resolve pelo título (devolve o mais recente da linhagem)
session_id = db.resolve_session_by_title("Corrigir o build do Docker")

# Gera automaticamente o próximo título da linhagem
next_title = db.get_next_title_in_lineage("Corrigir o build do Docker")
# Retorna: "Corrigir o build do Docker #2"

Busca de texto completo

O método search_messages() suporta a sintaxe de consulta do FTS5, com sanitização automática da entrada do usuário.

Busca básica

results = db.search_messages("docker deployment")

Sintaxe de consulta do FTS5

Sintaxe	Exemplo	Significado
Palavras-chave	docker deployment	Os dois termos (AND implícito)
Frase entre aspas	"exact phrase"	Correspondência exata da frase
OR booleano	docker OR kubernetes	Qualquer um dos termos
NOT booleano	python NOT java	Exclui o termo
Prefixo	deploy*	Correspondência por prefixo

Busca com filtros

# Busca só em sessões de CLI
results = db.search_messages("error", source_filter=["cli"])

# Exclui sessões de gateway
results = db.search_messages("bug", exclude_sources=["telegram", "discord"])

# Busca só em mensagens do usuário
results = db.search_messages("help", role_filter=["user"])

Formato dos resultados da busca

Cada resultado inclui:

• id, session_id, role, timestamp
• snippet — trecho gerado pelo FTS5 com marcadores >>>match<<<
• context — 1 mensagem antes e 1 depois da correspondência (conteúdo truncado em 200 caracteres)
• source, model, session_started — da sessão pai

O método _sanitize_fts5_query() lida com casos de borda:

• Remove aspas sem par e caracteres especiais
• Envolve termos com hífen em aspas (chat-send → "chat-send")
• Remove operadores booleanos soltos no fim (hello AND → hello)

Linhagem de sessões

Sessões podem formar cadeias via parent_session_id. Isso acontece quando a compressão de contexto dispara uma divisão de sessão no gateway.

Consulta: encontrar a linhagem de uma sessão

-- Encontra todos os ancestrais de uma sessao
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;

-- Encontra todos os descendentes de uma sessao
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;

Consulta: sessões recentes com prévia

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;

Consulta: estatísticas de uso de tokens

-- Total de tokens por modelo
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;

-- Sessoes com maior uso de tokens
SELECT id, title, model, input_tokens + output_tokens AS total_tokens,
       estimated_cost_usd
FROM sessions
ORDER BY total_tokens DESC
LIMIT 10;

Exportar e limpar

# Exporta uma única sessão com as mensagens
data = db.export_session("sess_abc123")

# Exporta todas as sessões (com mensagens) como lista de dicionários
all_data = db.export_all(source="cli")

# Apaga sessões antigas (só as encerradas)
deleted_count = db.prune_sessions(older_than_days=90)
deleted_count = db.prune_sessions(older_than_days=30, source="telegram")

# Limpa as mensagens mas mantém o registro da sessão
db.clear_messages("sess_abc123")

# Apaga a sessão e todas as mensagens
db.delete_session("sess_abc123")

Localização do banco

Caminho padrão: ~/.hermes/state.db

Ele vem de hermes_constants.get_hermes_home(), que resolve para ~/.hermes/ por padrão, ou para o valor da variável de ambiente HERMES_HOME.

O arquivo do banco, o arquivo WAL (state.db-wal) e o arquivo de memória compartilhada (state.db-shm) são todos criados no mesmo diretório.

---