# Лучшие практики работы с памятью

То, как вы структурируете воспоминания, определяет их полезность. Это руководство
описывает паттерны категоризации, тегирования и приоритизации, чтобы 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
# Initial store
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Later: update with same key
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
# Find memories not updated in 90 days
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):
        # Either delete or lower priority
        if is_obsolete(mem):
            delete_memory(mem["id"])
        else:
            update_memory(mem["id"], priority="low")
```

## Паттерн: наследование памяти

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

```python
# Parent project
store("project", "project_synapse", "Main Synapse project", 
      tags=["synapse", "parent"], priority="high")

# Sub-project (tags link to parent)
store("project", "project_synapse_docs", "Docs system for Synapse",
      tags=["synapse", "docs", "synapse-parent"], priority="high")

# Specific task (tags link to sub-project)
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)