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

07. Память (Memories)

Memories — система долгосрочной памяти AstraCode. Она читает прошлые сессии (rollout'ы), извлекает из них устойчивые факты о пользователе, проекте, предпочтениях, и подмешивает их в новые сессии.

Реализация — крейты memories/read/ и memories/write/. Хранилище — ~/.astracode/memories/, под git-контролем.

1. Общая идея

text
Сессия 1: пользователь говорит "I prefer Rust over Python"
  ↓ (через несколько часов / при старте новой сессии)
Phase 1: модель читает rollout, извлекает "user prefers Rust"
  ↓
raw_memories.md  — сюда падает извлечённый факт
  ↓ (когда накопилось достаточно или раз в N часов)
Phase 2: модель консолидирует raw_memories в структурированные блоки
  ↓
MEMORY.md, memory_summary.md — оконсолидированная база
  ↓
Сессия 2: при старте memory_summary.md инжектится в developer instructions модели

Идея: модель сама управляет своей долгосрочной памятью, без ручной разметки. Аналог чужой ChatGPT Memory, но локально и под git.

2. Конфигурация

toml
[memories]
generate_memories = true                   # включает Phase 1+2
use_memories = true                        # инжектит memory_summary.md в новые сессии
disable_on_external_context = false        # отключить если AGENTS.md уже большой
max_raw_memories_for_consolidation = 256   # сколько raw-памятей берёт Phase 2
max_rollout_age_days = 10                  # окно по возрасту сессий
min_rollout_idle_hours = 6                 # ждать N часов после сессии перед Phase 1
extract_model = "claude-haiku-4-5"         # дешёвая модель для Phase 1
consolidation_model = "claude-sonnet-4-6"  # умная модель для Phase 2

disable_on_external_context = true — рекомендуется, если в проекте уже есть жирный AGENTS.md/CLAUDE.md.

3. Структура ~/.astracode/memories/

text
~/.astracode/memories/
├── .git/                       # автоматический git-репо
├── MEMORY.md                   # консолидированная база: Task Group секции + блоки
├── memory_summary.md           # обзорная сводка (инжектится в developer instructions)
├── raw_memories.md             # сырая память (Phase 1 output)
├── phase2_workspace_diff.md    # git-стиль diff что изменилось
└── rollout_summaries/          # резюме по rollout'ам
    ├── 2026-05-15-abc123.md
    └── 2026-05-20-def456.md

Папка под git → можно cd ~/.astracode/memories && git log чтобы видеть историю изменений памяти.

4. Структура MEMORY.md

Phase 2 организует факты в MEMORY.md по Task Group-секциям (по cwd / проекту / workflow), а внутри — блоками ## User preferences и ## Reusable knowledge:

markdown
# Task Group: <cwd / project / workflow>
scope: <описание области>
## User preferences
- when <situation>, the user asked / corrected: "<quote>" -> <guidance> [Task 1]
## Reusable knowledge
- <конкретный факт/указатель> [Task 1][Task 2]

Отдельных файлов по типам (user_profile.md, feedback_*.md, project_*.md, reference_*.md) нет — все факты живут в едином MEMORY.md + ссылаются при необходимости на rollout_summaries/.

5. Phase 1 — извлечение

Запускается асинхронно при старте сессии (если выполнены условия):

  1. Берёт rollout'ы из ~/.astracode/sessions/... за последние max_rollout_age_days.
  2. Фильтрует те, что не моложе min_rollout_idle_hours (даём сессии "остыть").
  3. Для каждого rollout отправляет в extract_model промпт: «извлеки факты о пользователе, проекте, предпочтениях».
  4. Результат пишет в raw_memories.md (append-only).
  5. Краткое резюме — в rollout_summaries/<date>-<id>.md.

Phase 1 фоновый, не блокирует TUI.

6. Phase 2 — консолидация

Запускается: - по таймеру (раз в день); - когда raw_memories.md превышает порог; - вручную через /memories → "Re-consolidate".

Шаги: 1. Загружает топ-N raw-памятей (по частоте использования). 2. Запускает внутреннего агента-консолидатора (consolidation_model) без сетевого доступа. 3. Агент обновляет MEMORY.md и memory_summary.md, пишет diff в phase2_workspace_diff.md. 4. Коммитит результат в локальный .git.

Агент работает по системному промпту, описывающему правила (что хранить, что не хранить, как структурировать).

7. Использование в новых сессиях

Если use_memories = true, при старте сессии: 1. Читается memory_summary.md. 2. Содержимое инжектится в developer instructions (через build_memory_tool_developer_instructions). 3. Если файл большой — обрезается по токенам (лимит MEMORY_TOOL_DEVELOPER_INSTRUCTIONS_SUMMARY_TOKEN_LIMIT = 5000, TruncationPolicy::Tokens). 4. Агенту даётся read-path промпт: он может дополнительно открыть MEMORY.md или файлы из rollout_summaries/ через memory-read tool, когда нужен конкретный файл.

Цитирование: если модель использовала файлы памяти, она обязана добавить в конец ответа один <memory_citation> XML-блок. Структура для программного парсинга (парсер — memories/read/src/citations.rs, тип MemoryCitation в protocol/src/memory_citation.rs):

xml
<memory_citation>
<citation_entries>
MEMORY.md:234-236|note=[responsesapi citation extraction code pointer]
rollout_summaries/2026-02-17T21-23-02-LN3m-weekly_memory_report_pivot_from_git_history.md:10-12|note=[weekly report format]
</citation_entries>
<rollout_ids>
019c6e27-e55b-73d1-87d8-4e01f1f75043
</rollout_ids>
</memory_citation>

Формат каждой записи: <file>:<line_start>-<line_end>|note=[<как использована>]. Пути — относительно ~/.astracode/memories/. AstraCode парсит блок в MemoryCitation (protocol/src/memory_citation.rs) для рендера в UI.

8. Команда /memories

В TUI:

text
/memories

Открывает экран: - Статус Phase 1 / Phase 2 (когда запускались, сколько обработано). - Размер MEMORY.md, количество файлов памяти. - Кнопки: Re-consolidate, Disable, Open in editor, Open git log.

9. Безопасность памяти

  • Файлы памяти не шифруются (но лежат в ~/.astracode, привилегированном).
  • Phase 2 запускается без сетевого доступа → агент-консолидатор не может «слить» данные.
  • API-ключи и секреты не должны попадать в память (модель явно проинструктирована не извлекать их).
  • Чтобы убрать факт: отредактировать MEMORY.md (или соответствующий rollout_summaries/ файл), либо удалить весь файл.

10. Что НЕ хранится в памяти

(Из инструкции консолидатора)

  • Код, конвенции, архитектура — выводится из git и репо.
  • Git-история и изменения — есть git log.
  • Решения багов — есть в коммитах.
  • AGENTS.md/CLAUDE.md — уже в контексте.
  • Эфемерные детали текущей задачи.

11. Отключить память

Полностью:

toml
[memories]
generate_memories = false
use_memories = false

Или по сессиям: запустить astracode --disable memories ... (отключает feature memories на этот запуск, эквивалент -c features.memories=false).

12. Сброс памяти

Остановите AstraCode и сначала сохраните существующее memory repo:

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

При следующем старте папка будет создана заново, пустая. Backup сохраняет историю git и позволяет отменить сброс.

13. Отладка

bash
# Где живут rollout'ы:
ls ~/.astracode/sessions/

# История консолидации:
cd ~/.astracode/memories
git log --oneline

# Текущий diff Phase 2:
cat ~/.astracode/memories/phase2_workspace_diff.md

# Логи извлечения:
grep memories ~/.astracode/log/astracode-tui.log

14. Файлы кода

  • Чтение: astracode-rs/memories/read/
  • Запись: astracode-rs/memories/write/
  • Phase 1 entry: memories/write/src/phase1.rs
  • Phase 2 entry: memories/write/src/phase2.rs
  • Read-path промпт + инъекция memory_summary.md: memories/read/src/prompts.rs
  • Команда /memories: astracode-rs/tui/src/chatwidget/slash_dispatch.rs (ветка Memories)
ESC