Память агентов¶

Память — это то, что Synth помнит между сессиями: устойчивые факты о проекте и семантический поиск по вашим документам. В начале хода агент получает релевантные фрагменты сам, без явного «вспомни», а найденное всегда сопровождается ссылкой на источник.

Как это устроено

Память — расширение (плагин) платформы: логика поиска, чанков и эмбеддингов живёт в расширении, а данные и портал — в ядре. Пока исполнение кода расширений выключено, портал памяти показывает «память недоступна». Включение — в разделе Плагины.

Что даёт память¶

Возможность	Что видит агент
Факты проекта	Устойчивые утверждения с источником: «деплой в test идёт через Fleet (источник: сессия от 12.10)»
Воспоминание по вопросу хода	Несколько фрагментов корпуса, релевантных текущему вопросу, с путём к файлу
Инструменты агента	Поиск по памяти, явная запись факта, отзыв или замена факта

Индексы: проект или инстанс¶

Индекс — это поисковый корпус: либо файлы рабочего каталога, либо факты памяти. У каждого индекса есть область — кому он виден.

Область	Кто видит	Когда применять
Проект (по умолчанию)	только участники этого проекта	рабочие документы и код проекта
Инстанс	все пользователи инстанса, во всех сессиях	общая документация, регламенты, база знаний

Для индекса по файлам в области «Инстанс» проект указывается как проект-источник — чей рабочий каталог сканировать. Сам индекс при этом остаётся общим.

Инстансный индекс виден всем

Всё, что попало в такой индекс, доступно любому пользователю инстанса. Для рабочих файлов проекта используйте область «Проект»; инстансный индекс заводите только для корпуса, который не содержит чувствительного текста. Инстансные индексы создаёт администратор — через портал.

Как создать индекс¶

В веб-интерфейсе: Настройки → Администрирование → «Память» → форма «Создать индекс»:

Поле	Назначение
Имя	Имя индекса (например, `docs`)
Область	«Проект» или «Инстанс»
Источник	`файлы` (рабочий каталог) или `факты` (память)
Проект	Для области «Проект» — владелец индекса; для «Инстанс» + `файлы` — проект-источник корпуса
Фильтр	Glob по именам файлов (необязательно) — сужает корпус

Индекс строится в фоне: пока он собирается, статус — «строится», а когда готов — «готов». Индекс, построенный на устаревшей модели эмбеддингов, помечается как устаревший — его нужно пересобрать.

Модели эмбеддингов¶

Поиск по корпусу работает через эмбеддинги — числовые векторы текста. Провайдера и модель задаёт администратор в конфигурации инстанса:

plugins:
  embeddingProvider: ollama
  embeddingModel: nomic-embed-text:latest

Проверенные модели (локальный Ollama):

Модель	Размерность	Задержка	Объём	Рекомендация
`nomic-embed-text:latest`	768	~0.1–2 с	274 МБ	По умолчанию — быстро и компактно
`nomic-embed-text-v2-moe:latest`	768	~6 с (cold)	958 МБ	Если нужно качество при той же размерности векторов
`qwen3-embedding:latest`	4096	17–21 с	4.7 ГБ	Только осознанно: объём векторов в 5+ раз больше, заметная нагрузка на хост

Меняете модель — пересоберите индексы

Модель входит в отпечаток индекса, поэтому после смены модели старые индексы помечаются как устаревшие и не используются для поиска. Пересоберите их (в админке или командой synth memory rebuild).

Секреты и исходящие запросы¶

При индексации нет обфускации

Текст, попавший в индекс, уходит провайдеру эмбеддингов как есть — платформа не маскирует его перед отправкой. Найденные фрагменты затем попадают в запрос к модели. Поэтому индексируйте только те каталоги, где нет чувствительного текста, и держите секреты вне рабочего каталога.

Что в индекс не попадает никогда — исключения встроены и не отключаются:

каталоги .ssh, .gnupg, .aws, .kube, .docker, .terraform, .gcloud, secrets;
файлы .env*, credentials*.json, secret(s).json|yaml|yml, service-account*.json, id_rsa|ed25519|ecdsa|dsa*, *.pem, *.key, *.p12, *.pfx, *.jks, *.keystore, *.ppk, *.kdbx, *.tfstate*.

Исключения ловят файлы по имени — секрет в нестандартном файле (например, в docker-compose.yml или в config.yaml) они не поймают.

Практические правила:

Эмбеддинги — локальные. Локальный Ollama не отправляет корпус наружу; внешний провайдер получает его целиком.
Сужайте корпус. Фильтр по имени файла в форме индекса — самый простой способ не проиндексировать лишнее.
Инстансный индекс — только для общего. Рабочие файлы проекта остаются в проектной области.
Секреты — вне рабочего каталога. Храните их в каталоге секретов инстанса, а не в файлах проекта.

Вкладка «Память» в правой панели¶

Откройте правую панель → Память. Вкладка показывает только агрегаты (без текстов фактов и фрагментов):

