CodeAlmanac

CodeAlmanac ведёт вики по кодовой базе, которую пишут и поддерживают в актуальном состоянии coding-агенты. Она ориентирована на контекст, который сам код передать не может: почему система устроена именно так, что ломалось раньше, какие инварианты важны и как рабочий процесс проходит сквозь файлы и сервисы. Вики хранится в виде обычного markdown в директории almanac/ репозитория, индексируется локально и рецензируется в Git как любые другие изменения. Это llm-wiki-pattern, применённый к кодовой базе, - см. llm-wiki-as-agent-memory о том, почему несколько независимых проектов пришли к одной и той же основе.

Как это устроено

Всю работу с текстом выполняют три lifecycle-агента - build, ingest и garden. Они работают через собственный Yoke SDK проекта, а полные инструкции к задачам упакованы в файлы промптов.

ingest встраивает материалы в вики. На вход можно передавать файлы, директории, git diff, диапазоны коммитов, PR или issue на GitHub, URL и локальные транскрипты агентов:

codealmanac ingest README.md --using codex
codealmanac ingest github:pr:123 --using claude

garden работает с графом, а не добавляет новые данные: ищет устаревшие страницы, битые ссылки, темы, слабые зацепки, дубликаты и неподтверждённые утверждения.

Интерфейс для чтения общий для агентов и людей и намеренно сделан простым:

codealmanac search "checkout timeout"
codealmanac search --mentions src/checkout/
codealmanac show checkout-flow
codealmanac topics
codealmanac health
codealmanac serve            # local web viewer, with a Jobs panel

Суть в автоматизации

codealmanac setup устанавливает три задачи macOS launchd:

Job	Default	What it does
Sync	каждые 5 ч	Сканирует локальные хранилища транскриптов Codex и Claude на предмет диалогов со времени последней синхронизации, ставит долгосрочные знания в очередь для нужной вики
Garden	каждые 24 ч	Проверяет каждую зарегистрированную вики на предмет устаревших, дублирующихся или плохо связанных страниц
Update	каждые 24 ч	Обновляет CLI, когда это безопасно

Sync - самый интересный компонент, и именно его не хватает большинству похожих систем: источником знаний служат ваши текущие диалоги с агентами, собираемые в пассивном режиме, а не то, что вы не забыли записать вручную. Архитектура явно допускает отсутствие изменений: "No-op is valid. If the material adds no durable wiki knowledge, the harness should leave the wiki unchanged" - и для автономного генератора это правильное поведение по умолчанию, в отличие от того, что получилось бы при наивной реализации.

Модель доверия

README высказывается об этом непривычно прямо, и это главное, что нужно взвесить перед запуском:

Lifecycle-агенты - это доверенные локальные coding-агенты. Они работают с теми же широкими неинтерактивными правами доступа к файловой системе, которые CodeAlmanac предоставлял исторически, поэтому граница almanac/ - это политика инструкций и коммитов, а не песочница ОС.

В итоге каждые пять часов на вашей машине запускается автономный агент с полным доступом к файловой системе. Авторы советуют использовать инструмент только в тех репозиториях, где вы готовы с этим мириться, и проверять git diff, если автоматические коммиты отключены. Всем, кто уже задумывается о sandboxing-ai-agents или bubblewrap-dev-env, захочется изолировать этот процесс, а не использовать настройки по умолчанию.

Телеметрия подключается добровольно по рекомендации во время установки; по документации отправляются результаты команд и жизненного цикла, а также очищенные отчёты о падениях под случайным UUID установки, с отключённым GeoIP и без кода, путей, аргументов, запросов, промптов или транскриптов. Переменная DO_NOT_TRACK=1 поддерживается.

Ограничения

Работает только на macOS и требует Codex или Claude Code в качестве runner'а. Python 3.12+, устанавливается через uv tool install codealmanac@latest. К macOS инструмент привязан именно из-за зависимости от launchd - в самой архитектуре нет ничего специфичного для Apple, поэтому перенос на systemd-timer в Linux напрашивается сам собой.

Оценка

Две идеи, которые стоит перенять независимо от того, будете ли вы внедрять сам инструмент: сбор долгосрочных знаний из уже создаваемых транскриптов агентов и регулярный прогон задач по уходу за базой как полноценный процесс, а не разовое действие, когда в вики всё стало плохо. В этом vault'е вторая задача выполняется вручную в рамках процесса /lint.

В списке watchlist - 529★, YC S26, только под macOS, а модель автоматического агента с доступом к файловой системе должна пройти проверку реальными пользователями, прежде чем её можно будет безоговорочно рекомендовать.

Apache-2.0, 529★, 45 форков. Репозиторий: https://github.com/AlmanacCode/codealmanac