# Policy Engine для Agent Memory

**Дата:** 2026-01-10  
**Версія:** 1.0.0

---

## 🎯 Призначення

Policy Engine визначає **семантичні правила** для пам'яті агентів:
- Що запам'ятовувати в `long_term_memory_items`
- Хто має право писати "факт"
- Як підтверджується / видаляється пам'ять
- Retention policies

---

## 📋 Правила пам'яті

### 1. Що йде в Long-term Memory

**Запам'ятовується:**
- ✅ Факти про користувача (ім'я, преференції, обмеження)
- ✅ Факти про проєкт (назва, мета, технології)
- ✅ Встановлені правила та політики
- ✅ Підтверджені користувачем рішення

**НЕ запам'ятовується:**
- ❌ Тимчасові контексти (йдуть в short-term)
- ❌ Непідтверджені припущення
- ❌ Технічні деталі виконання (йдуть в logs)
- ❌ Чутливі дані без явного дозволу

### 2. Хто має право писати факт

**Джерела фактів:**
- `user_confirmed` — користувач явно підтвердив
- `agent_extracted` — агент витягнув з контексту (низька confidence)
- `system_rule` — системне правило (висока confidence)

**Права:**
- Тільки `agent_extracted` з `confidence > 0.7` → автоматично в long-term
- `confidence < 0.7` → потребує підтвердження користувача
- `is_sensitive=true` → завжди потребує підтвердження

### 3. Підтвердження / Видалення пам'яті

**Механізм feedback:**
- Користувач може: `confirm`, `reject`, `edit`, `delete`
- Після `confirm` → `confidence += 0.1`, `last_confirmed_at = now()`
- Після `reject` → `confidence -= 0.3`, можливе видалення
- Після `edit` → оновлення `fact_text`, `confidence = 0.8`

### 4. Retention Policies

**Типи:**
- `permanent_until_revoked` — залишається до явного видалення
- `ttl_7d` — автоматичне видалення через 7 днів
- `ttl_30d` — автоматичне видалення через 30 днів
- `confidence_based` — видаляється якщо `confidence < 0.3` протягом 30 днів

---

## 🔧 Реалізація

### Policy Rules (PostgreSQL)

```sql
CREATE TABLE memory_policy_rules (
    rule_id UUID PRIMARY KEY,
    org_id UUID NOT NULL,
    category VARCHAR(100) NOT NULL,
    condition JSONB NOT NULL,  -- e.g., {"confidence": {"gte": 0.7}}
    action VARCHAR(50) NOT NULL,  -- e.g., "auto_confirm", "require_user_approval"
    priority INTEGER DEFAULT 0,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
```

### Policy Engine (Python)

```python
class MemoryPolicyEngine:
    async def should_store_in_long_term(self, memory_item: dict) -> bool:
        """Перевірка, чи має пам'ять йти в long-term"""
        # Перевірка правил
        pass
        
    async def requires_user_confirmation(self, memory_item: dict) -> bool:
        """Перевірка, чи потрібне підтвердження користувача"""
        # Перевірка confidence, is_sensitive, etc.
        pass
        
    async def apply_retention_policy(self, memory_id: UUID):
        """Застосування retention policy"""
        # Видалення за TTL або confidence
        pass
```

---

## 📊 Приклади правил

### Правило 1: Автоматичне підтвердження високої confidence

```json
{
  "category": "preference",
  "condition": {
    "confidence": {"gte": 0.8},
    "is_sensitive": false
  },
  "action": "auto_confirm"
}
```

### Правило 2: Вимагати підтвердження для чутливих даних

```json
{
  "category": "*",
  "condition": {
    "is_sensitive": true
  },
  "action": "require_user_approval"
}
```

### Правило 3: Автоматичне видалення низької confidence

```json
{
  "category": "*",
  "condition": {
    "confidence": {"lt": 0.3},
    "last_confirmed_at": {"lt": "now() - 30 days"}
  },
  "action": "auto_delete"
}
```

---

*Документ створено: 2026-01-10 19:30 CET*