15. Хранилище данных — AstraCode — Техническая документация

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

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

text

~/.astracode/
├── config.toml                  # пользовательский конфиг
├── managed_config.toml          # managed-слой (опционально, через MDM/host)
├── installation_id              # стабильный UUID инсталляции
├── state_5.sqlite               # БД состояния (текущая версия — 5)
├── state_5.sqlite-shm
├── state_5.sqlite-wal
├── logs_2.sqlite                # БД логов выполнения
├── logs_2.sqlite-shm
├── logs_2.sqlite-wal
├── history.jsonl                # история пользовательских вводов
│
├── secrets/
│   ├── local.age                # зашифрованные секреты
│   └── local.key                # fallback мастер-ключ (если keyring недоступен)
│
├── memories/                    # система памяти (под git)
│   ├── .git/
│   ├── MEMORY.md
│   ├── memory_summary.md
│   ├── raw_memories.md
│   ├── phase2_workspace_diff.md
│   ├── rollout_summaries/
│   ├── user_profile.md
│   ├── feedback_*.md
│   ├── project_*.md
│   └── reference_*.md
│
├── sessions/                    # rollout-файлы по дате
│   └── YYYY/MM/DD/
│       └── <thread_id>.json     # метаданные
│       └── <thread_id>.jsonl    # события (turn-by-turn)
│
├── skills/                      # скиллы
│   ├── .system/                 # встроенные (~/.astracode/skills/.system/<skill>/)
│   │   ├── skill-creator/
│   │   ├── pdf/
│   │   ├── doc/
│   │   └── ...
│   └── <custom>/                # пользовательские
│
│
├── shell_snapshots/             # снимки shell-окружения
│   └── <snapshot_id>.json
│
├── mcp_oauth/                   # OAuth-токены для MCP (если store = file)
│   └── <server_id>.token
│
├── plugins/                     # пользовательские плагины
│   └── <plugin>/
│
├── rules/                       # approval-профили
│   └── <profile>.toml
│
├── memories_extensions/         # расширения для памяти
│
├── log/                         # текстовые логи
│   └── 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, title, model, provider, created_at, cwd, cli_version, …)
`thread_goals`	Цели тредов (см. 13-goal-and-modes.md)
`thread_dynamic_tools`	Динамически подключённые инструменты треда
`thread_spawn_edges`	Связи «родитель → дочерний тред»
`agent_jobs` / `agent_job_items`	Фоновые agent-задания и их элементы
`backfill_state`	Прогресс backfill-миграций исторических данных
`stage1_outputs`	Промежуточные выводы Phase 1 памяти
`remote_control_enrollments` / `device_key_bindings`	Привязки удалённого управления и device-key

(Полный и актуальный список — в astracode-rs/state/migrations/.) Цифра в имени (_5) — версия schema. При повышении мажорной версии создаётся новый файл, старый остаётся.

logs_2.sqlite

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

Логи можно ротировать (старше N дней удаляются автоматически — настраивается).

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

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

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

5. history.jsonl

Append-only JSONL с историей пользовательских вводов (короткие записи). Хранит только текст, отправленный пользователем в composer, — это не общая история всех событий сессий:

jsonl

{"session_id": "...", "ts": 0, "text": "..."}
{"session_id": "...", "ts": 0, "text": "..."}

Используется для навигации по ранее введённым сообщениям. Список тредов для меню выбора /resume берётся не отсюда, а из rollout/state-хранилища (sessions/ и state_5.sqlite).

6. secrets/

См. 09-security.md.

text

secrets/
├── local.age   # зашифрованный JSON-словарь секретов
└── local.key   # fallback мастер-ключ (только если keyring недоступен)

Файл local.age — это age-encrypted BTreeMap<String, Secret> (имя секрета → значение + scope + metadata).

7. memories/

См. 07-memories.md.

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

8. sessions/

Rollout-файлы — основной артефакт сессии. Структура:

text

sessions/2026/06/01/
├── 9e3b4f12-...-abc.json     # метаданные (rolled_at, model, provider, summary)
└── 9e3b4f12-...-abc.jsonl    # события turn-by-turn

