# Модель памяти

Модель памяти Synapse разработана для LLM-агентов — достаточно структурирована
для надёжного отзыва, достаточно гибка для любой предметной области.

## Анатомия воспоминания

```json
{
  "id": "mem_abc123",
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed on vps1. CI green.",
  "tags": ["synapse", "deployment", "v1.5.0"],
  "priority": "high",
  "source": "agent",
  "verified": false,
  "confidence": 0.85,
  "expires_at": null,
  "mind_id": "m_xyz789",
  "created_at": "2026-06-27T...",
  "updated_at": "2026-06-27T..."
}
```

## Поля

| Поле | Тип | Обязательное | Описание |
|-------|------|----------|-------------|
| `id` | string | авто | Уникальный ID (mem_xxx) |
| `category` | enum | ✅ | Одна из 8 категорий |
| `key` | string | ✅ | Стабильный идентификатор (используется для обновлений) |
| `content` | string | ✅ | Содержимое памяти (любой текст) |
| `tags` | string[] | – | Для поиска и фильтрации |
| `priority` | enum | – | low, normal, high, critical (по умолчанию: normal) |
| `source` | enum | авто | user, agent (кто сохранил) |
| `verified` | bool | авто | Проверил ли человек? |
| `confidence` | float | – | 0.0 до 1.0 (по умолчанию: 1.0 для user, 0.7 для agent) |
| `expires_at` | timestamp | – | Когда забыть это воспоминание |
| `mind_id` | string | авто | Какому mind принадлежит |
| `created_at` | timestamp | авто | Первый раз сохранено |
| `updated_at` | timestamp | авто | Последнее изменение |

## Категории

Восемь категорий покрывают типичные сценарии LLM-агентов:

| Категория | Назначение | Пример содержимого |
|----------|---------|-----------------|
| `identity` | Кто пользователь | «User is Michael Schäfer, software engineer in Berlin» |
| `preference` | Предпочтения пользователя | «Prefers concise technical responses» |
| `fact` | Проверяемые факты | «Office is in Berlin, timezone Europe/Berlin» |
| `project` | Статус проекта | «Synapse v1.5.0 deployed, working on v1.6.0 docs» |
| `skill` | Навыки пользователя | «Advanced Python, 10+ years» |
| `mistake` | Прошлые ошибки | «Forgot to bump npm version — CI failed» |
| `context` | Контекст сессии | «Currently reviewing PR #42» |
| `note` | Прочие заметки | «Try Redis for caching next sprint» |

## Ключи: стабильные идентификаторы

Поле `key` критически важно — с его помощью вы обновляете воспоминания,
не создавая дубликатов.

```python
# First store
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Update with same key (overwrites, doesn't duplicate)
store("project", "project_synapse_status", "v1.5.0 deployed", priority="high")
```

**Правила ключей:**

- Должен быть уникален в рамках (category, mind)
- Используйте `snake_case`
- Добавляйте префикс категории для ясности: `preference_communication`, `mistake_npm_version`
- Сохраняйте стабильность — не меняйте ключи после создания

## Теги: для поиска

Теги обеспечивают быструю фильтрацию и поиск:

```bash
# Find all memories with tag "docker"
GET /memory/by-tag?tag=docker

# FTS5 search within tagged subset
GET /memory/search?q=swarm&tag=docker
```

**Лучшие практики тегов:**

- 2–5 тегов на воспоминание (не перегружайте)
- Нижний регистр для единообразия
- Используйте названия проектов, темы, технологии
- Теги нечувствительны к регистру

## Уровни приоритета

| Приоритет | Когда использовать | Поведение при отзыве |
|----------|-------------|-----------------|
| `critical` | Идентичность, юридическое, необратимое | Всегда наверху отзыва |
| `high` | Активные проекты, ключевые предпочтения | Заметно в отзыве |
| `normal` | Большинство воспоминаний (по умолчанию) | Стандартный порядок отзыва |
| `low` | Эфемерное, желательно знать | Может быть суммаризировано |

`/memory/recall` сортирует по приоритету (сначала critical), затем по свежести.

## Источник: user против agent

У воспоминаний есть тег `source`:

- `user` — сохранено человеком (через JWT или человеко-ориентированный UI)
- `agent` — сохранено LLM-агентом (через Mind Key)

Это влияет на:

- **Верификацию:** воспоминания `user` авто-верифицируются, `agent` — нет
- **Уверенность:** для `user` по умолчанию 1.0, для `agent` — 0.7
- **Отзыв:** `/memory/recall` помечает неверифицированные воспоминания как «(unverified)»

> [!NOTE]
> Относитесь к воспоминаниям с источником `agent` с должным скепсисом. Они могут
> быть выведены или предполагаться, а не прямо заявлены пользователем.

## Верификация

Флаг `verified` указывает, что человек подтвердил воспоминание:

- Воспоминания `user`: авто-верифицированы (`true`)
- Воспоминания `agent`: по умолчанию неверифицированы (`false`)

Верификация через:

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"
```

> [!NOTE]
> Верификация требует JWT (человеческая аутентификация), а не Mind Key
> (агентская аутентификация). Это гарантирует, что только люди могут
> помечать воспоминания как верифицированные.

## Уверенность

Поле `confidence` (от 0.0 до 1.0) указывает, насколько надёжно воспоминание:

- 1.0 — прямо заявлено пользователем
- 0.7 — выведено агентом
- 0.5 — неопределённое, требует проверки
- 0.0 — явно сомнительное

Устанавливайте confidence при сохранении:

```json
{
  "category": "preference",
  "key": "prefers_dark_mode",
  "content": "User seems to prefer dark mode (based on their IDE screenshots)",
  "confidence": 0.5,
  "source": "agent"
}
```

## Истечение срока

Устанавливайте `expires_at` для чувствительных ко времени воспоминаний:

```json
{
  "category": "context",
  "key": "current_meeting_topic",
  "content": "Discussing Q3 roadmap",
  "expires_at": "2026-06-28T00:00:00Z"
}
```

Истёкшие воспоминания не возвращаются `/memory/recall` (но остаются в БД).
Используйте `/memory/expiring?within=7d`, чтобы увидеть воспоминания, истекающие скоро.

## Жизненный цикл памяти

```
                  ┌─────────────────┐
                  │     Create      │
                  │  POST /memory   │
                  └────────┬────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │     Active      │ ◀──── PUT /memory/:id (update)
                  │  (in recall)    │
                  └────────┬────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Expired  │ │ Verified │ │ Deleted  │
        │ (in DB)  │ │ (flag)   │ │ (gone)   │
        └──────────┘ └──────────┘ └──────────┘
```

## Поведение отзыва

`GET /memory/recall` возвращает простое текстовое резюме, оптимизированное
для контекста LLM:

```
Mind: Michael's Mind
Memories: 12 total (10 verified, 2 unverified)

[001] identity (CRITICAL) [verified]
  user_name
  Michael Schäfer
  Tags: person, identity

[002] preference (HIGH) [verified]
  communication_style
  Prefers concise technical responses
  Tags: communication

[003] project (HIGH) [unverified]
  synapse_status
  v1.5.0 deployed, working on v1.6.0 docs
  Tags: synapse, deployment

...
```

- Сортировка по приоритету (critical → low), затем по свежести
- Неверифицированные воспоминания помечены `[unverified]`
- Теги включены для контекста
- Простой текст (разбор JSON не требуется)

## Следующие шаги

- [Memory API](/docs/api/memory)
- [Лучшие практики работы с памятью](/docs/guides/memory-best-practices)
- [FTS5-поиск](/docs/concepts/fts5-search)