Как я поддерживаю здоровье knowledge vault для AI-агентов: health checks, валидация и автоисправление

Когда у тебя один AI-агент — хаос в knowledge base прощается. Когда три агента одновременно пишут в один Obsidian vault — хаос становится дорогим.

На моём сервере Hermes Agent, Claude Code и Codex работают из одного Obsidian vault как из shared memory. Это устранило дрейф знаний и дублирование работы. Но возникла новая проблема: как поддерживать vault в здоровом состоянии, когда три агента пишут в него по 10+ раз в день?

Битые wikilinks, пропавший frontmatter, грязный git, случайные секреты в заметках — всё это накапливается и делает vault бесполезным. В этой статье — как я построил систему health checks для knowledge vault и какие инструменты написал, чтобы спать спокойно.

Почему здоровье vault — это не «опционально»

До того как я ввёл health checks, vault деградировал за 5-7 дней. Вот что происходило:

Битые wikilinks. Claude Code создавал заметку и линковал «[[AGENT_HANDOFF]]» — но Codex переименовывал файл, и линк становился мёртвым. На четвёртый день в vault было 12 битых ссылок.
Пропавший frontmatter. Hermes создавал playbook без YAML-заголовка — инструменты vault не могли его классифицировать, поиск ломался.
Грязный git. Агенты генерировали заметки, но никто не коммитил. История изменений терялась. После ребута контейнера — откат на старую версию, новый контент пропадал.
Секреты в заметках. Claude Code однажды вставил API-ключ в тело playbook’а. Я заметил через 3 дня, когда полез читать.

Это не теоретические страхи — реальные грабли с production-стеком. Итог: vault без health checks — это бомба замедленного действия.

Инструмент: bronevik-vault-status

Я написал скрипт bronevik-vault-status, который прогоняет vault через 8 проверок и возвращает структурированный ответ:

$ bronevik-vault-status

git_dirty_count=0
obsidian_config=present
missing_required_count=0
missing_frontmatter_count=0
broken_wikilinks_count=0
secret_like_paths_count=0
content_overall=ok
overall=ok

Восемь полей — восемь аспектов здоровья. Когда overall=ok — vault чист, агенты могут работать. Когда нет — фиксим до следующей сессии.

Этот же блок встроен в общий bronevik-status (под секцией knowledge-vault), так что я вижу состояние vault вместе с состоянием Docker-контейнеров, systemd-юнитов и бэкапов в одном выводе.

Что проверяется

git_dirty_count. Сколько незакоммиченных изменений. Цель — 0. Даже одно изменение — повод заглянуть и закоммитить. Агенты не коммитят автоматически (это осознанное решение: коммиты должны быть осмысленными), поэтому я делаю это вручную или через cron раз в сутки.
obsidian_config. Существует ли .obsidian/ с настройками. Без этого Obsidian не признает vault своим. Была ситуация, когда после обновления Docker-образа .obsidian/ не примонтировался — vault работал как папка с текстовыми файлами, wikilinks перестали резолвиться.
missing_required_count. Есть ли обязательные корневые заметки: HOME.md, AGENTS.md, HERMES.md, CLAUDE.md, README.md. Это точка входа для каждого агента. Без AGENTS.md Claude Code не знает, какие правила применять.
missing_frontmatter_count. Сколько .md-файлов без YAML-frontmatter. Исключение: README.md разрешено без frontmatter. Всё остальное должно иметь тип, владельца, статус и теги.
broken_wikilinks_count. Сколько [[ссылок]] ведут в никуда. Самый частый источник проблем: файл переименован, перемещён или удалён, а ссылки остались.
secret_like_paths_count. Нет ли в vault файлов, похожих на секреты: ключи, токены, пароли. Это safety net — агентам запрещено хранить секреты в vault, но лучше перепроверить.
content_overall. Общая оценка контента: нет ли пустых заметок, корректны ли даты обновлений.
overall. Агрегат всех проверок. ok только если всё остальное тоже ok.

Что я делаю, когда vault не в порядке

Сценарий: прихожу утром, запускаю bronevik-vault-status — вижу broken_wikilinks_count=3.

Шаг 1: Найти битые ссылки

Скрипт показывает, какие именно wikilinks не резолвятся и в каких файлах они находятся. Обычно это 3-4 клика в Obsidian — и проблема видна.

Шаг 2: Понять причину

Файл переименован → обновить wikilink на новое имя.
Файл удалён → либо восстановить из git, либо удалить ссылку.
Ссылка с опечаткой → исправить.

90% битых ссылок — это файлы, переименованные другим агентом. Агенты не видят изменения в реальном времени, каждый работает со снапшотом vault на момент начала сессии.

Реальный инцидент: переименование и лавина битых ссылок

Однажды Codex реорганизовал playbooks: переименовал AGENT_SYNC.md → AGENT_SYNC_PLAYBOOK.md и переместил из 40-playbooks/ в 50-agents/. Одно переименование — и 7 битых wikilinks в 5 разных заметках. Hermes, Claude Code и даже сам Codex ссылались на старый путь.

Хуже того: два агента начали параллельные сессии до того, как я исправил ссылки. Hermes создал ДУБЛИКАТ заметки с именем AGENT_SYNC.md в 00-inbox/ — потому что не нашёл оригинал по старой ссылке и решил «восстановить» его. Теперь у меня было две версии одного playbook’а.

Урок: после любого переименования файла — немедленный прогон bronevik-vault-status и исправление ВСЕХ битых ссылок до того, как агенты начнут новые сессии.

