Хранилище сессий

Агент Hermes использует ресурсы данных SQLite (~/.hermes/state.db) для сохранения метаданных сессий, полной истории сообщений и конфигурации моделей в сессиях CLI и шлюза. Это заменяет прежний подход с указанием JSONL-файлов для каждой сессии.

Исходный файл: hermes_state.py

Обзор конструкции

~/.hermes/state.db (SQLite, режим WAL)
├── sessions              — Метаданные сессий, количество токенов, биллинг
├── messages              — Полная история сообщений для каждой сессии
├── messages_fts          — Виртуальная таблица FTS5 (content + tool_name + tool_calls)
├── messages_fts_trigram  — Виртуальная таблица FTS5 с триграммным токенизатором (CJK / поиск подстрок)
├── state_meta            — Таблица метаданных ключ/значение
└── schema_version        — Таблица с одной строкой, отслеживающая состояние миграций

Ключевые проектные решения: - Режим WAL для одновременных читателей + один писатель (многоплатформенный шлюз) - Виртуальная таблица FTS5 для быстрого текстового поиска по всем сообщениям сессий. - Линия наследования сессий через цепочку parent_session_id (разделение, вызванное сжатием) - Маркировка источника (cli, telegram, discord и т.д.) для фильтра на платформе - Пакетный раннер и RL-траектории НЕ хранения здесь (отдельные системы)

Схема SQLite

Таблица Сессий

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;

Таблица Сообщений

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 (time.time())

Полнотекстовый поиск FTS5

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

Таблица FTS5 синхронизируется с помощью трёх триггеров, которые срабатывают при INSERT, UPDATE и DELETE в таблице messages:

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;

Версия схемы и приложения

Текущая версия схемы: 11

Таблица schema_version хранит одно значение числа. Простые добавления столбцов обрабатываются декларативно с помощью _reconcile_columns() (который сравнивает случайные столбцы с SCHEMA_SQL и ADDit недостающие). Цепочка, управляемая версиями, зарезервирована для миграции данных и изменений индексов/ФНС, которые нельзя выразить декларативно:

Версия	Изменение
1	Начальная схема (сессии, сообщения, FTS5)
2	Добавлен столбец `finish_reason` в сообщения
3	Добавлен столбец `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	Добавлены столбцы рассуждений в сообщениях: `reasoning`, `reasoning_details`, `codex_reasoning_items`
7	Добавлен столбец `reasoning_content` в сообщения
8	Добавлен столбец `api_call_count` в сеансах
9	Добавлен столбец `codex_message_items` в сообщениях для идентификации идентификатора/фазы сообщений Ответы Кодекса
10	Добавлена виртуальная таблица `messages_fts_trigram` (триграммный токенизатор для CJK / поиск подстрок) и обратное заполнение существующей строки
11	Переиндексация `messages_fts` и `messages_fts_trigram` для покрытия `tool_name` + `tool_calls` и переключение режима внешнего вида на встроенный; удаление старых триггеров и обратное заполнение каждой строки сообщения

Декларативное добавление столбцов использует ALTER TABLE ADD COLUMN, обернутый в попытке/за исключением случая обработки, когда столбец уже существует (идемпотентность). Число версий увеличивается после того, как каждый из них выигрывает блок Великобритании.

Обработка ошибок

Несколько процессов Hermes (шлюз + сессия CLI + агенты рабочего дерева) используют один state.db. Класс SessionDB обрабатывает конфликтные ситуации с помощью:

Короткий таймаут SQLite (1 секунда) вместо стандартных 30 с.
Повторов на уровне приложения со случайной задержкой (20-150 мс, до 15 повторов)
Транзакции НАЧИНАЮТСЯ IMMEDIATE для анализов, блокировок в начале транзакции.
Периодические контрольные точки WAL возглавляют 50 успешных записей (режим ПАССИВНЫЙ)

Это позволяет избежать «эффекта конвоя», когда определенная внутренняя задержка SQLite заставляет всех конкурирующих писателей повторять процедуру с одинаковыми интервалами.

_WRITE_MAX_RETRIES = 15
_WRITE_RETRY_MIN_S = 0.020   # 20 мс
_WRITE_RETRY_MAX_S = 0.150   # 150 мс
_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="Вот ответ...",
    tool_calls=[{"id": "call_1", "function": {"name": "terminal", "arguments": "{}"}}],
    token_count=150,
    finish_reason="stop",
    reasoning="Давайте подумаем об этом...",
)

Получение сообщений

# Необработанные сообщения со всеми метаданными
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", "Исправить сборку Docker")

# Поиск по заголовку (возвращает самую последнюю в линии наследования)
session_id = db.resolve_session_by_title("Исправить сборку Docker")

# Автоматическая генерация следующего заголовка в линии наследования
next_title = db.get_next_title_in_lineage("Исправить сборку Docker")
# Возвращает: "Исправить сборку Docker #2"

Полнотекстовый поиск

Метод search_messages() поддерживает синтаксис запросов FTS5 с автоматической санацией пользовательского ввода.

Базовый поиск

results = db.search_messages("развертывание docker")

Синтаксис запроса FTS5

Синтаксис	Пример	Значение
Ключевые слова	`развертывание докера`	Оба термина (неявное AND)
Фраза в кавычках	`"точная фраза"`	Совпадение точных фраз
Булево ОР	`докер ИЛИ kubernetes`	Любой из терминов
Булево НЕ	`python НЕ Java`	Исключить термин
Префикс	`разверт*`	Совпадение по префиксу

Фильтрованный поиск

# Поиск только в сессиях CLI
results = db.search_messages("ошибка", source_filter=["cli"])

# Исключение сессий шлюза
results = db.search_messages("баг", exclude_sources=["telegram", "discord"])

# Поиск только сообщений пользователя
results = db.search_messages("помощь", 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;

Запрос: Статистика использования токенов

-- Всего токенов по моделям
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;

-- Сессии с наибольшим использованием токенов
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) передаются в одном каталоге.