JSONL-формат события:

json

{"type": "user_message", "ts": "2026-06-01T10:23:45Z", "content": "..."}
{"type": "model_text_delta", "ts": "...", "delta": "..."}
{"type": "tool_use_start", "ts": "...", "tool_id": "...", "name": "local_shell", "input": {...}}
{"type": "tool_use_end", "ts": "...", "tool_id": "...", "output": "...", "exit_code": 0}
{"type": "assistant_message", "ts": "...", "content": "..."}

Rollout полностью описывает сессию и используется для /resume и анализа.

Поиск rollout

bash

ls ~/.astracode/sessions/2026/06/             # вручную по дате

В TUI:

text

/rollout    # путь к текущему rollout-файлу

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

9. skills/

См. 05-skills.md.

text

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

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

10. shell_snapshots/

Снимки переменных окружения и состояния shell в начале tool-вызовов. Используются для диагностики «почему модель решила, что в env есть X»:

json

{"snapshot_id": "...", "captured_at": "...", "env": {...}, "cwd": "...", "git_branch": "..."}

Хранятся ограниченное время (по умолчанию 7 дней).

11. log/

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

text

log/astracode-tui.log

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

Ротация: по размеру (10 MB → ротация в astracode-tui.log.1, .2, …, до 5 файлов).

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. Очистка

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

bash

find ~/.astracode/sessions -mtime +90 -delete

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

bash

rm -rf ~/.astracode/log/*

Для текстовых логов (log/) достаточно команды выше.

⚠️ Не перенаправляйте вывод в файл БД (например, > ~/.astracode/logs_2.sqlite). Перенаправление обнуляет файл SQLite и повреждает базу вместе с её WAL-файлами (-wal, -shm). Базы логов нельзя «очищать» таким способом.

Для обслуживания БД логов используйте только безопасный сценарий:

Полностью остановите AstraCode (ни один процесс не должен держать БД открытой).
Сделайте резервную копию всех трёх файлов: logs_2.sqlite, logs_2.sqlite-wal, logs_2.sqlite-shm.
Только после этого, при задокументированном восстановлении, можно удалить и пересоздать БД — удаляйте файл целиком (rm), а не обнуляйте его перенаправлением: bash # AstraCode остановлен, резервная копия сделана rm -f ~/.astracode/logs_2.sqlite ~/.astracode/logs_2.sqlite-wal ~/.astracode/logs_2.sqlite-shm При следующем запуске AstraCode создаст БД логов заново.

Штатная очистка логов выполняется ротацией (старше N дней удаляются автоматически — настраивается), отдельных ручных действий обычно не требуется.

Полный сброс

bash

rm -rf ~/.astracode

⚠️ Удалит всё: секреты, сессии, память, кастомные скиллы.

14. Бэкап

Что бэкапить: - config.toml — конфиг. - secrets/local.age — секреты (но без мастер-ключа из keyring бесполезен!). - memories/ — память. - skills/<custom>/ — кастомные скиллы. - state_5.sqlite — метаданные тредов и goals.

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

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

bash

tar czf astracode-backup-$(date +%F).tar.gz \
  ~/.astracode/config.toml \
  ~/.astracode/secrets/ \
  ~/.astracode/memories/ \
  ~/.astracode/skills/$(ls ~/.astracode/skills | grep -v .system | tr '\n' ' ')

И отдельно сохранить мастер-ключ из keyring (secret-tool lookup service astracode account <hash>) — без него local.age не дешифруется.

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

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

bash

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

⚠️ Смена ASTRACODE_HOME меняет account для keyring (account = SHA256(canonical($ASTRACODE_HOME))). Существующие секреты в другой директории недоступны.

16. Multi-user или multi-instance

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

bash

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

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

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

2. config.toml

3. installation_id

4. SQLite-БД

state_5.sqlite

logs_2.sqlite

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

5. history.jsonl

6. secrets/

7. memories/

8. sessions/

Поиск rollout

9. skills/

10. shell_snapshots/

11. log/

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

13. Очистка

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

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

Полный сброс

14. Бэкап

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

16. Multi-user или multi-instance

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