# Agent Memory Standard

## Архітектура пам'яті агентів DAARION

Кожен агент має доступ до трирівневої системи пам'яті:

### 1. Векторна пам'ять (Qdrant)

**Стандартні колекції на агента:**

| Колекція | Призначення | Dimension |
|----------|-------------|-----------|
| `{agent}_messages` | Історія повідомлень діалогів | 1024 |
| `{agent}_docs` | Документи та knowledge base | 1024 |
| `{agent}_memory_items` | Long-term memory items | 1024 |
| `{agent}_user_context` | Контекст користувачів | 1024 |

**Embedding model:** Cohere embed-multilingual-v3.0 (1024 dimensions)

### 2. Реляційна пам'ять (PostgreSQL)

**Таблиця `user_facts`:**
- `fact_id` - UUID
- `user_id` - ID користувача
- `team_id` - ID команди/DAO
- `agent_id` - ID агента
- `fact_key` - Ключ факту (наприклад: `name`, `preferences`, `chat_event:...`)
- `fact_value` - Текстове значення
- `fact_value_json` - JSONB для структурованих даних

### 3. Графова пам'ять (Neo4j)

**Node types:**
- `Agent` - агенти системи
- `User` - користувачі
- `Channel` - канали/чати
- `Message` - повідомлення
- `Topic` - теми розмов
- `Project` - проєкти

**Relationships:**
- `(User)-[:SENT]->(Message)`
- `(Agent)-[:RESPONDED]->(Message)`
- `(Message)-[:IN_CHANNEL]->(Channel)`
- `(Message)-[:ABOUT]->(Topic)`

## Стандарт іменування колекцій

```
{agent_id}_{collection_type}
```

Приклади:
- `helion_messages`
- `nutra_docs`
- `agromatrix_user_context`

## Спеціальні колекції

| Колекція | Агент | Призначення |
|----------|-------|-------------|
| `druid_legal_kb` | DRUID | Юридична база знань |
| `helion_artifacts` | HELION | Артефакти Energy Union |
| `nutra_food_knowledge` | NUTRA | База нутрієнтів |
| `cm_text_1024_v1` | Shared | Co-Memory спільні тексти |

## API Endpoints

### Memory Service (порт 8000)

```
POST /agents/{agent_id}/memory
  - Зберегти повідомлення/факт

GET /agents/{agent_id}/context
  - Отримати контекст для діалогу

GET /health
  - Health check
```

## Приклад збереження пам'яті

```python
await memory_client.save_memory(
    agent_id="helion",
    user_id="123456",
    channel_id="chat_789",
    content="User asked about solar panels",
    role="user",
    metadata={"topic": "energy", "intent": "question"}
)
```

## Статистика (2026-01-28)

| Агент | Messages | Docs | Memory Items | PG Facts |
|-------|----------|------|--------------|----------|
| HELION | 401 | 0 | 0 | 84 |
| NUTRA | 476 | 0 | 0 | 373 |
| AGROMATRIX | 78 | 0 | 0 | 56 |
| GREENFOOD | 26 | 0 | 0 | 16 |
| DRUID | 8 | 0 | 0 | 8 |
| DAARWIZZ | 8 | 0 | 0 | 8 |
| ALATEYA | 8 | 0 | 0 | 8 |
| CLAN | 8 | 0 | 0 | 8 |
| EONARCH | 8 | 0 | 0 | 8 |

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