Skip to main content
Glama

Долговременная память для кодовых баз, написанных ИИ — включая то, что уже было опробовано и отклонено.

Атрибуция строк говорит вам, кто что написал. 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

Запрашиваемый — prior_attempts возвращает попытка → откат → повторное открытие

Зафиксировано вживую, агентом в том же контексте, который произвёл изменение

Сущность — колонка БД, таблица, переменная окружения, зависимость, API-маршрут, функция

MCP-сервер — агент вызывает его по мере работы

Чейнджсеты — именованные слаги фич/задач, охватывающие множество сущностей

SQLite, ноль зависимостей

OpenLore

Очищено — rejected — неактивный статус, удаляется из запрашиваемого хранилища после каждой синхронизации решений (аннотация сохраняется в синхронизированном markdown-спецификации)

Производное — статический анализ tree-sitter состояния кода, плюс заметки о решениях, привязанные к коммитам

Узел AST (18 языков + 12 IaC)

MCP-сервер — одноразовый индекс + сертификаты при коммите

Рёбра графа вызовов

Граф SQLite в .openlore/

AgentDiff (sunilmallya)

Нет

Выведено постфактум Claude Haiku из диффа в конце сессии

Строка

Хуки жизненного цикла Claude Code → локальный демон

Сессия/задача

JSONL на диске

AgentDiff (codeprakhar25)

Нет

Провенанс между агентами, подписанный ed25519

Строка

Хуки редактора для каждого агента + git-хуки (подпись при коммите)

Нет

Подписанные трассы в git-ссылках

Origin

Нет — rework помечает откаченный ИИ-код постфактум, без обоснования

Квитанции промптов, захваченные вживую на каждом ходе

Строка

Хуки жизненного цикла агента + git post-commit хук

Нет

Git-заметки + ветка сессий

Git AI

Нет

Метаданные атрибуции

Строка

Контрольная точка, вызываемая агентом → Git-заметки при коммите

Нет

Git-заметки

BlamePrompt

Нет

Квитанции промптов — промпт, стоимость, инструменты; без указанного обоснования

Строка

Хуки жизненного цикла агента + 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 init

2. Регистрация MCP-сервера

Selvedge — это стандартный stdio MCP-сервер, поэтому он работает с любым MCP-клиентом — Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI и другими. См. Работает с любым MCP-клиентом для точной конфигурации для каждого клиента. Для Claude Code:

claude mcp add selvedge -- selvedge-server

3. Сообщите вашему агенту о его использовании

selvedge prompt --install CLAUDE.md

Укажите --install на тот файл промптов, который читает ваш клиент — сам блок идентичен для всех клиентов:

Клиент

Файл промпта

Claude Code

CLAUDE.md

Codex CLI (и другие инструменты, понимающие AGENTS.md)

AGENTS.md

Cursor

.cursor/rules/selvedge.md (или устаревший .cursorrules)

Gemini CLI

GEMINI.md

Это устанавливает канонический блок инструкций для агента, обрамлённый сторожевыми маркерами (<!-- 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 предоставляет:

Инструмент

Описание

log_change

Записывает событие изменения с сущностью, diff и обоснованием. rename_from + change_type="rename" фиксирует двойное событие переименования; change_type="supersede" заново открывает отменённое решение (append-only); опциональные constraint / stale_when сохраняют принцип решения и условие его недействительности для запросов

diff

История для сущности или префикса сущности, каждая строка помечена superseded_by

blame

Последнее изменение + контекст для точной сущности, плюс производный status решения (active / reverted / reopened)

history

Отфильтрованная история по всем сущностям

changeset

Все события, сгруппированные под именованным slug фичи/задачи

search

Полнотекстовый поиск по всем событиям

prior_attempts

Предыдущие попытки изменения сущности + предполагаемый результат (tried → reverted → re-opened) — вызывайте перед редактированием. Опциональный fuzzy-запрос добавляет семантически похожие записи (требуется extra semantic; при отсутствии — подстрочный поиск)

stale_decisions

Решения, требующие пересмотра: прошли revisit_after и всё ещё активно используются (flag="revisit_due"), или чьё условие stale_when совпало с более поздним изменением (flag="review_suggested")


Справочник 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.


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

Метод

Формат

Пример

Переменная окружения

SELVEDGE_DB=/path/to/db

Переопределение на сессию

Инициализация проекта

selvedge init

Создаёт .selvedge/selvedge.db в текущей рабочей директории

Глобальный запасной вариант

~/.selvedge/selvedge.db

Используется, если проектная БД не найдена

Globs для хука

.selvedge/config.toml

[hook]watch_globs = ["**/migrations/**", "db/**/*.sql"] — заменяет globs схем/миграций по умолчанию в принудительном хуке

Настройки проекта

.selvedge/config.toml

См. список ключей ниже — хранение, ограничения размера, шаблоны редактирования

Глобальные настройки

~/.selvedge/config.toml

Те же ключи; при совпадении выигрывает проектный файл

Обход хука

SELVEDGE_HOOK_DISABLE=1

Отключает принудительный хук PreToolUse для оболочки

Semantic extra

pip install "selvedge[semantic]"

Включает selvedge index + prior-attempts --fuzzy (локальные эмбеддинги model2vec, ~30 МБ; ядро от них не зависит)

.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 tools
blameBlame an entityA
Read-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 changesetA
Read-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 historyA
Read-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 historyA
Read-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 entityA
Read-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

stale_decisionsStale decisions due for revisitA
Read-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

    A4.2/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.'

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Local-first memory layer for AI coding agents — captures issues, attempts, fixes, and decisions, and warns at git commit before you repeat a mistake.
      19
      978 PyPI
      877
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides a memory layer for AI coding agents with Git-powered version control, enabling automatic tracking of prompts, context, and code diffs.
      194
      MIT