0.4.11
Поиск по документации… ⌘K
15 · Техническая документация

15. Хранилище данных

AstraCode хранит всё пользовательское состояние в ~/.astracode/ (или в директории, указанной через ASTRACODE_HOME). Это включает: конфиг, секреты, сессии, память, скиллы, логи.

1. Общая структура

text
~/.astracode/
├── config.toml                  # пользовательский конфиг
├── installation_id              # стабильный UUID инсталляции
├── state_5.sqlite               # БД состояния; суффикс _5 исторический
├── state_5.sqlite-shm
├── state_5.sqlite-wal
├── logs_2.sqlite                # БД логов; суффикс _2 исторический
├── logs_2.sqlite-shm
├── logs_2.sqlite-wal
├── history.jsonl                # история ввода в composer (input history)
├── .credentials.json            # учётные данные (в т.ч. MCP OAuth-токены), единый файл
├── license.key                  # опц. drop-in токен для активации/продления
├── license_state.json           # file backend или mirror activation record
│
├── secrets/
│   ├── local.age                # зашифрованные секреты (age-encrypted BTreeMap<String,String>)
│   └── local.key                # мастер-ключ при file storage (default на macOS)
│
├── memories/                    # система памяти (под git)
│   ├── .git/
│   ├── memory_summary.md
│   ├── raw_memories.md
│   ├── phase2_workspace_diff.md
│   └── rollout_summaries/
│
├── sessions/                    # rollout-файлы (по одному JSONL на тред)
│   └── YYYY/MM/DD/
│       └── rollout-<timestamp>-<uuid>.jsonl
│
├── skills/                      # скиллы
│   ├── .system/                 # встроенные (~/.astracode/skills/.system/<skill>/)
│   │   ├── skill-creator/
│   │   ├── pdf/
│   │   ├── doc/
│   │   └── ...
│   └── <custom>/                # пользовательские
│
├── shell_snapshots/             # снимки shell-окружения (.sh/.ps1)
│   └── <session_id>.<nonce>.sh  # (или .ps1 на Windows)
│
├── projects/<sha256_cwd>/        # per-project хранилище
│   ├── undo/<thread_id>.jsonl   # baseline'ы файловых изменений для `/undo`
│   └── ...                      # индекс проекта и т.п.
│
├── plugins/                     # пользовательские плагины
│   └── <plugin>/
│
├── rules/                       # approval-профили (Starlark)
│   └── default.rules            # расширение .rules, не .toml
│
├── memories_extensions/         # расширения для памяти
│
├── log/                         # текстовые логи (append, без ротации)
│   └── astracode-tui.log
│
└── tmp/                         # временные файлы

2. config.toml

Основной конфиг. См. 03-configuration.md для полного списка секций.

AstraCode сам пишет в него секцию [ui_state] (последний провайдер, модель). Остальные секции — на пользователе.

3. installation_id

text
~/.astracode/installation_id

Случайный UUID, генерируется при первом запуске. Используется для: - Идентификации в телеметрии (если включена). - Стабильной идентификации в feedback-репортах.

Не содержит PII. Можно удалить — при следующем запуске будет сгенерирован новый.

4. SQLite-БД

state_5.sqlite

Главная база. Таблицы (примерно):

Таблица Что хранит
threads Метаданные тредов (id, rollout_path, title, model_provider, cwd, sandbox_policy, approval_mode, git_sha/branch/origin_url, archived)
thread_goals Цели тредов (см. 13-goal-and-modes.md)
thread_dynamic_tools Динамически зарегистрированные tools треда
thread_spawn_edges Связи родитель↔ребёнок между тредами (сабагенты)
agent_jobs Пакетные задания агента (имя, статус, instruction, пути CSV)
agent_job_items Строки заданий (row_json, status, assigned_thread_id, результат)
stage1_outputs Промежуточные выводы Phase 1 памяти (rollout_slug)
jobs Внутренние фоновые job'ы памяти (kind, job_key, статус, lease, retry)
backfill_state Состояние backfill-процессов памяти
device_key_bindings Привязки device-key (keyring/keyless-устройства)
remote_control_enrollments Регистрации remote-control сессий

Кэш каталога моделей хранится не в БД, а в файле ~/.astracode/models_cache.json (models-manager/src/manager.rs). Состояние UI (последний провайдер/модель) лежит в секции [ui_state] файла config.toml, а не в таблице.

Суффикс _5 исторический. Текущая схема развивается внутри того же файла через state/migrations/; runtime больше не создаёт новый файл при каждом bump schema version.

logs_2.sqlite

Логи выполнения. Записываются асинхронно через otel-крейт: - События запроса к LLM (start, end, токены, стоимость). - Tool-вызовы и их результаты. - Ошибки и warnings.

