# Найкращі практики роботи з пам'яттю

Те, як ви структуруєте спогади, визначає їхню корисність. Цей посібник охоплює
шаблони категоризації, тегування та пріоритизації спогадів, щоб LLM міг
відкликати правильну інформацію в потрібний момент.

## Категорії: обирайте найбільш конкретну

| Категорія | Для чого | Приклад |
|----------|---------|---------|
| `identity` | Ім'я, роль, контактна інформація | `"user_name": "Michael Schäfer"` |
| `preference` | Подобання, антипатії, стиль роботи | `"communication": "Prefers concise responses"` |
| `fact` | Перевірювані факти | `"office_location": "Berlin, Germany"` |
| `project` | Статус проєкту, рішення | `"project_synapse": "v1.5.0 deployed"` |
| `skill` | Навички користувача | `"skill_python": "Advanced, 10+ years"` |
| `mistake` | Минулі помилки для уникнення | `"mistake_npm_version": "Always bump version"` |
| `context` | Контекст, релевантний сесії | `"current_focus": "Working on docs system"` |
| `note` | Різні нотатки | `"note_idea": "Try Redis for caching"` |

> [!TIP]
> У разі сумніву використовуйте `fact` для перевірюваної інформації та `note`
> для всього іншого. Не надмірно категоризуйте — краще мати чіткий `fact`, ніж
> заплутаний `context`.

## Ключі: змістовні ідентифікатори

Поле `key` — це ідентифікатор спогаду. Використовуйте змістовні, стабільні ключі:

**Хороші ключі:**
- `user_name`
- `project_synapse_status`
- `preference_communication_style`
- `mistake_npm_version_bump`

**Погані ключі:**
- `mem_001` (не змістовний)
- `temp` (не описовий)
- `2026-06-27-note` (дата не допомагає відкликанню)

### Угоди іменування ключів

- `snake_case` (нижній регістр із підкресленнями)
- Префіксуйте категорією: `preference_*`, `project_*`, `mistake_*`
- Використовуйте описові іменники, а не дієслова
- До 50 символів

## Теги: для пошуку та фільтрації

Теги забезпечують швидку фільтрацію та пошук. Додавайте 2-5 тегів на спогад:

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system.",
  "tags": ["synapse", "deployment", "status", "v1.5.0"]
}
```

### Шаблони тегів

- **Назви проєктів**: `synapse`, `synapse-mcp`, `synapse-chat`
- **Тем**: `deployment`, `ci`, `database`, `auth`
- **Статусу**: `active`, `completed`, `blocked`
- **Індикатори пріоритету**: `urgent`, `long-term`

> [!NOTE]
> Теги нечутливі до регістру. Використовуйте нижній регістр для узгодженості.

## Пріоритети: будьте реалістичними

| Пріоритет | Для чого | % спогадів |
|----------|---------|---------------|
| `critical` | Ідентичність користувача, юридична інформація, незворотні рішення | ~5% |
| `high` | Активні проєкти, важливі уподобання | ~20% |
| `normal` | Більшість фактів, нотаток, контексту | ~65% |
| `low` | Ефемерне, корисно знати | ~10% |

> [!WARNING]
> Не позначайте все `critical`. Якщо все критичне, то нічого не критичне.
> Залишайте `critical` для речей, що спричинять реальну шкоду при забуванні.

## Коли зберігати, а коли ні

### Завжди зберігайте

- Ідентичність користувача (ім'я, email, роль)
- Довготривалі уподобання
- Рішення про проєкт та їх обґрунтування
- Минулі помилки та отримані уроки
- Зобов'язання перед користувачем

### Не зберігайте

- Перехідний стан (використовуйте змінні)
- Історію розмов дослівно (це обробляє система чату)
- Чутливі дані (паролі, API-ключі)
- Факти, що легко вивести (поточна дата, вміст файлів)
- Ефемерний контекст (використовуйте категорію `context` із низьким пріоритетом)

## Оновлення спогадів

POST `/memory` з тією ж `category` + `key` оновлює наявний спогад:

```python
# Початкове збереження
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Пізніше: оновлення з тим самим ключем
store("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")
```

> [!TIP]
> Використовуйте стабільні ключі, щоб оновлювати без створення дублікатів. LLM
> має повторно POST-нути той самий ключ при зміні інформації, а не створювати
> нові спогади.

## Життєвий цикл спогаду

```
Create → Active → Stale → Archive → Delete
```

- **Create**: POST /memory з повним контекстом
- **Active**: Часто відкликати, оновлювати за потреби
- **Stale**: Ще релевантні, але не активно використовуються (знизити пріоритет?)
- **Archive**: Встановити пріоритет `low`, зберігати для історичного довідника
- **Delete**: DELETE /memory/:id, коли більше не релевантний

### Періодичне очищення

```python
# Знайти спогади, що не оновлювалися 90 днів
old_memories = requests.get(
    f"{URL}/memory/search?q=*",
    headers={"Authorization": f"Bearer {KEY}"}
)

for mem in old_memories["results"]:
    if is_stale(mem, days=90):
        # Або видалити, або знизити пріоритет
        if is_obsolete(mem):
            delete_memory(mem["id"])
        else:
            update_memory(mem["id"], priority="low")
```

## Шаблон: успадкування спогадів

Для ієрархічного контексту (проєкт → підпроєкт → завдання):

```python
# Батьківський проєкт
store("project", "project_synapse", "Main Synapse project", 
      tags=["synapse", "parent"], priority="high")

# Підпроєкт (теги пов'язують з батьком)
store("project", "project_synapse_docs", "Docs system for Synapse",
      tags=["synapse", "docs", "synapse-parent"], priority="high")

# Конкретне завдання (теги пов'язують з підпроєктом)
store("project", "task_docs_loader", "Implement docs-loader.ts",
      tags=["synapse", "docs", "task"], priority="normal")
```

Потім LLM може шукати `q=synapse+docs`, щоб знайти всі пов'язані спогади.

## Шаблон: журнал рішень

Зберігайте рішення з обґрунтуванням, щоб LLM не переробляв їх:

```python
store("fact", "decision_postgres_over_sqlite",
      "Chose PostgreSQL over SQLite for production. Reason: concurrent writes, "
      "FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.",
      tags=["decision", "database", "postgres", "sqlite"],
      priority="high")
```

## Шаблон: уникнення помилок

Зберігайте помилки зі специфічними інструкціями уникнення:

```python
store("mistake", "mistake_forget_version_bump",
      "Forgot to bump package.json version after changes. npm publish failed. "
      "FIX: Always run `npm version patch` before pushing. "
      "CI fails with 'version already exists' if you forget.",
      tags=["npm", "ci", "publish", "version"],
      priority="high")
```

## Антишаблони для уникнення

> [!WARNING]
> - **Зберігання логів розмов** — це обробляє система чату
> - **Зберігання цілих файлів** — використовуйте сховище скриптів або зовнішнє сховище
> - **Зберігання ефемерного стану** — використовуйте змінні
> - **Зберігання секретів** — використовуйте змінні середовища
> - **Дублювання спогадів** — використовуйте стабільні ключі
> - **Надмірне тегування** — 2-5 тегів на спогад ідеально
> - **Усе критичне** — будьте реалістичними з пріоритетами

## Наступні кроки

- [Memory API](/docs/api/memory)
- [Постійний LLM-агент](/docs/guides/persistent-llm-agent)
- [Стратегія тегування пам'яті](/docs/llm-cookbook/memory-tagging-strategy)