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} - отримати конкретний факт

Приклад використання:

# Зберегти факт
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: кількість останніх подій

Приклад використання:

# Зберегти 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 - створити підсумок

Приклад використання:

# Створити підсумок діалогу
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 автоматично отримує контекст пам'яті:

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

Структура контексту:

{
    "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:

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