Selvedge
Долговременная память для кодовых баз, написанных ИИ — включая то, что уже было опробовано и отклонено.
Атрибуция строк говорит вам, кто что написал. Selvedge подсказывает вашему агенту, что не писать дальше: подходы, которые эта кодовая база уже пробовала, откатывала и почему. Это git blame для ИИ-агентов, для почему, а не для того, какая модель коснулась какой строки — фиксируется вживую, самим агентом, в момент изменения, так что никому ниже по потоку не приходится гадать.
Selvedge — это локальный MCP-сервер. ИИ-агенты для кодинга (Claude Code, Cursor, Copilot) вызывают его во время работы, чтобы логировать структурированные события изменений с обоснованием. Ваши данные остаются в SQLite-файле в папке .selvedge/ рядом с вашим кодом.
Локально-первый по умолчанию, командный сервер по выбору, ноль LLM всегда.
Шесть месяцев назад ваш ИИ-агент добавил колонку под названием user_tier_v2. Вы не знаете, зачем. git blame указывает на коммит от claude-code с сгенерированным сообщением «Обновить схему». Сессия, в которой было сделано изменение, давно исчезла — и промпт, который его породил, тоже.
С Selvedge вы вместо этого запускаете это:
$ selvedge blame user_tier_v2
user_tier_v2
Changed 2025-10-14 09:31:02
Agent claude-code
Commit 3e7a991
Reasoning User asked to add a grandfathering flag for legacy free-tier
users during the pricing migration. Stores the original tier
so we can backfill discounts without touching billing history.Это обоснование было зафиксировано агентом в момент — записано в Selvedge из того же контекста, который породил изменение. Не выведено из диффа задним числом второй LLM. Не сообщение коммита, набранное вручную.
Для кого Selvedge
У Selvedge две аудитории. Тот же инструмент, тот же pip install, тот же SQLite-файл в .selvedge/. Разный масштаб боли.
Команды, ведущие долгосрочные кодовые базы, написанные ИИ.
Когда проект достаточно велик, чтобы вы (или кто-то другой) снова коснулись его через шесть месяцев, двенадцать месяцев, три года — но большая его часть написана агентом, чей контекст испарился в день, когда каждый PR был отправлен. git blame говорит вам, что изменилось. Selvedge говорит вам почему — даже после того, как сессия агента, шаблон промпта, разработчик, который это запросил, и версия модели давно исчезли. Это исходный вариант использования: производственные кодовые базы, решения по схеме, миграции, изменения зависимостей, которым нужен аудиторский след, переживающий смену команды.
Соло-разработчики, использующие Claude Code в повседневных проектах.
Побочные проекты, сборки на выходных, небольшой внутренний инструмент, который вы продолжаете дорабатывать. Вам не нужен корпоративный контроль — вам просто нужно помнить, почему вы (или ваш агент) сделали то, что сделали вчера, на прошлой неделе, в прошлом спринте. Запустите selvedge init один раз. Добавьте четыре строки в ваш CLAUDE.md. С этого момента selvedge blame — это мышечная память — способ поговорить с собой прошлым, когда ваше прошлое «я» было LLM.
Если вы когда-либо возвращались к своему собственному проекту, созданному ИИ, и думали: «зачем это было нужно?», Selvedge — недостающий элемент.
Related MCP server: claude-engram
Проблема
Код, написанный человеком, повсюду просачивает намерения — сообщения коммитов, описания PR, инлайн-комментарии, тред в Slack, который предшествовал этому. Код, написанный ИИ, — нет. Агент имеет полную ясность, почему он принял каждое решение, но этот контекст живет в промпте и испаряется, когда разговор заканчивается.
Шесть месяцев спустя ваша команда отлаживает решение по схеме без какого-либо следа. git blame говорит вам что изменилось и когда. Он не может сказать вам почему.
Selvedge фиксирует «почему» — вживую, самим агентом, в момент внесения изменения. Дифф — работа git. «Почему» — работа Selvedge.
Что нового в v0.3.10
Память приходит к агенту, а хранилище получает свои регуляторы. Две темы, выпущенные вместе, потому что конфигурационная половина — это то, что остальному нужно было для чтения настроек.
Доставка. Selvedge уже блокировал повторные правки откаченных сущностей. Не хватало доставки, когда нечего вето. Два новых хука:
SessionStart внедряет компактный дайджест в начале сессии — решения, требующие пересмотра, сущности, которые были опробованы и откачены, недавние изменения.
PreCompact срабатывает непосредственно перед тем, как сжатие контекста уничтожит обоснование этой сессии, и называет отслеживаемые сущности, которые вы редактировали, но не логировали.
Оба молчат, когда им нечего сказать, ограничены по размеру, доступны только для чтения и шаблонизированы. Ни один не может ничего блокировать — PreCompact намеренно отказывается от вето, которое предлагает ему API хуков. Это ответ на измеренный режим отказа: две статьи 2026 года зафиксировали, что инструменты памяти с моделью «вытягивания» остаются полностью неиспользуемыми (ноль добровольных операций памяти за 114 ходов против предварительно заполненного хранилища), в то время как детерминированная инъекция срабатывала каждый раз.
selvedge export --format markdown отображает хранилище в виде обозримого дайджеста для коммита рядом с ним, так что зафиксированное намерение появляется в pull request, а не прячется внутри бинарника. Детерминированно — повторная генерация без новых событий даёт нулевой дифф.
Конфигурация. .selvedge/config.toml теперь первоклассный, с канонической цепочкой приоритетов, которую selvedge doctor выводит для каждой настройки. Он приносит:
selvedge prune --include-events— первый путь, который может удалить зафиксированные обоснования, поэтому он требует и подтверждения, иSELVEDGE_DESTRUCTIVE=1. Ни того, ни другого по отдельности недостаточно, потому что--yesв cron-записи обходит промпт, а shell-профиль обходит переменную окружения. Хранение событий по умолчанию — никогда.Ограничения размера событий (
diff_bytes,reasoning_bytes), которые усекают с шумом — маркер в тексте, предупреждение при записи, счётчик вselvedge stats.Предупреждения о форме секретов в
log_change, расширяемые черезredaction_patterns, плюс строкаdoctor, которая сканирует уже сохранённое. Предупреждать, но не отклонять.
Также: закрыто пять проблем из ревью. Путь разрешения в принудительном хуке стал на 40% быстрее (33.6 мс → 20.1 мс на вызов с гейтом), и SELVEDGE_HOOK_DISABLE=1 наконец-то делает короткое замыкание до импортов, которые, согласно документации, должен пропускать; log_change больше не отбрасывает revisit_after / constraint / stale_when при переименованиях и заменах; --json в CLI и MCP-инструменты теперь возвращают идентичные структуры; и Docker-образ больше не поставляет собственную базу данных мейнтейнера. Тесты 826 → 984.
Что нового в v0.3.9.3
Исправляет сломанную установку и проводит полный проход по качеству кода. mcp 2.0.0 (выпущен 2026-07-28) удалил mcp.server.fastmcp, а Selvedge объявил mcp>=1.0.0 без верхней границы — так что любой pip install selvedge после этой даты тянул 2.0.0, и selvedge-server падал при импорте. Этот релиз закрепляет зависимость. Если ваш сервер перестал запускаться, вот почему — обновитесь.
Он выходит вместе с ревью, которое провело девять независимых проходов по кодовой базе, а затем попыталось опровергнуть каждую находку, прежде чем действовать. Исправлено семнадцать подтверждённых дефектов. Те, которые вы бы действительно заметили:
Принудительный хук перестал блокировать то, что не должен. Чтение отслеживаемого файла —
cat,git diff,pytest,ruff check— было заблокировано, и исправление, которое вам советовало запустить сообщение об ошибке, блокировалось тем же гейтом, так что из CLI не было выхода. Ещё два пути питали те же ложные блокировки: закомментированная строка SQL считалась реальным удалением, а любое сообщение коммита, просто содержащее слово «revert», помечало каждый затронутый файл как откаченный.Поиск стал быстрым при масштабе. Основное чтение сущности сканировало каждую строку — измерено 7.4 мс → 0.35 мс при 100k событий, а хук занимал секунды на больших хранилищах.
selvedge setupбольше не может удалять части вашегоCLAUDE.md, прерванный бэкап больше не может уничтожить ваш последний хороший, а обновление при работающих двух процессах Selvedge больше не падает с ошибкой, похожей на повреждение базы данных.
Тесты выросли с 739 до 826. Никаких изменений схемы и изменений поверхности инструментов, так что это замена без изменений для всех на 0.3.9.x.
Где Selvedge вписывается
ИИ-агенты вызывают Selvedge во время работы. Selvedge фиксирует почему в долговечное, запрашиваемое хранилище и возвращает его наружу — как записи Agent Trace для читателей, работающих с разными инструментами, как метаданные наблюдаемости, связывающиеся со стек-трейсами Sentry/Datadog, и как артефакты соответствия для аудитов SOC 2 и EU AI Act.
Selvedge не заменяет git (построчное что/когда), инструменты ревью PR (качество на этапе ревью), наблюдаемость агентов (трассировки вызовов LLM) или общие ИИ-функции хостинга кода. Он находится между ними — слой, где происхождение является гражданином первого класса, на который ссылается всё остальное.
Как Selvedge сравнивается
Существует быстрорастущая категория «git blame для ИИ-агентов». Вот где Selvedge вписывается — и где он намеренно не вписывается.
Отклонённые пути | Источник обоснования | Гранулярность | Механизм | Группировка | Хранилище | |
Selvedge | Запрашиваемый — | Зафиксировано вживую, агентом в том же контексте, который произвёл изменение | Сущность — колонка БД, таблица, переменная окружения, зависимость, API-маршрут, функция | MCP-сервер — агент вызывает его по мере работы | Чейнджсеты — именованные слаги фич/задач, охватывающие множество сущностей | SQLite, ноль зависимостей |
Очищено — | Производное — статический анализ tree-sitter состояния кода, плюс заметки о решениях, привязанные к коммитам | Узел AST (18 языков + 12 IaC) | MCP-сервер — одноразовый индекс + сертификаты при коммите | Рёбра графа вызовов | Граф SQLite в | |
Нет | Выведено постфактум Claude Haiku из диффа в конце сессии | Строка | Хуки жизненного цикла Claude Code → локальный демон | Сессия/задача | JSONL на диске | |
Нет | Провенанс между агентами, подписанный ed25519 | Строка | Хуки редактора для каждого агента + git-хуки (подпись при коммите) | Нет | Подписанные трассы в git-ссылках | |
Нет — | Квитанции промптов, захваченные вживую на каждом ходе | Строка | Хуки жизненного цикла агента + git post-commit хук | Нет | Git-заметки + ветка сессий | |
Нет | Метаданные атрибуции | Строка | Контрольная точка, вызываемая агентом → Git-заметки при коммите | Нет | Git-заметки | |
Нет | Квитанции промптов — промпт, стоимость, инструменты; без указанного обоснования | Строка | Хуки жизненного цикла агента + post-commit хук | Нет | Git-заметки |
Почему «отклонённые пути» важны — тот случай, который нельзя скопировать. Дорогостоящий сбой — не забывание, зачем существует колонка. Это агент, уверенно переписывающий то, что команда уже отвергла по веской причине, через шесть месяцев после того, как все, кто знал об этом, покинули контекстное окно. Ни один из инструментов атрибуции строк выше вообще не показывает отклонённые пути, и это не пробел в функциональности, который они могут закрыть в релизе — хранилище, ориентированное на строки, не имеет понятия сущности, которая пережила цикл попытка → откат → повторная попытка. См. docs/demos/prior-attempts.md.
Почему детерминизм важен. Обоснование Selvedge — это собственное намерение агента, записанное из того же контекстного окна, которое произвело изменение. В пути хранения или извлечения нет ни одной модели, поэтому один и тот же запрос возвращает один и тот же ответ сегодня и через два года, независимо от версий моделей. Инструменты, которые выводят обоснование постфактум, запускают вторую LLM, которая никогда не видела исходный промпт: то, что она выдаёт, — это пересказ, и повторный запуск может дать разные категории для одного и того же изменения. Как выразился один комментатор на Hacker News о конкурирующем подходе, «grep не найдёт ваш коммит, потому что вы отклонили "oauth-library"… если только нет детерминированного принуждения» (0x457).
Сам по себе детерминизм больше не является отличием — OpenLore тоже изначально детерминирован и говорит об этом. Отличие создаёт добавляемое только свидетельство: обоснование, которое агент написал сам, хранится в хранилище, где отклонение — это запись первого класса, а не неактивный статус, который нужно вычистить.
Почему «уровень сущности» важен. Большинство инструментов атрибутируют строки. Selvedge атрибутирует то, что вы действительно ищете: users.email, env/STRIPE_SECRET_KEY, api/v1/checkout, deps/stripe. Первый вопрос после git blame обычно звучит как «какова история этой колонки», а не «какова история строк 40–48 файла users.py».
Почему «зафиксировано вживую» важно. Само по себе это не отличительная черта — каждый инструмент здесь заявляет о какой-то её разновидности — но это механизм, который делает обоснование заслуживающим доверия. Запись в момент изменения, из контекста, который его произвёл, — это причина, по которой в пути нет второй модели, которая могла бы галлюцинировать объяснение. Пустое поле reasoning само по себе — честный сигнал: у агента его не было.
Сравнение актуально на 2026-08-05; OpenLore на v2.1.8 / 265★, проверено по его исходникам. Исправления приветствуются в виде issue.
Почему «чейнджсеты» важны. Развёртывание биллинга Stripe затрагивает таблицу users, две новые переменные окружения, три новых API-маршрута, одну зависимость и четыре функции по всей кодовой базе. Пометьте каждое событие тегом changeset:add-stripe-billing — и вы сможете позже вытащить весь объём, даже если исходный PR был разбит на восемь меньших в течение месяца.
Selvedge ↔ Agent Trace. Agent Trace — это открытый проводной формат атрибуции ИИ-кода, опубликованный Cursor (RFC, январь 2026). Его исходный домен на GitHub перестал работать в августе 2026 года, и многопоставщичный импульс вокруг него угас, но спецификация и схема всё ещё доступны на agent-trace.dev, замороженные на v0.1.0. Начиная с v0.3.9, selvedge export --format agent-trace создаёт записи Agent Trace v0.1.0, а selvedge import --format agent-trace читает их обратно — переносимый, документированный формат обмена для атрибуции ИИ по файлам/строкам, с обоснованием и провенансом на уровне сущностей в метаданных dev.selvedge каждой записи. Сопоставление описано в docs/agent-trace-interop.md; Selvedge включает схему и не имеет зависимости от вышестоящего проекта во время выполнения.
Быстрый старт
Claude Code — установите плагин (рекомендуется)
Две команды внутри Claude Code. Без предварительного pip install — плагин сам запускает сервер через uvx (или pipx):
/plugin marketplace add masondelan/selvedge
/plugin install selvedge@selvedgeЭто вся поверхность для агента за один шаг:
MCP-сервер — 8 инструментов (
log_change,prior_attempts,blame,diff,history,changeset,search,stale_decisions);скилл, который говорит агенту, когда их вызывать — перед редактированием отслеживаемой сущности, после любого существенного изменения;
хук принуждения PreToolUse — изменения схемы/миграций блокируются, пока в этой сессии не был проверен
prior_attempts, с предыдущим обоснованием в сообщении блокировки;слэш-команды —
/selvedge:status,/selvedge:blame <entity>,/selvedge:history,/selvedge:prior-attempts <entity>.
Хранилище (.selvedge/selvedge.db) создаётся само при первом зарегистрированном изменении. Два дополнительных элемента остаются на стороне CLI: post-commit хук, который помечает каждое событие хешем коммита (selvedge install-hook), и — если вы хотите команду selvedge в собственном PATH вашей оболочки — pip install selvedge, который лаунчер затем предпочитает uvx для точной закреплённой версии.
Плагин или
selvedge setupдля Claude Code? Выберите одно. Оба подключают MCP-сервер; запуск обоих регистрирует его дважды. Плагин — более лёгкий путь и тот, который обновляет себя сам. Если вы на плагине и хотите только post-commit штамповку хеша коммита, запуститеselvedge install-hookотдельно.
Любой другой MCP-клиент — selvedge setup
Cursor, Copilot, Windsurf, Codex CLI, Gemini CLI и остальные:
pip install selvedge
cd your-project
selvedge setupВот и всё. selvedge setup — это интерактивный мастер: он определяет, какие ИИ-инструменты у вас есть (Claude Code, Cursor, Copilot), записывает запись MCP в конфиг каждого из них, помещает канонический блок инструкций для агента в файл промптов вашего проекта (CLAUDE.md / .cursorrules / copilot-instructions.md), устанавливает хук принуждения PreToolUse в .claude/settings.json (только Claude Code — блокирует изменения схемы/миграций, пока не проверен prior_attempts; --skip-enforcement-hook для отказа), запускает selvedge init и устанавливает post-commit хук. Рядом с каждым изменённым файлом перед любым изменением на диске создаётся .bak. Повторный запуск — это no-op.
Для CI-загрузки или devcontainer.json postCreateCommand:
selvedge setup --non-interactive --yesПроверьте подключение — откройте второй терминал в том же проекте:
selvedge watchВнесите любое изменение в вашем ИИ-инструменте — добавьте колонку, переименуйте функцию, добавьте переменную окружения. selvedge watch должен вывести новое событие в течение секунды после вызова агентом log_change. Если ничего не приходит, запустите selvedge doctor для проверки здоровья одной командой, которая скажет, какой шаг молча сломан.
Запросите свою историю:
selvedge status # recent activity + missing-commit count
selvedge diff users # all changes to the users table
selvedge diff users.email # changes to a specific column
selvedge blame payments.amount # what changed last and why
selvedge history --since 30d # last 30 days of changes
selvedge history --since 15m # last 15 minutes ('m' = minutes)
selvedge changeset add-stripe-billing # all events for a feature/task
selvedge search "stripe" # full-text search
selvedge stats # log_change coverage report (per-agent)
selvedge import migrations/ # backfill from migration files
selvedge export --format csv # dump history to CSVЕсли вы не хотите запускать мастер, вот четыре ручных шага, которые он автоматизирует:
1. Инициализация в вашем проекте
cd your-project
selvedge init2. Регистрация MCP-сервера
Selvedge — это стандартный stdio MCP-сервер, поэтому он работает с любым MCP-клиентом — Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI и другими. См. Работает с любым MCP-клиентом для точной конфигурации для каждого клиента. Для Claude Code:
claude mcp add selvedge -- selvedge-server3. Сообщите вашему агенту о его использовании
selvedge prompt --install CLAUDE.mdУкажите --install на тот файл промптов, который читает ваш клиент — сам блок идентичен для всех клиентов:
Клиент | Файл промпта |
Claude Code |
|
Codex CLI (и другие инструменты, понимающие |
|
Cursor |
|
Gemini CLI |
|
Это устанавливает канонический блок инструкций для агента, обрамлённый
сторожевыми маркерами
(<!-- selvedge:start --> / <!-- selvedge:end -->), чтобы будущие
вызовы --install обновляли только обрамлённую область, не затрагивая
ничего остального в файле. Или передайте через конвейер:
selvedge prompt | tee -a CLAUDE.mdПредпочитаете копировать и вставлять? Тот же блок доступен в один клик на сайте: selvedge.sh/prompt-block — с кнопкой копирования и пояснениями, что ваш агент делает с этим блоком.
4. Установите post-commit хук
selvedge install-hookЭто те же четыре шага, которые выполняет мастер.
Работает с любым MCP-клиентом
Selvedge — это стандартный stdio MCP-сервер: его команда запуска —
selvedge-server, она попадает в PATH при pip install selvedge. Любой
клиент с поддержкой MCP может его запустить. Выберите свой:
claude mcp add selvedge -- selvedge-serverИли закоммитьте проектный .mcp.json, чтобы вся команда получила его:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Документация: https://code.claude.com/docs/en/mcp
.cursor/mcp.json (проектный) или ~/.cursor/mcp.json (глобальный):
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Новая схема Cursor также принимает явный "type": "stdio"; форма только
с command тоже работает (Cursor определяет stdio по command).
Документация: https://cursor.com/docs/mcp
~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Windsurf перезагружает файл на лету — перезапуск не нужен. Кнопка Plugins → View raw config в приложении открывает именно тот файл, который читает Cascade. Документация: https://docs.windsurf.com/windsurf/cascade/mcp
~/.codex/config.toml:
[mcp_servers.selvedge]
command = "selvedge-server"Или выполните codex mcp add selvedge -- selvedge-server.
Документация: https://developers.openai.com/codex/config-reference
~/.gemini/settings.json (или .gemini/settings.json для проекта):
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Или выполните gemini mcp add -s user selvedge selvedge-server.
Документация: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
Большинство клиентов используют одну и ту же JSON-структуру — укажите свою:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Если selvedge-server не найден, используйте его абсолютный путь (which selvedge-server).
Как это работает
Selvedge работает как MCP-сервер. ИИ-агенты в таких инструментах, как Claude Code, вызывают инструменты Selvedge по мере работы — записывая структурированные события изменений в локальную базу данных SQLite.
Каждое событие фиксирует:
Что изменилось (путь сущности, тип изменения, diff)
Когда (временная метка)
Кто (агент, ID сессии)
Почему (обоснование — взятое из контекста агента в момент изменения)
Где (git-коммит, проект)
Diff — это работа git. Почему — это работа Selvedge.
Selvedge отслеживает собственную историю
Этот репозиторий использует Selvedge на себе: его .selvedge/selvedge.db
закоммичен, поэтому свежий клон поставляется с историей «почему» самого
Selvedge. Клонируйте и спросите, почему изменилась любая часть Selvedge:
git clone https://github.com/masondelan/selvedge
cd selvedge
selvedge status # recent changes to Selvedge itself
selvedge search "telemetry" # why the opt-in heartbeat shipped
selvedge blame selvedge/semantic.py # why semantic search was addedКаждое событие было записано агентами, которые создавали Selvedge — теми
же вызовами log_change, которые этот README просит вас делать в вашем
собственном проекте.
Соглашения о путях сущностей
users.email DB column (table.column)
users DB table
src/auth.py::login Function in a file (path::symbol)
src/auth.py File
api/v1/users API route
deps/stripe Dependency
env/STRIPE_SECRET_KEY Environment variableПрефиксные запросы работают везде: users возвращает users, users.email,
users.created_at и любую другую сущность в пространстве имён users..
Инструменты MCP
При подключении в качестве MCP-сервера Selvedge предоставляет:
Инструмент | Описание |
| Записывает событие изменения с сущностью, diff и обоснованием. |
| История для сущности или префикса сущности, каждая строка помечена |
| Последнее изменение + контекст для точной сущности, плюс производный |
| Отфильтрованная история по всем сущностям |
| Все события, сгруппированные под именованным slug фичи/задачи |
| Полнотекстовый поиск по всем событиям |
| Предыдущие попытки изменения сущности + предполагаемый результат (tried → reverted → re-opened) — вызывайте перед редактированием. Опциональный |
| Решения, требующие пересмотра: прошли |
Справочник CLI
selvedge init [--path PATH] Initialize in project
selvedge status Recent activity summary
selvedge diff ENTITY [--limit N] Change history for entity
selvedge blame ENTITY Most recent change + context
selvedge history [--since SINCE] Browse all history
[--entity ENTITY]
[--project PROJECT]
[--changeset CS]
[--summarize]
[--limit N]
selvedge changeset [CHANGESET_ID] Show events in a changeset
[--list] or list all changesets
[--project NAME]
[--since SINCE]
selvedge search QUERY [--limit N] Full-text search
selvedge prior-attempts ENTITY Prior attempts + inferred outcome,
[--description T] with the tried → reverted →
[--all] re-opened trail + status line
[--window 7d] (--all widens recall)
[--fuzzy TEXT] add semantic matches (needs the
semantic extra; substring fallback)
selvedge supersede ENTITY Re-open a reverted decision —
--reasoning TEXT append-only, links the prior
[--constraint TEXT] reverted event (or --supersedes ID)
[--stale-when TEXT]
[--supersedes ID]
selvedge index [--model NAME] Build/update the optional semantic
[--json] embeddings index (selvedge[semantic])
selvedge stale [--entity ENTITY] Decisions due for a revisit: past
[--project NAME] revisit_after + still in use, or
[--agent NAME] stale_when matched by a later change
[--json] ("review suggested")
selvedge stats [--since SINCE] Tool call coverage report (per-tool, per-agent)
selvedge doctor [--json] Health check: DB path, schema, hook, MCP wiring
selvedge install-hook [--path PATH] Install git post-commit hook
[--window MIN] (default 60 minutes)
selvedge backfill-commit --hash HASH Backfill git_commit on recent events
[--window MIN] (default 60 minutes)
selvedge import PATH Import migrations (SQL / Alembic) or
[--format auto|sql| an Agent Trace file (agent-trace)
alembic|agent-trace]
[--from-git] or walk git history for reverts:
[--since REF|DATE] revert-message commits + deletions
[--project NAME] become change_type="revert" events
[--dry-run] (idempotent on commit + entity)
selvedge export [--format json|csv| Export history (agent-trace =
markdown|agent-trace] Agent Trace v0.1.0 records;
markdown = reviewable digest)
[--since SINCE]
[--entity ENTITY]
[--ndjson] agent-trace: one record per line
[--collapse-by-session] agent-trace: merge a session into one
[--output FILE]
selvedge log ENTITY CHANGE_TYPE Manually log a change
[--diff TEXT] CHANGE_TYPE: add, remove, modify,
[--reasoning TEXT] rename, retype, create, delete,
[--agent NAME] index_add, index_remove, migrate,
[--commit HASH] revert, supersede
[--project NAME]
[--changeset CS]
[--revisit-after WHEN] ISO date or offset (e.g. 90d)
[--rename-from OLD] OLD path when CHANGE_TYPE is 'rename'
[--constraint TEXT] the principle behind the decision
[--stale-when TEXT] what would invalidate it
[--supersedes ID] with CHANGE_TYPE 'supersede'
selvedge migrate-paths Re-canonicalize stored entity paths
[--apply] (dry-run by default; --apply writes)
[--json]Все команды чтения поддерживают --json для машиночитаемого вывода.
Относительное время в --since:
15m→ последние 15 минут (m= минуты)24h→ последние 24 часа7d→ последние 7 дней5mo→ последние 5 месяцев (moилиmon= месяцы)1y→ последний год
Нераспознаваемые значения (например, --since yesterday) завершаются
понятной ошибкой, а не молча возвращают пустые результаты. Временные метки
ISO 8601 также принимаются и нормализуются к UTC.
Конфигурация
Метод | Формат | Пример |
Переменная окружения |
| Переопределение на сессию |
Инициализация проекта |
| Создаёт |
Глобальный запасной вариант |
| Используется, если проектная БД не найдена |
Globs для хука |
|
|
Настройки проекта |
| См. список ключей ниже — хранение, ограничения размера, шаблоны редактирования |
Глобальные настройки |
| Те же ключи; при совпадении выигрывает проектный файл |
Обход хука |
| Отключает принудительный хук PreToolUse для оболочки |
Semantic extra |
| Включает |
.selvedge/config.toml
Каждый ключ опционален; отсутствующий файл означает значения по умолчанию
ниже. Приоритет: флаг CLI → переменная окружения → проектный
.selvedge/config.toml → глобальный ~/.selvedge/config.toml → значение
по умолчанию. SELVEDGE_DB — единственное исключение: он всегда
выигрывает при определении базы данных, потому что файл конфигурации
находится через разрешение этого пути. selvedge doctor выводит
фактическое значение и шаг, который его определил, для каждой настройки.
retention_days_events = 0 # 0 = never delete events (the default)
retention_days_tool_calls = 90 # local telemetry retention
backup_keep_last = 7
diff_bytes = 65536 # truncate oversized diffs at log time
reasoning_bytes = 32768 # truncate oversized reasoning
db_size_warn_mb = 500 # doctor warns above this
stale_days = 0 # 0 = off
digest_max_bytes = 4096 # cap on the session-start digest
redaction_patterns = [] # extra secret shapes to warn about
[hook]
watch_globs = ["**/migrations/**", "db/**/*.sql"]У каждого ключа также есть переопределение через переменную окружения
(SELVEDGE_DIFF_BYTES, SELVEDGE_RETENTION_DAYS_EVENTS, …).
Просмотр зафиксированных намерений в pull request
.selvedge/selvedge.db — это файл SQLite, поэтому обоснования внутри него
не видны в diff. Экспортируйте Markdown-дайджест рядом с ним и закоммитьте
оба:
selvedge export --format markdown -o .selvedge/DECISIONS.md
git add .selvedge/Дайджест сгруппирован по сущностям, отменённые решения — первыми, и он детерминирован — повторная генерация без новых событий даёт нулевой diff, поэтому он остаётся читабельным, а не превращается в шум, который все привыкли пропускать. Якоря заголовков образуются из пути сущности, поэтому ссылки на них продолжают работать по мере роста. Перегенерируйте его в том же коммите, что и код, или из pre-commit хука.
Проверка покрытия
Интересно, как часто ваш агент на самом деле вызывает log_change? Два
способа проверить:
# Quick summary in the terminal
selvedge stats
# Cross-reference against git commits
python scripts/coverage_check.py --since 30dСкрипт покрытия сравнивает ваш git-журнал с событиями Selvedge и показывает,
какие коммиты имеют связанные события изменений. Низкое покрытие обычно
означает, что системный промпт нужно усилить — см. docs/fallbacks.md.
В CI (GitHub Action)
Та же проверка доступна как составное действие Selvedge Coverage Check, поэтому вы можете отслеживать покрытие агента при каждом пуше — и при желании завершать сборку ошибкой, когда оно падает:
# .github/workflows/selvedge-coverage.yml
name: Selvedge coverage
on: [push, pull_request]
jobs:
coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # full history so commits can be matched
- uses: masondelan/selvedge@v0.3.10 # pin to a release tag (or @main for latest)
with:
since: 30d
fail-under: "0.5" # optional: fail below 50% coverage; omit to report onlyОно записывает сводку покрытия в сводку задания и выставляет
coverage-ratio, covered и total как выходные шаги. Действие
сопоставляет вашу git-историю с журналом событий Selvedge, поэтому
раннеру нужен .selvedge/selvedge.db проекта (закоммитьте его или
восстановите перед этим шагом) и полная git-история (fetch-depth: 0).
Входные параметры: since, window, limit, fail-under,
selvedge-version, python-version, working-directory, db-path.
Участие в разработке
git clone https://github.com/masondelan/selvedge
cd selvedge
pip install -e ".[dev]"
pytestСм. CLAUDE.md для деталей архитектуры и дорожной карты фаз.
Лицензия
MIT — см. LICENSE.
Available Tools
8 toolsblameBlame an entityARead-onlyIdempotent
Most recent change to an entity — what changed, when, who, why.
Like git blame but for semantic entities (DB columns, functions, env
vars, dependencies) and AI agents. Also carries the derived decision
state: status (active / reverted / reopened) and
superseded_by (id of a later supersede overriding this change, or
""). If no history exists for the entity, returns {"error": "..."}
with protocol-level isError: false.
Inputs: entity_path (required). Returns: id, diff, agent, error, +17 more
changesetGet a changesetARead-onlyIdempotent
All events that share a changeset_id, oldest first.
Use to reconstruct the full scope of a feature or task across multiple
entities. If the changeset has no events, returns
[{"error": "..."}] so the caller can distinguish "unknown changeset"
from "empty history."
Inputs: changeset_id (required). Returns: result
diffDiff an entity's historyARead-onlyIdempotent
Get change history for a codebase entity, newest first.
Supports prefix matching — e.g. 'users' returns all events for the users
table and any users.* column. Each event carries a derived
superseded_by id ("" when nothing overrode it), so the
tried → reverted → re-opened trail reads straight off the history.
Inputs: entity_path (required), limit. Returns: result
historyBrowse historyARead-onlyIdempotent
Filtered change history across all entities, newest first.
Combine since, entity_path, project, and changeset_id to scope
the result. On unparseable since input the response is
[{"error": "..."}] so the caller sees the problem.
Inputs: limit, since, project, entity_path, +1 more. Returns: result
log_changeLog a code changeA
Record a change to a codebase entity.
Call this immediately after making any meaningful change. The event is
written to the local SQLite store and returned with its assigned id and
timestamp. If the reasoning fails the quality validator (empty, too
short, or a generic placeholder), or the entity_path doesn't match the
usual shape for its entity_type, the result includes a warnings
array — the event is still stored.
Renames: pass the new path in entity_path, set change_type="rename",
and pass the old path in rename_from. Selvedge then writes two events —
a rename on the old path and a create on the new path with
metadata.renamed_from set — so the entity's history follows it. Example:
log_change(
entity_path="src/auth/session.py::login", # new path
change_type="rename",
rename_from="src/auth.py::login", # old path
entity_type="function",
reasoning="Split auth.py into an auth/ package; login moved.",
)Rejections: when you consider an approach and decide against it WITHOUT
writing the change, record the verdict with change_type="reject" — the
abandoned path is a first-class event, and the next agent's
prior_attempts query finds it as a high-confidence ("exact") row
instead of re-deriving the dead end. Name what was rejected AND what was
chosen instead, and record the condition that would invalidate the
verdict. Example:
log_change(
entity_path="users.card_pan",
change_type="reject",
entity_type="column",
reasoning="Rejected storing raw card PANs on the user row — "
"went with provider tokens instead; PANs in our own "
"DB put us in PCI scope.",
stale_when="payment provider changed",
expires_when="entity:deps/stripe:changes",
)Use change_type="revert" for the sibling case — the change WAS written
and then rolled back (clearer than a plain remove).
Superseding a reverted decision: when a reverted change becomes correct
again (the constraint that killed it no longer holds), do NOT delete or
edit history — log with change_type="supersede" and the reason. The
new event links the prior revert (auto-resolved when supersedes is
empty) and every read surface then reports the trail
tried → reverted → re-opened. Never re-apply a reverted change without
superseding it first.
On validation failure (invalid change_type, missing entity_path,
rename_from set without change_type='rename', supersedes set without
change_type='supersede', a supersede with nothing to re-open, or an
expires_when outside the closed grammar) the result is
{"status": "error", "error": "..."} with no event written.
Inputs: change_type (required), entity_path (required), diff, agent, +12 more. Returns: id, error, status, warnings, +2 more
prior_attemptsPrior attempts on an entityARead-onlyIdempotent
Prior change attempts on an entity, each with an inferred outcome.
Call this BEFORE editing an entity. If the same change was tried before
and reverted, you get the prior reasoning and change_type plus an
inferred outcome — so you can change your plan instead of repeating a
rejected approach.
Each result is a change event plus the trail fields: outcome
("reverted" — a later removal on the path; "reopened" — closed but a
later supersede re-opened it; "rejected" — a standalone reject event
that closed no earlier attempt, surfaced as its own row whose reasoning
IS the record; "active"), confidence ("exact" — the attempt was closed
by an explicit revert/reject, or the row is a standalone rejection;
"proximity_high" / "proximity_low" — the add->remove window heuristic
for implicit removals), outcome_reasoning (WHY it was rejected),
superseded_by + supersede_reasoning (the re-open, when present), and
current_status — the entity's standing now. Treat "reverted" and
"rejected" as "don't repeat this without a supersede"; "reopened" means
the old verdict no longer stands. Together they read: tried → reverted →
re-opened. Templated and deterministic — no LLM call; pull-only.
Conservative by design — min_confidence defaults to "proximity_high",
so an empty list (nothing clearly tried-and-rejected) is the normal,
preferred answer over a speculative false positive; "exact" rows always
clear that default floor. Pass min_confidence="proximity_low" to widen
recall. Rows carry match_type ("exact" / "substring" / "fuzzy") and
similarity.
Inputs: fuzzy, limit, description, entity_path, +2 more. Returns: result
searchSearch eventsARead-onlyIdempotent
Full-text search across entity paths, diffs, reasoning, and agents.
Useful for questions like 'what changes were made for the billing feature?', 'which columns were added by cursor?', or 'show everything related to authentication'.
Inputs: query (required), limit. Returns: result
stale_decisionsStale decisions due for revisitARead-onlyIdempotent
Decisions due for a revisit — expired, past their date, or with a triggered stale condition.
Three deterministic rules. Expiry-based (flag="expired"): events whose
expires_when condition fired, evaluated from local state only —
date: against now, entity:PATH:changes against the event log,
library:NAME>=VERSION against installed dist metadata; the pattern
kind that fired is in expired_pattern. A library: condition whose
dependency isn't locally observable surfaces as flag="manual_review"
instead of a guess; manual:LABEL never auto-fires. Date-based
(flag="revisit_due"): events whose revisit_after has passed AND the
entity is still live (queried via blame/diff/prior_attempts after
the decision, or its changeset saw later activity) — pure age alone
never surfaces. Condition-based (flag="review_suggested"): events
whose stale_when text shares keywords with a LATER change event — the
named invalidation evidence may have happened. Surfacing only: nothing
is un-retired automatically; follow up with a supersede if the
condition really was triggered. A later supersede that re-opens the
candidate (explicit supersedes id, or the same id-less auto-link
prior_attempts uses) drops it from this list; a same-path sibling
the supersede did not target still surfaces.
Each result is the change event plus flag, revisit_due,
days_overdue, active_use_signals, matched_terms,
matched_event_id, expires_status, expired_pattern,
expires_detail, and a one-line stale_reason. Date-due rows first,
most-overdue leading; filter by entity_path, project, or agent.
Templated and deterministic; no LLM call, no network.
Inputs: agent, limit, project, entity_path. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have clearly distinct scopes: log_change is the only writer; diff is entity-scoped history, history is cross-entity, changeset groups by id, and search is full-text. The main ambiguity is diff vs. blame — blame returns only the newest event and adds a status field, but it is effectively the first row of diff, so an agent could reasonably pick either for 'what changed most recently.'
The naming mixes three conventions: git-style single-word verbs (diff, blame, search), bare nouns (history, changeset), and descriptive snake_case phrases (log_change, prior_attempts, stale_decisions). The styles are individually readable and the git-inspired cluster ties the read tools together, but there is no single predictable verb_noun pattern across the set.
Eight tools is well within the ideal 3-15 range and each tool earns its place in the change-logging domain: one writer, four retrieval views (per-entity, latest, global, changeset-grouped), one search, one pre-edit decision helper, and one maintenance/review tool. The count feels tightly scoped with no obvious redundancy or bloat.
The surface fully covers the domain's lifecycle: log_change handles all event types (including rename, reject, revert, and supersede), and the read side provides entity-scoped history, latest state, cross-entity filters, changeset reconstruction, full-text search, pre-edit attempt lookup, and stale-decision review. The append-only design intentionally omits update/delete, which the descriptions explicitly justify, so there are no real dead ends for the stated purpose.
Maintenance
Related MCP Connectors
One searchable history across every AI coding tool, with secret scanning and a shared task board.
Shared, scoped, reviewable team memory for AI coding agents.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThe shared AI context engine for git — save, search, and share the reasoning behind code changes. Captures the why behind every commit and slide on PRs for coding agents.MIT
- AlicenseBqualityBmaintenancePersistent memory and session intelligence for AI coding assistants. Auto-tracks mistakes, decisions, and context via hooks. Mines your full session history for patterns, predictions, and cross-session search.2116MIT
- AlicenseAqualityAmaintenanceLocal-first memory layer for AI coding agents — captures issues, attempts, fixes, and decisions, and warns at git commit before you repeat a mistake.19978 PyPI877MIT
- AlicenseNot gradedqualityDmaintenanceProvides a memory layer for AI coding agents with Git-powered version control, enabling automatic tracking of prompts, context, and code diffs.194MIT