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

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

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

Обзор архитектуры

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

Ключевые проектные решения:

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

Схема SQLite

Таблица 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 синхронизируется с помощью трёх триггеров, срабатывающих при 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 и добавляет недостающие). Цепочка с привязкой к версии зарезервирована для миграций данных и изменений индексов/FTS, которые нельзя выразить декларативно:

Версия	Изменение
1	Начальная схема (sessions, messages, FTS5)
2	Добавлен столбец finish_reason в messages
3	Добавлен столбец title в sessions
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
7	Добавлен столбец reasoning_content в messages
8	Добавлен столбец api_call_count в sessions
9	Добавлен столбец codex_message_items в messages для воспроизведения id/фазы сообщений Codex Responses
10	Добавлена виртуальная таблица messages_fts_trigram (триграммный токенизатор для CJK / поиска подстрок) и обратное заполнение существующих строк
11	Переиндексация messages_fts и messages_fts_trigram для включения tool_name + tool_calls и переход от режима external-content к inline; удаление старых триггеров и обратное заполнение каждой строки сообщения

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

Обработка конфликтов записи

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

• Короткого таймаута SQLite (1 секунда) вместо стандартных 30 с
• Повторов на уровне приложения со случайной задержкой (20–150 мс, до 15 попыток)
• Транзакций BEGIN IMMEDIATE для выявления конфликтов блокировки в начале транзакции
• Периодических контрольных точек WAL каждые 50 успешных записей (режим PASSIVE)

Это позволяет избежать «эффекта конвоя», когда детерминированная внутренняя задержка 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 vibeos_state import SessionDB

db = SessionDB()                           # По умолчанию: ~/.vibeos/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

Синтаксис	Пример	Значение
Ключевые слова	docker развёртывание	Оба термина (неявное И)
Фраза в кавычках	"точная фраза"	Точное совпадение фразы
Логическое ИЛИ	docker OR kubernetes	Любой из терминов
Логическое НЕ	python NOT java	Исключить термин
Префикс	развёртыв*	Совпадение по префиксу

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

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

# Исключение gateway-сессий
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. Это происходит, когда сжатие контекста вызывает разделение сессии в gateway.

Запрос: поиск линейки сессий

-- Поиск всех предков сессии
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")

Расположение базы данных

Путь по умолчанию: ~/.vibeos/state.db

Это значение получается из vibeos_constants.get_vibeos_home(), которая по умолчанию возвращает ~/.vibeos/ или значение переменной окружения VIBEOS_HOME.

Файл базы данных, файл WAL (state.db-wal) и файл разделяемой памяти (state.db-shm) создаются в одном каталоге.