Project Memory

Project Memory — это project-local память SOBA Agent. Она хранится в репозитории в .soba/memory/ и переживает перезапуск процесса, новую сессию и compaction.

В v0.6.x Project Memory — это слой памяти, который SOBA автоматически подключает к agent loop, два agent tools и one-shot diagnostic command:

• read_project_memory — прочитать bounded и sanitized память проекта;
• write_project_memory — записать knowledge-файл или memory capsule.
• soba memory doctor — проверить persisted memory без запуска agent runtime.

1. Структура на диске

При первом использовании Project Memory создаёт директорию:

.soba/memory/
├── knowledge/
│   ├── architecture.md
│   ├── conventions.md
│   ├── known-errors.md
│   └── dependencies.md
├── capsules/
│   └── index.json
└── graph.json

Knowledge files

Knowledge files — это стабильные проектные документы, которые полезны почти в каждой сессии.

Memory capsules

Memory capsules — структурированные записи о решениях, ошибках, discovery и паттернах. Они лежат в .soba/memory/capsules/*.json, а индекс — в .soba/memory/capsules/index.json.

Поддержанные типы:

• decision
• error_fix
• discovery
• pattern
• blocker
• insight

Приоритеты:

• critical
• high
• medium
• low

По умолчанию хранилище держит до 50 capsules; low-priority старше 30 дней первыми попадают под pruning.

Memory source receipts

Capsule может хранить source receipt. В prompt просите поля явно: source.file, source.lines, source.lastVerified, source.confidence и staleIfFilesChange.

{
  "source": {
    "error": "Provider registry loading rule can drift",
    "fix": "Verify the source before reusing this memory",
    "file": "src/apps/cli/main.ts",
    "lines": [120, 150],
    "commit": "abc123",
    "confidence": "high",
    "lastVerified": "2026-06-19T10:00:00.000Z",
    "staleIfFilesChange": ["src/composition/runtime/create-soba-runtime.ts"]
  }
}

soba memory doctor использует эти поля, чтобы находить stale facts, deleted files, source line drift и изменения в связанных файлах.

Entity graph

graph.json хранит связи между сущностями проекта. В v0.6.x это локальный persisted graph слой для файлов, функций, классов, модулей, ошибок и зависимостей.

2. Как память попадает в prompt

SOBA создаёт ProjectMemory для текущего cwd, читает релевантные knowledge/capsules и добавляет bounded section в system prompt. Бюджет ограничен: память не должна вытеснять текущую задачу и последние важные turns.

Практический эффект:

1. В первой сессии вы сохраняете архитектурное решение.
2. Во второй сессии SOBA уже видит это решение в Project Memory.
3. Агенту не нужно заново объяснять базовый контекст проекта.

3. Как попросить агента обновить Project Memory

Пишите явно, какие факты должны стать долгоживущими:

Обнови Project Memory.

Сохрани:
- architecture: CLI разделён на parser, analyzer, reporter и adapters;
- conventions: Bun only, strict TypeScript, tests mirror src;
- known-errors: вне git repo git-команды должны возвращать controlled error;
- dependencies: runtime dependencies отсутствуют.

Используй project memory tools. Не сохраняй секреты, токены и абсолютные домашние пути.

SOBA должен использовать write_project_memory. Для проверки можно выполнить:

!find .soba/memory -maxdepth 3 -type f | sort
!sed -n '1,160p' .soba/memory/knowledge/architecture.md

4. Как попросить агента прочитать память

Перед планом прочитай Project Memory и учти architecture, conventions и known-errors.
Ничего не меняй, сначала дай краткое резюме релевантной памяти.

Агент может вызвать read_project_memory с фильтрами:

• kind: all, knowledge, capsules;
• knowledgeKey: architecture, conventions, known-errors, dependencies;
• tags;
• capsuleType;
• priority;
• from / to;
• query;
• limit;
• maxBytes.

Вывод tool ограничивается по размеру и проходит sanitation.

5. Project Memory doctor и Memory health commands

soba memory doctor проверяет .soba/memory/ для текущего project root:

soba memory doctor
soba memory doctor --format json
soba memory doctor --format markdown
soba memory stale
soba memory stale --format json
soba memory verify
soba memory verify --format json
soba memory explain "provider registry"
soba memory explain "provider registry" --format json

Отчёт включает:

• количество knowledge files, bytes и estimated tokens;
• capsules со статусом source provenance: fresh, stale, missing, outside_project, untracked, corrupted, invalid_source;
• issues для stale source files, missing source files, source line drift, ссылок за пределы project root и битых capsule JSON files.

Exit code равен 0 только при статусе healthy. Если есть stale или broken capsules, команда возвращает 1 и пишет отчёт в stderr, чтобы её можно было использовать в CI.

Команда не запускает agent runtime и не требует provider credentials.

soba memory stale показывает только stale или broken capsules и связанные issues. Это короткий actionable report для CI или pre-merge checks, когда полный doctor report слишком подробный. Exit code равен 0 только если нет stale/broken capsules и нет memory doctor issues.

soba memory verify даёт компактный verification report с полем verified. Exit code равен 0 только при verified: true, то есть когда Project Memory находится в healthy-состоянии без issues.

Memory receipt explanations читает soba memory explain <query>. Команда показывает релевантные capsules, source receipts, score и doctor issues, чтобы было понятно, можно ли использовать найденный memory факт сейчас.

soba memory explain <query> использует relevance scoring capsules и объединяет результат с memory doctor: показывает summary, tags, score, source receipt и issues для найденных capsules. Если найденный факт stale или broken, команда пишет объяснение в stderr и возвращает exit code 1.

6. Безопасность и sanitation

write_project_memory отклоняет:

• secret-like content;
• path traversal за пределы .soba/memory;
• неизвестные knowledge keys;
• некорректные capsule payloads.

Не сохраняйте в Project Memory:

• API keys;
• OAuth tokens;
• приватные ключи;
• абсолютные домашние пути;
• временные debug dumps с пользовательскими секретами.

Если нужно записать интеграционный факт, используйте placeholders:

Используется переменная окружения GITHUB_TOKEN, значение токена в Project Memory не сохранять.

7. Project Memory vs Context Capsule vs Portable Capsule

Используйте Project Memory для устойчивых знаний, Context Capsules — для управления длинным контекстом, Portable Capsules — для передачи работы.

8. Проверка

Минимальная проверка Project Memory:

Обнови Project Memory коротким архитектурным решением, затем прочитай его обратно через project memory tools.

Проверка новой сессии:

soba -i --lang ru

Кратко напомни архитектурные решения проекта из Project Memory. Ничего не меняй.

Если SOBA не видит сохранённые факты, проверьте:

• вы запускаете SOBA из того же project root;
• .soba/memory/knowledge/*.md существует;
• в памяти нет только пустых template-файлов;
• prompt явно просит использовать Project Memory.

Что дальше

• Проект шаг за шагом — end-to-end сценарий с Project Memory.
• Compaction и Context Capsules — управление длинным контекстом.
• Portable Capsules — handoff через .capsule.md.