telegram-cli-bot/VECTOR_RAG_MEMORY.md

# 🧠 Векторная память с RAG и градиентной памятью

Гибридная система памяти для ИИ-чата на **SQLite + ChromaDB** с **градиентной детализацией**.

---

## 📋 Обзор

Система использует **трёхуровневую архитектуру** памяти:

1. **STM (Short-Term Memory)** — последние 5 сообщений — **полностью**
2. **LTM (Long-Term Memory)** — сообщения 6-20 — **сжато (50 символов)**
3. **RAG (Retrieval-Augmented Generation)** — глубокий поиск через ChromaDB

**Модель эмбеддингов:** `all-MiniLM-L6-v2`
- Размер: 90MB
- Измерения: 384
- Скорость: ~1000 эмбеддингов/сек на CPU
- Потребление памяти: <200MB

---

## 🏗️ Архитектура

```
┌─────────────────────────────────────────────────────────┐
│                   Telegram Bot (bot.py)                 │
│                                                         │
│  ┌─────────────┐    ┌──────────────┐    ┌───────────┐ │
│  │ handle_ai_  │───▶│ hybrid_      │───▶│ qwen_     │ │
│  │ task()      │    │ memory_      │    │ integration│ │
│  └─────────────┘    │ manager      │    └───────────┘ │
│                     └───────┬──────┘                    │
│            ┌────────────────┼────────────────┐         │
│            │                │                │         │
│            ▼                ▼                │         │
│  ┌──────────────────┐ ┌──────────────────┐  │         │
│  │  SQLiteStorage   │ │  VectorStorage   │  │         │
│  │  (facts,         │ │  (ChromaDB,      │  │         │
│  │   messages,      │ │   sentence-      │  │         │
│  │   sessions)      │ │   transformers)  │  │         │
│  └──────────────────┘ └──────────────────┘  │         │
│                                            │         │
└────────────────────────────────────────────┼───────────┘
```

### Градиентная память (как работает):

```
┌──────────────────────────────────────────────────────┐
│  КОНТЕКСТ ДЛЯ ИИ                                      │
├──────────────────────────────────────────────────────┤
│  📋 ПРОФИЛЬ ПОЛЬЗОВАТЕЛЯ (факты из SQLite)           │
├──────────────────────────────────────────────────────┤
│  💬 STM: Последние 5 сообщений (ПОЛНОСТЬЮ)           │
│     • Чёткая память о недавнем                       │
│     • Полный текст без сокращений                    │
├──────────────────────────────────────────────────────┤
│  🕰️ LTM: Сообщения 6-20 (СЖАТО: 50 символов)        │
│     • Размытая память о прошлом                      │
│     • Краткое содержание для контекста               │
├──────────────────────────────────────────────────────┤
│  🔍 RAG: Релевантные сообщения по запросу            │
│     • Глубокий поиск через ChromaDB                  │
│     • Семантический поиск по всем сообщениям         │
└──────────────────────────────────────────────────────┘
```

---

## 🔧 Компоненты

### vector_memory.py

**VectorMemoryStorage** — векторное хранилище:
- `add_message()` — добавить сообщение с эмбеддингом
- `search_similar()` — семантический поиск по запросу
- `search_by_session()` — поиск внутри сессии
- `get_stats()` — статистика

**HybridMemoryManager** — гибридный менеджер:
- `add_message()` — сохранение в SQLite + ChromaDB
- `search_relevant()` — приоритет векторному поиску, фоллбэк на LIKE
- `format_context_for_ai()` — контекст для ИИ с профилем и релевантными сообщениями
- `extract_and_save_facts()` — извлечение фактов из сообщений

### memory_system.py

**SQLiteMemoryStorage** — реляционное хранилище:
- Таблицы: `facts`, `messages`, `sessions`
- Поиск через `LIKE`
- Извлечение фактов по эвристикам

---

## 📊 Команды

### /memory — Статистика памяти

```
🧠 Статистика памяти:

📊 Сообщений: 42
📌 Фактов: 5
📁 Сессий: 3

🔮 Векторная память:
  Документы: 42
  Модель: all-MiniLM-L6-v2

Память использует SQLite + ChromaDB с семантическим поиском.
```

---

## 🚀 Использование

### Сохранение сообщения:

```python
from vector_memory import save_message

save_message(user_id=123456, role="user", content="Меня зовут Владимир")
save_message(user_id=123456, role="assistant", content="Приятно познакомиться!")
```

### Семантический поиск:

```python
from vector_memory import search_memory

# Найти сообщения по смыслу (не точное совпадение!)
results = search_memory(user_id=123456, query="как настроить сервер", limit=5)

for msg, score in results:
    print(f"{score:.2f}: {msg.content}")
```

### Контекст для ИИ (градиентная память):

```python
from vector_memory import get_context

# Градиентная память: STM=5, LTM=15
context = get_context(user_id=123456, query="Где мои файлы?", stm_size=5, ltm_size=15)

# Структура контекста:
# - 📋 Профиль пользователя (факты)
# - 💬 STM: Последние 5 сообщений (полностью)
# - 🕰️ LTM: Сообщения 6-20 (сжато, по 50 символов)
# - 🔍 RAG: Релевантные сообщения по запросу
```

### Команды бота:

- `/memory` — статистика памяти
- `/memory_test` — тестирование градиентной памяти
- `/facts` — показать сохранённые факты
- `/compact` — запустить компактификацию истории

---

## 📁 Файлы

- `vector_memory.py` — векторная память (ChromaDB + sentence-transformers)
- `memory_system.py` — SQLite память
- `memory.db` — SQLite база данных
- `vector_db/` — ChromaDB хранилище

---

## ⚙️ Настройка

### Требования:

```bash
pip install chromadb sentence-transformers
```

### Модель эмбеддингов:

По умолчанию используется `all-MiniLM-L6-v2` (лёгкая, быстрая).

Для изменения модели:

```python
vector_storage = VectorMemoryStorage(
    persist_directory="./vector_db",
    model_name="all-mpnet-base-v2"  # Более точная, но тяжелее
)
```

**Доступные модели:**
- `all-MiniLM-L6-v2` — 90MB, 384 dim (быстрая)
- `all-mpnet-base-v2` — 420MB, 768 dim (точная)
- `paraphrase-multilingual-MiniLM-L12-v2` — мультиязычная

---

## 🎯 Как работает RAG

1. **Пользователь отправляет сообщение** → сохраняется в SQLite + ChromaDB
2. **ИИ запрашивает контекст** → гибридный менеджер формирует промпт:
   - Профиль пользователя (факты)
   - Последние N сообщений
   - Релевантные сообщения из векторного поиска
3. **ИИ получает контекст** → отвечает с учётом истории

**Пример:**
```
User: Помнишь, я спрашивал про настройку nginx?

RAG находит:
- Сообщение 3-дневной давности про nginx config
- Факт: "Использует nginx"

ИИ отвечает:
"Да, вы спрашивали про настройку nginx. Вот что мы обсуждали..."
```

---

## 📈 Производительность

| Операция | Время |
|----------|-------|
| Добавление сообщения | ~50ms |
| Векторный поиск (5 результатов) | ~100ms |
| Извлечение фактов | ~5ms |
| Формирование контекста | ~20ms |

**Потребление памяти:**
- Модель: ~200MB
- ChromaDB: ~100-500MB (зависит от количества сообщений)
- SQLite: ~10MB
- **Итого: <1GB** ✅

---

## 🔒 Безопасность

- Данные хранятся локально
- Нет отправки третьим сторонам
- Можно удалить: `rm memory.db vector_db/`