​

Исследование размера и жизненного цикла vector.db

​

Решение от 25 августа 2026 года

• один файл допускается к индексации только до tools.vectorMemory.maxFileBytes; значение по умолчанию — 8 МиБ;
• memory/*-raw-archive.md сохраняются на диске, но исключены из обнаружения и обоих видов поиска;
• файл разбивается и отправляется поставщику порциями не более 20 фрагментов;
• до первого запроса эмбеддингов все фрагменты подсчитываются во временной базе, проверяются предел в 8192 фрагмента и нижняя оценка текстовой записи; после первого ответа полная оценка с известной размерностью вектора проверяется до упаковки и публикации, а поколение более 64 МиБ отклоняется; за один проход полное чтение, первичное хеширование, переиндексация и постановка исчезнувших путей в очередь выполняются ограниченно, не более чем для 20 файлов каждого вида работы;
• обнаружение путей не создаёт общий список в памяти Python: дерево обходится потоком, полный снимок имён складывается порциями во временную дисковую базу, а между каждыми 100 просмотренными записями управление возвращается шлюзу; сортировка читается из индекса временного снимка, а позиция справедливого продолжения сохраняется в служебных метаданных основного индекса;
• список уже индексированных путей сверяется с тем же временным снимком дисковыми порциями по 100 строк, без отдельного запроса Python для каждого файла; если обход каталога завершился не полностью из-за ошибки чтения, удаление якобы исчезнувших путей на этом проходе не выполняется;
• суммарная расчётная запись поколений за проход не превышает 64 МиБ; обращения к поставщику заранее резервируются для целого файла, а допустимый файл, которому мало обычного бюджета, может превысить его только первым, не делит обращения с другим файлом и всё равно ограничен числом фрагментов;
• каждая порция сразу переводится в двоичный вид и записывается во временную дисковую базу, поэтому список эмбеддингов всего файла больше не удерживается в Python;
• одинаковый текст внутри обработки использует один запрос эмбеддинга, но отдельные пути и диапазоны строк сохраняются как самостоятельные источники;
• полностью подготовленное поколение файла заменяет прежнее одной ограниченной транзакцией; перед публикацией и перед постановкой отклонённого поколения в очередь повторно и с тем же пределом размера проверяются хеш исходника и редакция настроек;
• повторный сбой эмбеддингов для неизменившегося файла не переписывает текст, полнотекстовый индекс и временные метки;
• первый сбой поставщика открывает общий интервал ожидания, поэтому остальные файлы не создают сотни одинаковых неудачных запросов;
• новые и обновлённые строки хранят вектор только в chunks_vec; поле chunks.embedding остаётся для чтения старых баз, но новая JSON-копия туда не записывается;
• размерность сначала восстанавливается из объявления chunks_vec; несовпадение размерности прекращает публикацию и никогда не удаляет действующую таблицу;
• параметры разбиения новых и обновлённых файлов записываются в files.index_signature, поэтому их последующее изменение приводит к пофайловому обновлению; пустая подпись старой схемы остаётся явным признаком наследия и сама по себе не запускает массовую перезапись;
• размер, время изменения и другие признаки исходника сохраняются в files, поэтому неизменившиеся файлы не хешируются заново при каждом минутном проходе;
• исключённый, исчезнувший или явно удаляемый крупный путь сначала удаляется из files и сразу пропадает из поиска, затем cleanup_queue удаляет до 100 фрагментов за транзакцию; новые полнотекстовые строки имеют индексированное соответствие с фрагментом, а старые очищаются справедливо чередуемыми окнами до 100 строк по rowid;
• при постановке старого полнотекстового поколения в очередь фиксируется верхняя граница rowid, поэтому очистка не гонится за новыми строками других файлов; соответствие files.fts_map_complete позволяет современным поколениям вообще не выполнять общий проход;
• режим двоичного, смешанного или старого JSON-хранилища и неизвестность профиля прежней схемы записываются в vector_index_meta до добавления новых столбцов; запуск не соединяет целиком многогигабайтные таблицы ради доказательства полноты двоичных копий, а неизменившиеся поколения с неизвестным профилем сохраняются без повторного полного хеширования;
• компактный счётчик оставшихся JSON-поколений уменьшается в одной транзакции с удалением или заменой их строк в files, в том числе пока доступность двоичного расширения ещё не выяснена; нулевое значение снимает ограничение смысловой индексации без обхода chunks;
• точное удаление и фоновая очистка одинаково обрабатывают исторические пути с / и \;
• соединение ограничивает внутренний кэш, задаёт автоматические контрольные точки и предпочтительный предел журнала 64 МиБ; обычный проход использует неблокирующую контрольную точку, а усечение выполняется при спокойном завершении; занятый читатель откладывает его без изменения данных.

​

Ручное уплотнение от 25 августа 2026 года

• шлюз и все процессы агента для рабочей области должны быть остановлены; межпроцессная блокировка владельца не позволяет уплотнению и индексатору одновременно открыть базу;
• после получения блокировки команда выполняет контрольную точку WAL, чтобы ожидающие записи вошли в стабильный снимок; замена не продолжается с непустым журналом;
• на той же файловой системе создаётся свежая теневая база, в которую попадают только живые файлы и фрагменты;
• достоверные старые JSON-векторы переносятся в двоичное хранилище; исторические нулевые заглушки считаются отсутствующими смысловыми данными, но их фрагменты остаются в полнотекстовом поиске, а недостающие векторы не строятся через поставщика модели;
• полнотекстовый индекс строится заново; целостность, количества строк, размерность и связи проверяются до публикации;
• после проверок теневая база атомарно заменяет активную, а байт-в-байт резервная копия прежней базы с отметкой времени всегда остаётся в memory;
• исходные файлы, записи памяти и настройки не изменяются, внешние вызовы к поставщику модели не выполняются;
• любая ошибка до атомарной замены оставляет прежний vector.db активным.

• код и тесты исследовались в рабочей копии C:\projects\veles;
• числовая диагностика ниже получена другим агентом непосредственно из реальной базы /data/veles/workspace/memory/vector.db;
• результаты осмотра тестовой базы намеренно не используются как доказательство состояния клиентских данных;
• никакие изменения реальной базы в рамках этого исследования не выполнялись.

​

Краткий вывод

• все записи files.path существовали на диске;
• хеши проиндексированных файлов совпадали с текущим содержимым;
• проиндексированных, но больше не обнаруживаемых файлов не было;
• основных фрагментов без родительской записи files в проверенных агрегатах не найдено;
• число свободных страниц SQLite было практически нулевым.

​

Фактическое состояние реальной базы на 10 июля

​

Размеры файлов

​

Страницы SQLite

302 307 × 4 096 = 1 238 249 472 байта
88 × 4 096 = 360 448 свободных байт

​

Сопоставление с файловой системой

STALE_MISSING_FILES = 0
CHANGED_HASH_FILES = 0
UNREADABLE = 0
discoverable_on_disk = 737
indexed_files = 735
indexed_not_discoverable = 0

• docs/Astras/astras_issues_2025.json;
• memory/HISTORY.md.

​

Ограничения диагностики

​

Как данные хранились на 10 июля

1. files — путь, проект, хеш файла, модель и состояние эмбеддингов.
2. chunks — текст каждого фрагмента и JSON-представление эмбеддинга.
3. chunks_fts — полнотекстовое представление текста и внутренние таблицы FTS5.
4. chunks_vec — двоичное представление того же эмбеддинга через sqlite-vec.

• двоичный вектор float32: 1536 × 4 = 6144 байта;
• JSON того же вектора часто занимает около 30 КБ или больше;
• текст хранится как минимум в chunks и FTS5;
• дополнительно присутствуют индексы и служебные страницы SQLite.

​

Что прежний жизненный цикл уже делал правильно

​

Изменение файла

​

Удаление вручную

​

Удаление через RPC рабочей области

​

Скрытие разговора

​

Старые файлы памяти

​

Найденные риски в прежнем коде

​

1. Перезапись при повторной ошибке эмбеддингов

​

2. Гонка удаления с незавершённым индексированием

1. синхронизация прочитала файл;
2. начался сетевой запрос эмбеддингов;
3. в это время RPC удалил файл и очистил индекс;
4. запрос эмбеддингов завершился;
5. старая задача снова вставила уже удалённый файл.

​

3. Удаление векторов зависит от _dims

​

4. Исторические разделители путей

​

5. Скрытые ошибки FTS/vector

​

6. Дубликаты FTS внутри одного прохода

​

7. Опасная смена размерности

​

8. Нет отпечатка алгоритма разбиения

​

9. Физический размер не уменьшается после логического удаления

​

Исторический минимальный план (заменён решением от 25 августа)

​

Восстановление размерности

• Сначала читать float[N] из SQL-объявления chunks_vec в sqlite_master.
• Оставить чтение JSON запасным путём.
• Не прекращать запись JSON-эмбеддингов.
• При несовпадении размерности не удалять chunks_vec; отменять индексирование файла до любых изменений БД и сообщать о необходимости отдельного перестроения.

​

Повторные ошибки эмбеддингов

• Первая ошибка для нового или изменённого файла по-прежнему создаёт актуальный текстовый индекс с embed_ok=0.
• Если хеш и модель уже совпадают и embed_ok=0, следующая неудачная попытка не должна выполнять DELETE, INSERT или менять временные метки.
• Успешная попытка позднее заполняет векторы и устанавливает embed_ok=1.

​

Защита от гонки

• Читать точный снимок содержимого и вычислять его хеш.
• Получать эмбеддинги вне транзакции.
• Непосредственно перед первой операцией SQLite повторно проверить существование и хеш файла.
• Если файл исчез или изменился, отбросить подготовленный результат.
• После проверки выполнять все синхронные изменения без промежуточных await.

​

Транзакции и удаление

• Замену одного файла выполнять в явной транзакции под существующей блокировкой.
• При любой ошибке выполнять откат.
• Проверять существование chunks_vec независимо от _dims.
• Всегда рассматривать варианты пути с / и \.
• При точном удалении очищать все FTS-строки этого пути, включая исторические дубликаты.
• Не скрывать ошибку обязательной очистки, чтобы карантинный механизм смог вернуть файл.
• В пределах одной индексации пропускать уже встреченный chunk_id.

​

Ограничение WAL

PRAGMA journal_mode = WAL;
PRAGMA wal_autocheckpoint = 1000;
PRAGMA journal_size_limit = 67108864;

• проверить размер vector.db-wal;
• если он больше 64 МБ, выполнить лучший возможный PRAGMA wal_checkpoint(TRUNCATE);
• результат BUSY считать безопасной отсрочкой;
• не считать невозможность контрольной точки ошибкой индексации;
• повторить попытку при чистом завершении.

​

Что не меняется

• схема и названия таблиц;
• формат существующих строк;
• JSON в chunks.embedding;
• периодический полный проход;
• поведение ручных изменений файловой системы;
• RPC шлюза;
• область индексируемых файлов;
• правила хранения старых файлов памяти.

​

Ожидаемый результат первого исправления

​

Что уменьшится

​

Что не уменьшится

• почти все его страницы заняты живыми данными;
• JSON-эмбеддинги сохраняются;
• автоматический VACUUM не выполняется.

​

Как изменится будущий рост

• повторные ошибки эмбеддингов перестанут переписывать неизменившийся текстовый индекс;
• FTS перестанет получать одинаковый идентификатор несколько раз за один проход;
• WAL будет иметь ограничение и возможность усечения;
• обычная индексация новых данных продолжит использовать прежний объём на фрагмент.

​

Осознанно отклонённые изменения

​

Периодическая сборка мусора

​

PRAGMA user_version и общая система миграций

​

Автоматический VACUUM и auto_vacuum

​

Ограничение файла в 2 МБ

​

Немедленная интеграция файлового наблюдателя

​

Широкий административный интерфейс

​

Автоматическое удаление JSON-эмбеддингов

​

Исторический проект уменьшения основного файла

​

Возможные стратегии

​

Постепенное уменьшение новых данных

• небольшое изменение кода;
• старый _restore_dims() продолжает находить образец;
• существующая база не переписывается автоматически.

• основной файл сразу не уменьшается;
• контракт «один JSON на файл» надо поддерживать при удалении и переиндексации;
• старые версии снова записывают полный JSON.

​

Полная теневая миграция

1. Остановить синхронизацию и новые записи.
2. Создать согласованную резервную копию средствами SQLite, а не обычным копированием активного WAL-файла.
3. Работать только с теневой копией.
4. Для каждого JSON-эмбеддинга проверить существование соответствующего двоичного вектора.
5. Восстановить отсутствующий chunks_vec из валидного JSON, если размерность совпадает.
6. Обнулить JSON только после подтверждения двоичной копии.
7. Сохранить повреждённые или единственные копии без изменений.
8. Выполнить уплотнение в новый файл через VACUUM INTO.
9. Загрузить sqlite-vec и проверить целостность, количества идентификаторов, размерность, FTS и результаты известных запросов.
10. Закрыть соединения, выполнить контрольную точку и атомарно переключить файлы.
11. Хранить исходную базу без автоматического удаления.

​

Контракт отката после полной миграции

• старый выпуск обязан открывать новую активную базу без дополнительных действий — тогда JSON лучше сохранять;
• откат выполняется восстановлением исходной резервной базы — тогда проверенные JSON-копии можно удалить.

​

Первоначальный список проверок для минимального исправления

1. Первый сбой эмбеддингов создаёт текстовый индекс с embed_ok=0.
2. Второй одинаковый сбой вызывает API, но не меняет строки, временные метки и Connection.total_changes.
3. Следующая успешная попытка добавляет векторы и устанавливает embed_ok=1.
4. Файл удаляется во время приостановленного запроса эмбеддингов и не возвращается в индекс.
5. Файл изменяется во время запроса, и устаревший снимок не фиксируется.
6. Ошибка на каждом этапе замены файла откатывает всю транзакцию.
7. При _dims=None существующие строки chunks_vec всё равно удаляются.
8. Пути с / и \ очищаются одинаково.
9. Повторный chunk_id создаёт только одну FTS-строку.
10. Размерность восстанавливается из sqlite_master, даже когда JSON отсутствует.
11. Несовпадение размерности не удаляет chunks_vec.
12. Контрольная точка WAL не меняет количество files, chunks, FTS и векторов.
13. Активный читатель приводит к безопасному BUSY, а не к ошибке синхронизации.

​

Проверка на копии реальной базы после реализации

• размеры vector.db, WAL и SHM;
• page_count, page_size, freelist_count;
• количества files и chunks;
• количества по проектам;
• список обнаруживаемых, но не проиндексированных файлов;
• PRAGMA integrity_check;
• результаты нескольких известных FTS- и векторных запросов.

• логические количества и результаты поиска не меняются;
• массовой переиндексации 735 существующих файлов нет;
• основной файл остаётся примерно прежнего размера;
• WAL сокращается при отсутствии блокирующих читателей.

​

Полезные указатели в коде

• veles/agent/vector_memory.py
  • _restore_dims() — восстановление размерности и чтение сохранённого режима хранилища без полного обхода фрагментов;
  • _ensure_vector_table() — безопасная проверка размерности без удаления действующей таблицы;
  • _discover_files() — область индексирования;
  • _sync_once_locked() — ограниченный проход, скрытие отсутствующих путей и проверка снимков;
  • _spool_chunks() / _embed_staged_chunks() — предварительный подсчёт и порционная подготовка эмбеддингов;
  • _replace_file_from_stage() — атомарная публикация готового поколения;
  • _clear_file_data() / _drain_cleanup_queue() / delete_file_index() — точная и порционная очистка;
  • sync_loop() — периодический проход.
• veles/api/runtime.py
  • _cleanup_vector_index_for_deleted_file();
  • delete_workspace_path_file() — карантин и восстановление при ошибке.
• veles/agent/loop.py
  • создание, запуск, горячая смена конфигурации и закрытие менеджера.
• veles/config/schema.py
  • VectorMemoryConfig, включая интервал и параметры разбиения.
• tests/test_vector_memory_indexing.py, tests/test_vector_search_tool.py и tests/test_workspace_file_delete.py
  • проверки ограничений, сбоев, старых схем, пустых файлов, разделителей путей и точного удаления.

​

Решения, которые нельзя забыть

• Реальная база сейчас согласована с файловой системой; не называть размер доказательством оставшихся удалённых файлов.
• VACUUM без удаления JSON почти ничего не даст при freelist_count = 88.
• WAL и основной файл — разные проблемы.
• Ручное уплотнение выполняется только через veles vector-memory compact --yes при остановленном Велесе; блокировку владельца нельзя обходить.
• Резервная копия прежней базы всегда сохраняется; не обещать уменьшение общего объёма тома до её ручного перемещения или удаления после проверки.
• Не удалять vector.db ради смены модели или исправления индекса.
• Не удалять chunks_vec при несовпадении размерности.
• Не очищать JSON-эмбеддинги автоматически без отдельного согласия на миграцию и контракт отката.
• Безопаснее временно хранить лишние данные, чем повредить или молча перестроить клиентскую базу.