Runtime ограничивает размер и число строк по log partition; это не настраиваемая ротация «старше N дней».

Безопасность БД

SQLite-файлы — 0o600 (только владелец). Не шифруются, но не содержат секретов (API-ключи только в secrets/local.age).

WAL-файлы (-wal, -shm) появляются при работе. Не удалять во время работы AstraCode — это сломает БД.

5. history.jsonl

Append-only JSONL с историей ввода пользователя в composer (input history). Это не данные тредов для /resume (треды берутся из state DB). Каждая запись — HistoryEntry из core/src/message_history.rs:57:

rust
pub struct HistoryEntry {
    pub session_id: String,
    pub ts: u64,
    pub text: String,
}

Пример содержимого:

jsonl
{"session_id": "...", "ts": 1717230000, "text": "fix the bug in auth.rs"}
{"session_id": "...", "ts": 1717230045, "text": "run the test suite"}

Используется для автодополнения ввода в composer. Список тредов для /resume формируется из таблицы threads в state_5.sqlite, а не из этого файла.

6. secrets/

См. 09-security.md.

text
secrets/
├── local.age   # зашифрованный JSON: BTreeMap<String, String>
└── local.key   # мастер-ключ при ASTRACODE_PROVIDER_SECRETS_KEY_STORAGE=file

Файл local.age — это age-encrypted BTreeMap<String, String> (имя секрета → строковое значение). Структура файла — SecretsFile { version, secrets: BTreeMap<String, String> } (см. secrets/src/local.rs:50). Отдельных полей scope/metadata у секрета нет.

License activation record хранится отдельно от provider secrets: в OS keyring и/или license_state.json. Drop-in license.key поглощается license gate при следующем запуске. См. 24-license.

7. memories/

См. 07-memories.md.

Под git — папка инициализируется как репозиторий при первом включении memories. Каждое изменение в Phase 2 коммитится автоматически.

8. sessions/

Rollout-файлы — основной артефакт сессии. На каждый тред — один файл в формате JSONL с именем rollout-<timestamp>-<uuid>.jsonl, размещённый в директории даты (см. rollout/src/recorder.rs:1370):

text
sessions/
└── 2026/06/01/
    └── rollout-2026-06-01T10-23-45-9e3b4f12-94b8-487b-a530-2aeb6098ae0e.jsonl