Шаг 3: Исправить и проверить

# После исправления
bronevik-vault-status
# Должно быть: broken_wikilinks_count=0, overall=ok

Шаг 4: Закоммитить

cd /workspace/bronevik-knowledge
git add -A && git commit -m "fix: restore broken wikilinks after agent session"

Шаг 5: Триггернуть бэкап

После значимых изменений — бэкап. У меня на это есть sudo hermes-backup-now (локальный restic) и sudo hermes-offsite-backup-status для проверки офсайт-копии в Google Drive.

Про secret-сканирование: это не паранойя

AI-агенты не всегда понимают, что такое «секрет». Claude Code может вставить токен в тело заметки, потому что «так удобнее». Codex может сохранить конфиг с паролем как playbook. Hermes — скопировать .env в vault «для контекста».

У меня было два инцидента:

API-ключ в заметке. Claude Code вставил OPENAI_API_KEY=sk-... в тело операционного playbook’а. Я обнаружил через secret_like_paths_count=1 при утренней проверке. Скрипт показал файл и строку. Удалил, перекоммитил, ротировал ключ.
Файл .env в vault. Hermes скопировал .env из рабочей директории в 00-inbox/ для «справочных целей». Скрипт поймал — файл удалён до того, как попал в git history.

Правило, которое я вывел: никогда не хранить секреты в vault. Никаких исключений. Секреты живут в /opt/data/.secrets/ на хосте и читаются агентами через файловую систему — но в vault попадать не должны.

Git-целостность: почему dirty vault — это проблема

Когда git_dirty_count > 0, это значит:

Последние изменения не закоммичены.
Если контейнер упадёт или пересоздастся — незакоммиченные изменения могут потеряться (зависит от маунтов).
История vault рассинхронизирована с реальным состоянием.

Я держу git_dirty_count=0 через cron: раз в сутки Hermes проверяет vault, коммитит изменения с сообщением auto: daily vault snapshot, и пушит. Это не заменяет осмысленные коммиты, но даёт safety net.

Процедура восстановления vault из git — отдельная тема, но факт в том, что без регулярных коммитов восстанавливать нечего.

Интеграция в общий мониторинг

bronevik-vault-status — не изолированный скрипт. Он встроен в экосистему:

bronevik-status — общий health check, включает vault как одну из секций наравне с Docker-контейнерами, systemd-юнитами и бэкапами.
Cron — Hermes запускает проверку каждые 30 минут через MCP bridge: host_maintenance_status. overall=ok — тишина. overall!=ok — я получаю алерт с детализацией, что именно сломалось.
Pre-session gate — перед началом работы агенты проверяют vault. Если overall != ok — сессия не стартует, пока vault не починен. Это предотвращает каскадные повреждения.
Post-session gate — после завершения сессии vault проверяется снова. Новые битые ссылки или грязный git — повод для ручного review и коммита.

Это превращает vault из «папки с файлами» в управляемый компонент системы с измеримым состоянием.

Автоматический daily snapshot

Раз в сутки cron-джоба Hermes делает снапшот vault:

cd /workspace/bronevik-knowledge
git add -A
git diff --cached --quiet || git commit -m "auto: daily vault snapshot $(date +%Y-%m-%d)"

Это не заменяет осмысленные коммиты (их я делаю вручную, глядя на diff), но даёт safety net: если контейнер упадёт между ручными коммитами — изменения не потеряны. Ежедневный снапшот также даёт историю изменений, по которой можно отследить, какой агент и когда вносил изменения.

Что будет, если не следить: каскадный отказ

Представь: Claude Code создаёт заметку с битым wikilink на PROJECT_PLAN.md. Hermes заходит в vault, видит ссылку, идёт по ней — файла нет. Hermes решает «помочь» и создаёт заглушку PROJECT_PLAN.md с type: stub. Через час Codex заходит, видит две заметки (оригинал + заглушка) и пытается смержить — создаёт третью. Через день у тебя три версии одного документа, и никто не знает, какая правильная.

Это не гипотетический сценарий. Это случилось на второй неделе работы мультиагентной системы. Именно после этого я написал bronevik-vault-status и ввёл pre-session gate.

Что я бы сделал иначе

Оглядываясь назад, три вещи:

Ввести health checks с первого дня. Я внедрил bronevik-vault-status через 2 недели после запуска мультиагентной системы. Первые две недели были хаосом.
Автоматический commit после каждой сессии. Сейчас я делаю это вручную или через ежедневный cron. Агенты могли бы коммитить сами — но я опасаюсь «грязных» коммитов с мусором. Возможно, нужен pre-commit hook с валидацией.
Более строгий секретный скоринг. Сейчас проверка ищет паттерны (sk-, ghp_, cfut_). Но пароль mypassword123 она не найдёт. Нужен более умный детектор.

Итог

Knowledge vault для AI-агентов — это не просто папка с Markdown. Это операционная система знаний, и она требует обслуживания.

Мои уроки:

Health checks — не опция, а must-have. Без них vault деградирует за неделю.
Валидация wikilinks и frontmatter — первое, что ломается при совместной работе агентов.
Secret-сканирование — не паранойя. Агенты реально кладут секреты в заметки.
Git-целостность — без регулярных коммитов история теряется.
Интеграция в мониторинг — vault должен быть частью общего health check системы.

Если строишь мультиагентную систему на Obsidian — начни с health checks. Это сэкономит тебе недели отладки и пару седых волос.