В контексте последнего хода — блоки facts и recall: статус (loaded/truncated/empty), размер в символах и оценку токенов. Если блока нет, вкладка объясняет почему (например, recall не срабатывал — не было вопроса хода).
Скоуп — сколько активных фактов видит сессия и какие индексы доступны: всего, проектные/инстансные, готовые, собирающиеся, с ошибкой.
Статус — готовность памяти (ready/degraded/unavailable) и активность плагина.
Управление — тумблер «Память для проекта» (владелец/редактор проекта): выключение убирает блоки памяти из промпта и тулы памяти у проекта, но не удаляет факты и индексы; включение возвращает. Для сессии без проекта настройки нет.
Индексы — ADMIN может создать индекс (файлы проекта или факты; проектный или общий), пересобрать его и включить/выключить проектный индекс. Выключенный индекс остаётся в списке, но не используется в recall/search. Общий индекс не отключается — это ресурс всего инстанса (замок и подпись в списке).
Автоматизация (ADMIN, только при проекте) — три действия: извлечь факты из текущей сессии, слить дубли фактов, переиндексировать проект. Для каждого видно, доступен ли системный шаблон, подготовлен ли пайплайн проекта и когда был последний прогон. Кнопки: «Подготовить пайплайн», «Запустить сейчас», «Расписание» (открывает шедулер с заполненной формой).

Данные — из GET /api/v2/sessions/:id/memory; доступ проверяется по правам на сессию. Метрики (synth_memory_*) и Grafana-дашборд «Synth — Память» — для администратора инстанса.

Автоматизация: задания и расписания¶

Автоматического расписания «из коробки» нет, но вкладка «Память» готовит всё за пару кликов.

Системные шаблоны (не пайплайны проекта, а заготовки):

Шаблон	Что делает	Расписание
`builtin:memory-consolidation`	извлекает устойчивые утверждения из сессии и пишет факты	обычно только разово
`builtin:memory-consolidate-facts`	сливает дубли фактов проекта	да
`builtin:memory-reindex`	пересобирает все проектные индексы	да

«Подготовить пайплайн» создаёт в проекте копию шаблона (идемпотентно) и публикует её. После этого «Запустить сейчас» делает разовый прогон, а «Расписание» открывает «Шедулер» с уже заполненными проектом, пайплайном и payload. Общие (instance) индексы переиндексируются только через портал (ADMIN), не проектным пайплайном.

Где смотреть:

Правая панель → «Шедулер» — расписания, создание/редактирование, история запусков.
Левая панель → «Пайплайны» — пайплайны проекта, публикация и прогоны.
Настройки → Администрирование → «Аддоны» → «Пайплайны» → «Шаблоны» — системные шаблоны памяти. Вкладки «Определения»/«Экземпляры» — другой, legacy-контур.

Подробности формата пайплайнов — в разделе «Пайплайны (preview)».

CLI: `synth memory`¶

Команда synth memory — тонкий клиент HTTP API портала памяти: она не выполняет поиск сама, а обращается к работающему инстансу. Поэтому нужен запущенный инстанс и ключ доступа.

synth memory status                                  # готовность, провайдер, счётчики
synth memory list --project prj_42                   # список индексов
synth memory list --scope instance                   # только инстансные индексы

# Проектный индекс по документам проекта
synth memory index prj_42 --name docs --source files --filter '**/*.md' --wait

# Общий индекс инстанса по фактам памяти (проект не нужен)
synth memory index --scope instance --source facts --name facts --wait

synth memory rebuild idx_7f3a --wait                 # пересобрать (после смены модели)
synth memory drop idx_7f3a --yes                     # удалить

Подкоманда	Что делает
`status`	Готовность портала, провайдер, число фактов и индексов
`list`	Список индексов (фильтры: `--project`, `--state`, `--scope`)
`index`	Создать индекс (`--name`, `--source`, `--scope`, `--filter`)
`rebuild`	Пересобрать индекс по id
`drop`	Удалить индекс по id (нужен `--yes`)

Общие флаги: --url, --token, --data-dir, --json. Команды index и rebuild отвечают сразу, а сборка идёт в фоне — с --wait команда дожидается готовности индекса.

HTTP API¶

Портал памяти доступен и напрямую:

Метод	Путь	Назначение
`GET`	`/api/v2/memory/status`	Готовность и счётчики
`GET`	`/api/v2/memory/facts`	Факты (фильтры, постранично)
`GET`	`/api/v2/memory/indexes`	Индексы (фильтр области — `scope`, значения `project` или `instance`)
`POST`	`/api/v2/memory/indexes`	Создать индекс (тело: `scope`, `source`, `projectId`)
`POST`	`/api/v2/memory/indexes/:id/rebuild`	Пересобрать индекс
`DELETE`	`/api/v2/memory/indexes/:id`	Удалить индекс

Права: чтение и мутации индекса — администратору; для проектных индексов дополнительно действуют права проекта.

Что дальше¶

Плагины — как включить расширение памяти.
Конфигурация — настройки инстанса целиком.
CLI — остальные команды терминала.