Имена EventMsg (сериализуются через #[serde(tag="type", rename_all="snake_case")], см. 21-rollout-format.md):

json
{"type": "user_message", "ts": "...", "content": "..."}
{"type": "agent_message_delta", "ts": "...", "delta": "..."}
{"type": "item_started", "ts": "...", "tool_id": "...", "name": "local_shell", "input": {...}}
{"type": "item_completed", "ts": "...", "tool_id": "...", "output": "...", "exit_code": 0}
{"type": "agent_message", "ts": "...", "content": "..."}

Rollout полностью описывает сессию.

Поиск rollout

bash
find ~/.astracode/sessions -type f -name 'rollout-*.jsonl'

В TUI:

text
/rollout    # путь к текущему rollout

(дебаг-команда, доступна только в debug-сборке (cfg!(debug_assertions)), не в release).

Для анализа rollout есть отдельная дебаг-команда (без треда):

bash
astracode debug trace-reduce <trace-bundle>   # единственная debug-команда для rollout

Команд astracode replay и astracode debug rollout не существует.

9. skills/

См. 05-skills.md.

text
skills/
├── .system/         # встроенные, ставятся при первом запуске
└── <user-skill>/    # пользовательские

При обновлении AstraCode .system/ перезаписывается — не редактируйте файлы внутри, изменения потеряются.

10. shell_snapshots/

Снимки переменных окружения и состояния shell в начале tool-вызовов. Используются для диагностики «почему модель решила, что в env есть X». Снимки сохраняются как скрипты с расширением .sh (Unix) или .ps1 (PowerShell/Windows), а не JSON (см. core/src/shell_snapshot.rs:124):

text
shell_snapshots/<session_id>.<nonce>.sh

Хранятся ограниченное время — 3 дня (SNAPSHOT_RETENTION = 60*60*24*3 в core/src/shell_snapshot.rs:33), устаревшие удаляются.

10a. projects//undo/ (отмена изменений)

Каждое срабатывание apply_patch и write_file снимает пред-состояние (baseline) каждого затронутого файла и кладёт его в отдельное хранилище, намеренно отрезанное от rollout-файла — так компактизация и обрезка истории (thread_rollout_truncation) не орфанят undo-записи:

text
projects/<sha256_cwd>/undo/<thread_id>.jsonl

Команда /undo (или /undo <call_id>) откатывает конкретное изменение: перезаписывает файл записанными байтами, либо удаляет файл, если он был создан агентом; бинарники хранятся и восстанавливаются как байты. Модель LIFO-only (последнее изменение файла восстанавливается первым), без redo; коллаб-/сабагентские правки живут в хранилище своего треда. Состояние терминально и переживает рестарт (crash recovery). Серверный доступ — через fs/listChanges и fs/undo.

11. log/

Текстовые логи (читабельные глазами):

text
log/astracode-tui.log

Формат: [timestamp] [level] [module] message.

Ротация отсутствует — логи пишутся простым append. При необходимости файл можно очистить вручную.

12. Сколько весит ~/.astracode/

Примерные оценки для активного пользователя (3 месяца использования):

Часть Размер
config.toml < 10 KB
state_5.sqlite 10–50 MB
logs_2.sqlite 50–200 MB
sessions/ 100 MB — 1 GB
memories/ + .git 5–20 MB
skills/.system/ 50–100 MB
skills// 1–10 MB
secrets/ < 100 KB
log/ < 50 MB
Итого 200 MB — 1.5 GB

13. Очистка

Удалить старые сессии

Используйте archive/delete action в picker /sessions. Фактически picker архивирует тред и сохраняет возможность работать с согласованными metadata. Прямое удаление rollout-файла делает сессию невосстановимой; при следующем списке AstraCode обнаружит отсутствующий путь и удалит соответствующую строку metadata. Поддерживаемого массового физического purge API сейчас нет.

Очистить логи

Сначала полностью остановите все процессы AstraCode. Не обнуляйте отдельный SQLite-файл: это оставляет WAL/SHM несогласованными. Для принудительного сброса переместите всю группу в резервную директорию; runtime создаст новую БД и применит миграции:

bash
mkdir -p ~/.astracode/log-reset-backup
mv ~/.astracode/logs_2.sqlite ~/.astracode/log-reset-backup/
mv ~/.astracode/logs_2.sqlite-wal ~/.astracode/log-reset-backup/
mv ~/.astracode/logs_2.sqlite-shm ~/.astracode/log-reset-backup/
mv ~/.astracode/log/astracode-tui.log ~/.astracode/log-reset-backup/

Если WAL/SHM или текстовый лог отсутствуют, соответствующая команда mv просто завершится ошибкой; это не мешает перенести остальные существующие файлы.

Сбросить кэш каталога моделей

bash
rm ~/.astracode/models_cache.json

(кэш лежит в файле, не в SQLite; при следующем запуске пересоздастся)

Полный сброс

Полностью остановите AstraCode и переместите всю директорию в заранее выбранное место вне $ASTRACODE_HOME:

bash
mv ~/.astracode /path/to/astracode-data-backup

Следующий запуск создаст чистое хранилище. Не удаляйте backup, пока не проверены конфигурация, сессии, память, кастомные скиллы и расшифровка секретов.

14. Бэкап

Что бэкапить: - config.toml — конфиг. - secrets/local.age и secrets/local.key, если выбран file storage. - memories/ — память. - skills/<custom>/ — кастомные скиллы. - state_5.sqlite — метаданные тредов и goals. - sessions/ — содержимое тредов, на которое ссылается state DB.

Что не бэкапить: - logs_2.sqlite, log/ — логи. - skills/.system/ — переустановится автоматически. - tmp/, shell_snapshots/ — эфемерные.

Минимальный бэкап:

bash
tar -C "$HOME" -czf astracode-backup-$(date +%F).tar.gz \
  --exclude='.astracode/skills/.system' \
  .astracode/config.toml \
  .astracode/secrets/ \
  .astracode/memories/ \
  .astracode/skills/ \
  .astracode/state_5.sqlite \
  .astracode/sessions/

Бэкап делайте после корректной остановки процесса, чтобы основной SQLite-файл содержал checkpoint WAL. Если выбран keyring, сохраните credential отдельно подходящим для вашей ОС защищённым способом; Linux-команда secret-tool не является переносимым способом экспорта для macOS. Без соответствующего ключа local.age не расшифровывается.

15. Переменные ASTRACODE_HOME

Можно поместить всё в другую директорию:

bash
export ASTRACODE_HOME=/mnt/work/astracode-data
mkdir -p $ASTRACODE_HOME
astracode

При keyring storage смена ASTRACODE_HOME меняет account (secrets|<short SHA256(canonical($ASTRACODE_HOME))>). При file storage vault можно переносить только вместе с secrets/local.key и с сохранением безопасных прав доступа.

16. Multi-user или multi-instance

Можно запустить несколько инстансов AstraCode с разными ASTRACODE_HOME — они полностью изолированы:

bash
ASTRACODE_HOME=~/.astracode-work astracode
ASTRACODE_HOME=~/.astracode-personal astracode

Полезно для разделения секретов (рабочие/личные ключи).

ESC