> ## 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.

# Долговременная память Велеса

> Техническое руководство по механизмам памяти, архивации сессий и восстановлению контекста в Велесе.

# Долговременная память Велеса: технический справочник

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

***

## Архитектура памяти

Память Велеса разделена на шесть функциональных слоёв:

### 1. Профиль пользователя (`USER.md`)

Это устойчивые сведения о пользователе: язык, часовой пояс, предпочтения, рабочая роль и другие данные, полезные во всех диалогах. Файл общий для всех личностей; его активная копия добавляется в системный контекст при каждом запросе после проектных инструкций, но перед долгосрочной памятью. Размер активной копии — не более `contextWindowTokens / 4` символов и не более 16 000 символов. Если файл длиннее, Велес добавляет отметку о сокращении; сам `USER.md` не меняется. Библиотека памяти Nerve не обрезает содержимое: до общего предела текстового файла около 1 МиБ она показывает его целиком, а превышение размера отмечает отдельным состоянием. Ошибка чтения или декодирования исключает профиль только из текущего системного контекста и записывается в журнал. Профиль не отменяет системные правила, `SOUL.md`, `AGENTS.md` и `TOOLS.md`.

### 2. Курируемая память (`memory/MEMORY.md`)

Это «золотой фонд» знаний о пользователе, проектах и принятых решениях. Данные здесь структурированы и подаются в системный контекст при каждом запросе.

* **Инструмент**: `save_memory` (вызывается Велесом для обновления фактов).
* **Путь**: `memory/MEMORY.md`.

### 3. Резюме текущих диалогов (`memory/conversations/*.md`)

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

### 4. Дневные записи (`memory/YYYY-MM-DD.md`)

Используются для «экстренного сброса» памяти при переполнении контекстного окна. Если диалог становится слишком длинным, Велес выписывает в этот файл ключевые тезисы перед тем, как старые сообщения будут удалены из активной памяти.

* **Срабатывание**: автоматическое, при достижении порога токенов.

> **Примечание.** Когда включено [сжатие контекста](/dive-deeper/context_compression_ru)
> (по умолчанию), активное окно беседы удерживает структурированное резюме, а
> свёрнутые ходы дополнительно выгружаются в долговременную память. Прежняя
> посегментная выгрузка в дневные логи остаётся запасным механизмом на случай,
> когда сжатие выключено.

### 5. Резюме завершённых сессий (`memory/YYYY-MM-DD-HHMM-slug.md`)

Каждый раз, когда вы начинаете новую сессию (команда `/new`), Велес создает краткий, структурированный отчет о завершенном разговоре.

* **ID сессии**: записывается в файл для связи с полной стенограммой.
* **Поиск**: эти файлы индексируются для семантического поиска инструментом `memory_search`.

### 6. Архив стенограмм (`sessions/archive/*.jsonl`)

Это «черный ящик», где хранятся дословные записи всех прошлых разговоров в формате JSONL.

* **Индекс**: файл `sessions/_sessions.jsonl` связывает темы (slug), ID сессий и пути к файлам.
* **Инструменты**: `session_list` (поиск сессии) и `session_history` (чтение стенограммы).

***

```mermaid theme={null}
graph TD
    A[Новое сообщение] --> B{Контекст переполнен?}
    B -- Нет --> C[Активная сессия]
    B -- Да --> D[Сброс старого контекста]
    D --> E[Запись в дневной лог memory/YYYY-MM-DD.md]
    D --> C
    
    C --> F{Команда /new?}
    F -- Да --> G[Архивация сессии]
    G --> H[Создание резюме memory/YYYY-MM-DD-HHMM-slug.md]
    G --> I[Стенограмма сессии sessions/archive]
    G --> J[Индекс _sessions.jsonl]
    
    K[Профиль USER.md] --> M[Системный контекст]
    L[Курируемая память memory/MEMORY.md] --> M
    C --> N[Резюме memory/conversations]
```

## Как Велес восстанавливает прошлый контекст

Существует три режима восстановления информации:

### 1. Мгновенный (из `USER.md` и `memory/MEMORY.md`)

Велес сразу получает безопасно ограниченную активную копию профиля пользователя и курируемую память. Этот режим применяется для постоянных предпочтений, важных фактов, технического набора и правил работы. Полный `USER.md` остаётся доступен в библиотеке памяти Nerve даже тогда, когда в запрос попала только его начальная часть.

### 2. По смыслу (`memory_search`)

Агент ищет информацию во всех вложенных файлах памяти (`memory/**/*.md`). Это полезно для вопросов типа: «О чем мы договорились на прошлой неделе касательно интеграции с Redis?». Поиск работает по смыслу, а не только по ключевым словам.

Ключевой поиск устойчив к кавычкам внутри запроса. Если пользователь или модель ищет фразу с кавычками, Велес экранирует её для внутреннего индекса и не превращает это в пустой результат.

### 3. Точное восстановление истории

Если Велесу нужен дословный текст сообщения или точный вывод команды из прошлого, он использует связку:

1. `session_list` — находит нужный `session_id` в списке завершенных бесед.
2. `session_history` — загружает полную стенограмму по этому ID.

***

## Жизненный цикл сессии

1. **Активная фаза**: сообщения записываются в текущую сессию, а безопасно ограниченная копия `USER.md` и содержимое `memory/MEMORY.md` добавляются к каждому запросу.
2. **Резюме диалога**: для обычного диалога поддерживается файл в `memory/conversations/`.
3. **Сброс**: при нехватке места важные детали выписываются в дневную запись.
4. **Консолидация**: Велес периодически обновляет `memory/MEMORY.md`, добавляя туда новые устойчивые знания.
5. **Завершение (`/new`)**:
   * Рабочее окно очищается.
   * Создается резюме сессии (`memory/YYYY-MM-DD-...md`).
   * Стенограмма сохраняется в архив (`sessions/archive/...jsonl`).
   * Запись добавляется в индекс `_sessions.jsonl`.

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

***

## Как помочь Велес помнить лучше

* **Будьте явными**: фразы «запомни, что я предпочитаю...» или «это наше новое правило архитектуры» значительно повышают вероятность попадания факта в долгосрочную память.
* **Актуализируйте**: если правило изменилось, скажите об этом: «Мы больше не используем библиотеку X, теперь работаем через Y».
* **Используйте `/new`**: завершение логических блоков работы командой `/new` помогает Велесу структурировать свои отчеты и делает поиск по архиву более точным.

***

## Итог

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