> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velesagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Личности

> Как в Veles работают личности: SOUL.md, AGENTS.md, сессии и Nerve.

# Личности

**Личность** (Personality) - это выбранный образ и системная роль Велеса. Она отвечает на вопрос: "Кто сейчас говорит и как он должен мыслить?"

Личности нужны, когда в одном рабочем пространстве хочется иметь несколько устойчивых стилей работы: например, аккуратного ревьюера, исследователя, архитектора или краткого оператора.

<Note>
  **Если вы просто пользуетесь Велесом:** достаточно знать, что личность — это «специалист», которого вы выбираете при создании нового диалога (кнопка **Новый**), а создаёте и редактируете в разделе **Личности**. Остальное на этой странице — для тех, кто настраивает Велес и хочет понять, как это устроено внутри.
</Note>

## Где хранятся личности

Личности хранятся прямо в рабочей области: prompt остаётся в Markdown, а небольшие служебные данные - в JSON.

Основная личность `main` использует файлы в корне workspace:

```text theme={null}
SOUL.md
personality.json
```

Дополнительные личности живут в папке `personalities/<id>/`:

```text theme={null}
personalities/
  reviewer/
    SOUL.md
    personality.json
    skills/
      review/
        SKILL.md
```

`SOUL.md` содержит сам prompt личности: тон, характер, стиль мышления, рабочие привычки и ограничения.

`personality.json` хранит служебные метаданные личности: имя, модель по умолчанию, уровень thinking/reasoning и даты. Он не попадает в system prompt.

## SOUL.md и AGENTS.md

`SOUL.md` и `AGENTS.md` решают разные задачи.

`SOUL.md` - это идентичность активной личности. Он попадает в system prompt как слой "кто я".

`AGENTS.md` - это общие инструкции проекта и workspace. Он остается общим для всех личностей и попадает в system prompt как проектный контекст.

Например:

* `SOUL.md`: "Ты строгий ревьюер, сначала ищешь риски и регрессии."
* `AGENTS.md`: "В этом репозитории не запускай тесты сам, попроси пользователя."

## Навыки личности

У дополнительной личности может быть свой каталог навыков:

```text theme={null}
personalities/<id>/skills/<имя-навыка>/SKILL.md
```

Эти навыки добавляются в каталог и context только когда отвечает эта личность. Навыки других личностей не попадают в prompt, чтобы не засорять контекст лишними правилами. Если имя навыка совпадает, порядок приоритета такой: навыки активной личности, затем общие `workspace/skills`, затем встроенные `veles/skills`.

## Что не изолируется

В текущей реализации личности не создают отдельные рабочие области.

Общими остаются:

* workspace-файлы;
* память;
* сессии и история;
* cron-задачи;
* логи;
* runtime home.

Это сделано намеренно. Личность сейчас является Markdown-идентичностью с необязательным собственным набором навыков, а не полной изоляцией среды. Если позже потребуется отдельная память или отдельные workspace для разных личностей, это будет отдельный дизайн.

## Сессии

Корневая сессия личности имеет ключ:

```text theme={null}
personality:<id>:main
```

Например:

```text theme={null}
personality:main:main
personality:reviewer:main
```

Служебные дочерние сессии используют тот же id личности:

```text theme={null}
personality:reviewer:subagent:<id>
personality:reviewer:cron:<id>
personality:reviewer:cron:<id>:run:<run-id>
```

Если после миграции уже существует сессия `personality:<id>:...`, но Markdown-файлы личности еще не созданы, Veles автоматически создаст пустую личность в `personalities/<id>/`, чтобы запуск не падал.

## Управление в Nerve

В Nerve личности создаются и редактируются в разделе **Личности**.

При создании можно указать:

* имя;
* soul/personality prompt;
* модель по умолчанию;
* уровень thinking/reasoning.

Изменения сохраняются на стороне Велеса и отражаются в файлах рабочей области. Первый пользовательский текст больше не используется как скрытая начальная инструкция; постоянная инструкция личности хранится только в `SOUL.md`.

Профиль пользователя не принадлежит отдельной личности. Корневой `USER.md` общий для всех личностей, а его безопасно ограниченная копия добавляется в активный контекст каждого обращения после общих проектных инструкций. Библиотека памяти Nerve показывает файл полностью в пределах общего текстового ограничения и явно отмечает его превышение. Поэтому сведения о пользователе достаточно обновить один раз; создавать копии `USER.md` внутри `personalities/<id>/` не нужно.

В коде Nerve для этой сущности тоже используется термин Personality: создание, переключение, workspace-scoping и списки верхнеуровневых сессий не должны называться agents. Термины agent log, agent status, assistant display name и subagent остаются только там, где речь действительно идет о runtime-исполнении или дочерних подагентах.

## Миграция

Старые runtime-ключи `agent:<id>:...` заменены на `personality:<id>:...`.

`veles gateway`, `veles agent` и Railway startup-скрипт запускают эту миграцию автоматически перед стартом. Если миграция уже была выполнена или старых записей нет, она просто завершается успешно и продолжает запуск.

Команду можно запустить вручную для явной проверки:

```bash theme={null}
veles migrate-personalities
```

Она переписывает сохраненные session keys, root-history records, conversation metadata, cron jobs и связанные поля `agentId` в `personalityId`.

После cutover Veles ожидает только новые ключи `personality:*`. Если старые `agent:*` записи всё ещё остались после автоматической миграции, startup останавливается с понятным сообщением, потому что это обычно означает конфликт файлов или повреждённые данные.

## Переименование id личности

Если личность получила неудачный id, например `agent-3`, используйте скрипт:

```bash theme={null}
veles rename-personality agent-3 medical
veles rename-personality agent-3 medical --yes
```

По умолчанию команда использует workspace из конфигурации Veles. Флаг `--workspace` нужен только если требуется явно указать другой workspace. Первый запуск без `--yes` показывает dry-run, а `--yes` применяет изменения.

Перед запуском остановите Veles/Nerve, чтобы они не писали новые session-файлы одновременно со скриптом.

Скрипт переименовывает папку `personalities/<id>/`, обновляет `personality.json`, переписывает ключи вида `personality:<id>:...` в `sessions/`, `memory/`, `cron/` и `tasks/`, а также переименовывает live session JSONL-файлы. После применения запустите Veles/Nerve заново, чтобы сбросить in-memory кеши. Если включена векторная память, после проверки файлов переиндексируйте память.

## Автовыбор личности

Veles может выбрать подходящую личность для нового пользовательского запроса на стороне gateway. Endpoint `GET /api/personalities/select?query=...` и RPC `personalities.select` берут текст запроса, собирают имена, метаданные и `SOUL.md` всех личностей, затем просят модель по умолчанию выбрать лучший вариант.

Ответ возвращает `personalityId`, безопасные метаданные выбранной личности, `reason`, `confidence`, модель, которая сделала выбор, и количество рассмотренных кандидатов. Текст `SOUL.md` используется только внутри выбора и не возвращается в поле `personality`, чтобы Nerve мог начать сессию по `rootSessionKey` без повторной отправки prompt-текста в UI.

Для длинных запросов можно использовать `POST /api/personalities/select` с JSON-телом:

```json theme={null}
{
  "query": "Пользовательский запрос, для которого нужно выбрать личность"
}
```