microdao-daarion/HELION-MEMORY-TYPES.md

# 🧠 Типи пам'яті для агента Helion

**Дата:** 2026-01-12  
**Агент:** Helion (Energy Union)

---

## 📋 Огляд системи пам'яті

Helion використовує **Memory Service** для збереження та отримання контексту діалогів. Система пам'яті інтегрована через `memory_client.py` в Gateway сервісі.

---

## 🧠 Типи пам'яті

### 1. **Facts (Факти)**
**Призначення:** Довгострокові факти про користувача та команду

**Характеристики:**
- Зберігаються назавжди (до явного видалення)
- Структуровані дані (ключ-значення)
- Можуть містити JSON дані
- Прив'язані до `user_id` та опціонально до `team_id`

**API:**
- `GET /facts` - отримати всі факти користувача
- `POST /facts/upsert` - створити/оновити факт
- `GET /facts/{fact_key}` - отримати конкретний факт

**Приклад використання:**
```python
# Зберегти факт
await memory_client.upsert_fact(
    user_id="user123",
    fact_key="preferred_language",
    fact_value="uk",
    team_id="energy_union"
)

# Отримати факт
fact = await memory_client.get_fact(
    user_id="user123",
    fact_key="preferred_language"
)
```

---

### 2. **Events (Події/Повідомлення)**
**Призначення:** Короткострокова пам'ять про діалоги та взаємодії

**Характеристики:**
- Зберігаються з `scope` (short_term / long_term)
- Містять повідомлення користувача та відповіді агента
- Можуть бути фільтровані за `agent_id`, `channel_id`, `kind`
- Обмежені за кількістю (limit параметр)

**API:**
- `GET /agents/{agent_id}/memory` - отримати події агента
- `POST /agents/{agent_id}/memory` - зберегти подію

**Параметри:**
- `scope`: `short_term` (нещодавні) або `long_term` (архівні)
- `kind`: `message` (повідомлення), `action` (дії), тощо
- `limit`: кількість останніх подій

**Приклад використання:**
```python
# Зберегти turn діалогу
await memory_client.save_chat_turn(
    agent_id="helion",
    team_id="energy_union",
    user_id="user123",
    message="Яка ціна на токени?",
    response="Ціна токенів ENERGY зараз...",
    channel_id="telegram_chat_123",
    scope="short_term"
)
```

---

### 3. **Summaries (Підсумки діалогів)**
**Призначення:** Стислі підсумки довгих діалогів для масштабування контексту

**Характеристики:**
- Створюються для періодів часу
- Містять стислий опис теми діалогу
- Можуть містити теми (topics) та метадані
- Використовуються для зменшення обсягу контексту

**API:**
- `GET /summaries` - отримати підсумки
- `POST /summaries` - створити підсумок

**Приклад використання:**
```python
# Створити підсумок діалогу
await memory_client.create_dialog_summary(
    team_id="energy_union",
    channel_id="telegram_chat_123",
    agent_id="helion",
    user_id="user123",
    period_start=datetime(2026, 1, 1, 10, 0),
    period_end=datetime(2026, 1, 1, 11, 0),
    summary_text="Обговорення токеноміки ENERGY та правил стейкінгу",
    message_count=25,
    participant_count=2,
    topics=["tokenomics", "staking", "energy"]
)
```

---

## 🔄 Контекст пам'яті для діалогу

При обробці повідомлення Gateway автоматично отримує контекст пам'яті:

```python
memory_context = await memory_client.get_context(
    user_id="user123",
    agent_id="helion",
    team_id="energy_union",
    channel_id="telegram_chat_123",
    limit=10
)
```

**Структура контексту:**
```json
{
    "facts": [
        {"fact_key": "preferred_language", "fact_value": "uk"},
        {"fact_key": "user_role", "fact_value": "investor"}
    ],
    "recent_events": [
        {
            "body_text": "Попереднє повідомлення користувача",
            "body_json": {"type": "user_message"},
            "created_at": "2026-01-12T10:00:00Z"
        }
    ],
    "dialog_summaries": [
        {
            "summary_text": "Попередній діалог про токеноміку",
            "topics": ["tokenomics"],
            "period_start": "2026-01-11T09:00:00Z"
        }
    ]
}
```

Цей контекст передається в Router разом з повідомленням для генерації відповіді.

---

## 💾 Backend Storage

Memory Service використовує наступні бази даних:

### PostgreSQL
- **База:** `daarion_memory`
- **Таблиці:** 
  - `facts` - довгострокові факти
  - `agent_memory` - події/повідомлення
  - `dialog_summaries` - підсумки діалогів

### Redis (опціонально)
- Кешування контексту (TTL: 5 секунд за замовчанням)
- Швидкий доступ до нещодавніх подій

---

## 🔧 Конфігурація

**Змінні середовища:**
- `MEMORY_SERVICE_URL` - URL Memory Service (за замовчанням: `http://memory-service:8000`)
- `MEMORY_CONTEXT_CACHE_TTL` - TTL кешу контексту в секундах (за замовчанням: 5)

**В docker-compose.node1.yml:**
```yaml
environment:
  - MEMORY_SERVICE_URL=http://memory-service:8000
```

---

## 📊 Схема роботи

```
Telegram Message
    ↓
Gateway (Helion)
    ↓
1. Отримати контекст пам'яті (facts + events + summaries)
    ↓
2. Передати повідомлення + контекст в Router
    ↓
3. Router генерує відповідь з урахуванням контексту
    ↓
4. Gateway зберігає turn діалогу (message + response)
    ↓
5. Відправити відповідь в Telegram
```

---

## ⚠️ Важливо

1. **Memory Service опціональний** - якщо він недоступний, Gateway працює без пам'яті
2. **Кешування** - контекст кешується на 5 секунд для оптимізації
3. **Обмеження** - кількість подій обмежена параметром `limit` (за замовчанням: 10)
4. **Scope** - `short_term` для нещодавніх подій, `long_term` для архіву

---

**Оновлено:** 2026-01-12