# Specification: Swarm Memory Architecture

## 1. Goal
Определить структуру и логику хранения данных роя: краткосрочного контекста текущих задач и долгосрочных знаний о предпочтениях пользователя, исключая смешивание контекстов при работе с разными репозиториями и минимизируя расход квот Gemini API.

---

## 2. Централизованная база данных сессий (Centralized Sessions DB)

Для отслеживания истории выполнения задач, хранения переписки и промежуточных состояний используется централизованная база данных **SQLite** на стороне Telegram-моста.

*   **Путь к БД:** `Gemini_Swarm_Core/sessions.db` (на VPS: `/opt/Gemini_Swarm_Core/sessions.db`).
*   **Режим работы SQLite:** Включен режим **WAL (Write-Ahead Logging)**, `busy_timeout=10000` (10 секунд) и `synchronous=NORMAL` для предотвращения блокировок базы (`database is locked`) при конкурентных записях.

### Структура таблиц изоляции:

1.  **Таблица `sessions`:**
    Содержит реестр всех созданных изолированных задач:
    ```sql
    CREATE TABLE IF NOT EXISTS sessions (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        repo_path TEXT NOT NULL,                -- Путь к целевому проекту на диске (CWD)
        task_name TEXT NOT NULL,                -- Имя задачи (например, task-a1b2c3d4)
        conversation_id TEXT NOT NULL,          -- UUID сессии для флага --conversation в agy
        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
        UNIQUE(repo_path, task_name)
    );
    ```
2.  **Таблица `chat_history` (с изоляцией по задачам):**
    ```sql
    CREATE TABLE IF NOT EXISTS chat_history (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        session_id TEXT NOT NULL,               -- Идентификатор чата в Telegram
        role TEXT NOT NULL,                     -- Роль (user / model)
        text TEXT NOT NULL,
        timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
        session_db_id INTEGER DEFAULT NULL      -- Внешний ключ на sessions.id
    );
    ```

---

## 3. Механизм изоляции контекста (Context Isolation)

Изоляция выполняется на трех уровнях:

1.  **Логическая изоляция БД:** При извлечении истории для CEO в `ask_ceo()` выборка делается строго с фильтром по `session_db_id IS active_session_id`. История прошлых или чужих задач никогда не попадает в контекстное окно текущей сессии.
2.  **Изоляция на уровне файловой системы (CWD):** В функциях `ask_ceo()`, `extract_and_save_ltm()` и `run_task_logic()` рабочий каталог запуска процесса `agy` принудительно устанавливается в `active_repo_path` текущего проекта.
3.  **Изоляция сессий Antigravity Engine:** При вызове CLI передается флаг `--conversation <conversation_id>` с UUID текущей задачи, что разграничивает внутренний кэш диалогов движка `agy`.

---

## 4. Долгосрочная память (Long-Term Memory & Quota Optimization)

Долгосрочные факты и предпочтения пользователя сохраняются в таблице `long_term_memory`:
```sql
CREATE TABLE IF NOT EXISTS long_term_memory (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT NOT NULL,                   -- Идентификатор чата в Telegram
    fact TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

### Регламент оптимизации квот (Gemini API):
1.  **Пакетная экстракция (Batching):** Автоматический вызов `extract_and_save_ltm` для анализа переписки и извлечения новых фактов происходит только **каждые 20 сообщений** (вместо извлечения на каждое сообщение), что снижает затраты токенов на LTM-запросы в 20 раз.
2.  **Ручное управление (`/remember`):** Пользователь может вручную сохранить факт через команду `/remember [факт]` или принудительно запустить экстракцию фактов из последнего диалога, отправив команду `/remember` без аргументов.
3.  **Ротация истории (DB Hygiene):** База данных автоматически удерживает не более 200 сообщений на одну сессию (лишние удаляются методом TRIM при каждом сохранении ответа CEO).
4.  **PRAGMA optimize:** SQLite оптимизирует индексы и статистику выполнения запросов при каждой graceful-остановке сервиса.