# Модель пам'яті Модель пам'яті 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 # Перше збереження store("project", "project_synapse_status", "v1.4.0 deployed", priority="high") # Оновлення з тим самим ключем (перезаписує, не дублює) store("project", "project_synapse_status", "v1.5.0 deployed", priority="high") ``` **Правила ключів:** - Має бути унікальним у межах (category, mind) - Використовуйте `snake_case` - Префіксуйте категорією для ясності: `preference_communication`, `mistake_npm_version` - Тримайте стабільними — не змінюйте ключі після створення ## Теги: для пошуку Теги забезпечують швидку фільтрацію та пошук: ```bash # Знайти всі спогади з тегом "docker" GET /memory/by-tag?tag=docker # Пошук FTS5 у межах підмножини з тегом GET /memory/search?q=swarm&tag=docker ``` **Найкращі практики тегів:** - 2-5 тегів на спогад (не перетегуйте) - Нижній регістр для узгодженості - Використовуйте назви проєктів, тем, технологій - Теги нечутливі до регістру ## Рівні пріоритету | Пріоритет | Коли використовувати | Поведінка відкликання | |----------|-------------|-----------------| | `critical` | Ідентичність, юридична інформація, незворотне | Завжди на початку відкликання | | `high` | Активні проєкти, ключові уподобання | Помітне у відкликанні | | `normal` | Більшість спогадів (за замовчуванням) | Стандартний порядок відкликання | | `low` | Ефемерне, корисно знати | Може бути сумаризовано | `/memory/recall` сортує за пріоритетом (critical першими), потім за новизною. ## Джерело: користувач проти агента Спогади позначаються `source`: - `user` — збережено людиною (через JWT або людський інтерфейс) - `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 — прямо сумнівно Встановлюйте впевненість при збереженні: ```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)