selvedge.sh · PyPI · GitHub

Постоянная память решений для AI-агентов.

Сохраняйте, почему вы выбрали тот или иной подход, от чего отказались и что

могло бы изменить ваше решение. В следующей сессии разработки находите этот

контекст по ключу: функции, столбцу базы данных, маршруту API или зависимости.

Selvedge подходит всем, кто работает с совместимым агентом. Подключайтесь через

локальный MCP по stdio или используйте CLI из агента с доступом к командной

строке. При смене инструментов решения остаются в том же хранилище SQLite в

.selvedge/.

Учётная запись на хостинге не нужна; для основного хранения и поиска не

выполняются вызовы LLM.

Начало работы · Документация · Совместимость с агентами

uv tool install --upgrade selvedge
selvedge demo

Требуются uv и Python

3.10 или новее. В демонстрации используется временная база данных. Чтобы

подключить агента к реальному проекту, следуйте краткому руководству.

Кому подходит Selvedge

Разработчикам, работающим в одиночку, которые возвращаются к проекту, когда исходный диалог уже недоступен.
Командам, которым нужно передавать зафиксированные решения между сессиями и инструментами разработки.

Проблема

Код показывает, какой подход был выбран, но не всегда раскрывает ограничение,

которое повлияло на выбор, или альтернативу, от которой отказались. Selvedge

позволяет сохранять такие объяснения в проекте и предоставляет инструменты,

чтобы найти их перед следующими изменениями.

Вспомнить можно только решения, сохранённые явно. Сохранённое объяснение —

это описание, предоставленное человеком или агентом; Selvedge не проверяет его

достоверность и не гарантирует, что агент к нему обратится. Проверьте настройку,

сверив одно решение между двумя сессиями.

Что нового в v0.3.16

Используйте зафиксированные решения при проверке кода. Команда selvedge ledger

показывает, кто зафиксировал каждое решение и какая последующая запись явно его

пересмотрела. Необязательный Action для проверки PR добавляет причины и отвергнутые альтернативы для изменённых файлов на основе истории базовой ветки, одобренной для публикации. Сведения об авторстве указываются самими участниками; Action включается по желанию и никогда не выполняет код из PR-head.

Команда selvedge doctor --agent CLIENT проверяет конфигурацию хуков проекта

для всех шести целевых вариантов настройки и предлагает конкретные дальнейшие

шаги. Проверка конфигурации не подтверждает, что клиент активировал хуки.

В пилотном исследовании с внедрением записей проведено

24 синтетических испытания: ранее отвергнутые варианты, которые по-прежнему

оставались актуальными, повторно возникли в 4 из 6 подходящих запусков без памяти

и в 0 из 6 запусков с внедрёнными записями. В обоих условиях проверки на устаревшие

и не относящиеся к делу сведения пройдены. Две синтетические задачи не позволяют

сделать вывод об общей эффективности при разработке или о превосходстве над

поддерживаемыми в актуальном состоянии файлами; о прежнем равенстве результатов

в тесте с четырьмя вариантами по-прежнему сообщается. Новых зависимостей времени

выполнения, миграций и инструментов MCP нет.

Что нового в v0.3.15

Нативные адаптеры жизненного цикла для всех шести целевых вариантов настройки.

Теперь настройка предлагает хуки для Codex, Cursor, VS Code Copilot Local, Gemini CLI и

Windsurf/Cascade, а также для Claude Code. Контекст при запуске и проверки изменений

под наблюдением доступны там, где их поддерживает клиент; уведомления о сжатии

контекста носят рекомендательный характер. Windsurf поддерживает только проверки

изменений и команд. Существующая конфигурация сохраняется; для изменённых хуков

создаются резервные копии, а конфликты отображаются явно.

См. возможности, активацию и проверку. Новые

адаптеры проверены протокольными тестами и тестами подпроцессов; версии клиентов

и тестовые оболочки всё ещё имеют значение. Новых зависимостей, инструментов MCP,

миграций и телеметрии по умолчанию нет.

В пилотном исследовании конфигурации опубликованы

все 48 измеренных испытаний и контрольных проверок, включая неудачные результаты.

Исследование не доказывает преимущество перед файлом, который поддерживается

в актуальном состоянии, или перед размещением тех же сведений в запросе.

Какую задачу решает Selvedge

Сохраните решение. Вы или ваш агент для разработки фиксируете выбор, его

обоснование и отвергнутые варианты через MCP или CLI.

Храните его вместе с проектом. Selvedge сохраняет запись в локальной базе

SQLite и связывает её с функцией, столбцом, маршрутом или другой сущностью,

которой она касается.

Вспомните его перед следующими изменениями. В последующей сессии можно

обратиться к той же базе данных и проверить, по-прежнему ли действует прежнее

ограничение.

Git хранит историю кода; инструменты проверки оценивают изменения; средства

наблюдаемости показывают поведение во время выполнения. Selvedge добавляет

зафиксированные причины принятых решений.

Как это работает ·

Обмен данными в формате Agent Trace

Сравнение Selvedge с другими подходами

Выбирайте наиболее простой механизм памяти, который подходит вашему рабочему процессу:

Потребность	С чего начать	Что добавляет Selvedge
Постоянные правила проекта	Файлы инструкций для агента, которые поддерживаются в актуальном состоянии	Решения с возможностью поиска, связанные с конкретными сущностями
Проверенные архитектурные решения	Записи архитектурных решений (ADR)	Структурированные результаты, отвергнутые варианты и сигналы для пересмотра
Кто и когда изменил строку	История Git и инструменты атрибуции	Указанную причину и прежние подходы для конкретной сущности
Передача зафиксированных решений в другую сессию или клиент	Общая документация проекта	Поиск через MCP и CLI в одной локальной базе данных

Эти подходы можно использовать совместно. Ознакомьтесь со сравнением со ссылками на источники

и материалом «Инструкции, ADR и память решений»,

чтобы узнать критерии выбора и ограничения каждого подхода.

Почему важна история сущности. users.email, env/STRIPE_SECRET_KEY,

api/v1/checkout и deps/stripe остаются полезными объектами для поиска, даже если

связанный с ними код перемещается. Явные записи об отказе и замене решения позволяют

последующей сессии проверить, какие варианты уже рассматривались и действует ли

исходное ограничение по-прежнему.

Почему важно сохранять решения вовремя. Запись обоснования, пока контекст

ещё доступен, помогает сохранить сведения, которых нет в diff. Однако это

не гарантирует безошибочность обоснования. Поиск использует сохранённые записи;

агент для разработки по-прежнему отвечает за проверку применимости решения

и тестирование изменений.

Зачем нужны наборы изменений. Помечайте события общим набором изменений,

например add-stripe-billing, чтобы находить решения по задаче в таблицах,

переменных окружения, маршрутах и функциях.

Обмен данными в формате Agent Trace. Команды selvedge export --format agent-trace и

selvedge import --format agent-trace обмениваются записями в формате Agent Trace v0.1.0.

Обоснования и историю сущностей можно передавать в метаданных dev.selvedge.

В документе описаны соответствие форматов и ограничения;

Selvedge включает схему в свой состав и не зависит от исходного проекта во время

выполнения.

Краткое руководство

Подключите своего агента

Установите uv, затем выполните:

uv tool install --upgrade selvedge
selvedge demo
cd your-project
selvedge setup

Команда setup обнаружит поддерживаемые клиенты. Чтобы явно выбрать предустановку, укажите --agent и один из вариантов: claude-code, codex, copilot, cursor, gemini или windsurf.

Чтобы настроить несколько клиентов, укажите этот параметр несколько раз. Предустановки упрощают настройку, но не ограничивают совместимость. Для другого агента с поддержкой локального MCP через stdio выполните настройку вручную. Агенты, у которых есть доступ к оболочке, могут использовать CLI.

Предпочитаете pip? Выполните python -m pip install --upgrade selvedge в виртуальном окружении.

Исполняемый файл selvedge-server должен находиться в PATH редактора. Запустите редактор из этого окружения или укажите в конфигурации MCP абсолютный путь к исполняемому файлу.

Перед изменением файлов setup запросит подтверждение, создаст резервные копии существующего содержимого, установит MCP и инструкции для агента, инициализирует проект и предложит добавить Git post-commit-хук.

Файлы конфигурации и хуки жизненного цикла различаются в зависимости от клиента. В руководстве по совместимости описаны пути для предустановок, требования к активации и ограничения.

Перезапустите агента в проекте и, если потребуется, разрешите использовать инструменты Selvedge.

Учитывайте требования вашего клиента к доверию к проекту. Попросите агента:

Используй Selvedge, чтобы записать один реальный подход, который мы рассматривали и отклонили в этом проекте. Укажи сущность, причину отказа и то, что могло бы изменить наше решение. Не выдумывай решений. Покажи путь к сохранённой сущности и ID записи.

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

Доступ через MCP сам по себе не гарантирует автоматическую запись каждого решения: установленные инструкции помогают агенту пользоваться инструментом. Встроенные адаптеры жизненного цикла обрабатывают события поддерживаемых клиентов; доставка данных при запуске, проверка отслеживаемых изменений и уведомления при уплотнении контекста зависят от среды запуска. Прежде чем включать эти возможности, ознакомьтесь с руководством по хукам агента.

Для настройки в CI или в postCreateCommand файла devcontainer.json выполните:

selvedge setup --non-interactive --yes

Проверьте подключение — откройте второй терминал в том же проекте:

selvedge watch

Внесите любое изменение с помощью AI-инструмента: добавьте столбец, переименуйте функцию или добавьте переменную окружения. Команда 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                         # observed tool calls and explanation quality
selvedge import migrations/            # backfill from migration files
selvedge export --format csv           # dump history to CSV

Ручная установка — если вы предпочитаете настроить всё самостоятельно

Если вы не хотите запускать мастер настройки, выполните вручную четыре шага, которые он автоматизирует:

1. Инициализируйте проект

cd your-project
selvedge init

2. Зарегистрируйте MCP-сервер

Настройте клиент так, чтобы он запускал selvedge-server как локальный MCP-сервер через stdio.

Если исполняемый файл недоступен через PATH клиента, укажите абсолютный путь. Если клиент запускается вне каталога проекта, задайте SELVEDGE_DB, указав путь к базе данных проекта. Синтаксис конфигурации зависит от клиента; см. примеры подключения.

3. Укажите агенту, как пользоваться сервером

selvedge prompt --install path/to/agent-instructions.md

Замените path/to/agent-instructions.md на путь к фактическому файлу, который читает ваш клиент. Сам блок инструкций одинаков для всех клиентов:

Клиент	Файл с инструкциями
Claude Code	`CLAUDE.md`
Codex CLI (и другие инструменты, поддерживающие `AGENTS.md`)	`AGENTS.md`
Cursor	`.cursor/rules/selvedge.md` (или устаревший `.cursorrules`)
Gemini CLI	`GEMINI.md`

Команда добавит стандартный блок инструкций для агента, обрамлённый маркерами (/). При последующих вызовах --install содержимое между маркерами будет обновляться, а остальная часть файла останется нетронутой. Чтобы вывести блок для копирования, выполните:

selvedge prompt

Хотите скопировать и вставить блок вручную? На сайте он доступен в один клик:

selvedge.sh/prompt-block — там есть кнопка копирования и пояснения о том, как агент использует этот блок.

4. Установите post-commit-хук

selvedge install-hook

Это те же четыре шага, которые выполняет мастер настройки.

Совместимость с агентами

Для Selvedge не требуется конкретный бренд агента или поставщик модели. Интерфейс MCP работает через локальный stdio: совместимый клиент должен уметь запускать selvedge-server и вызывать его инструменты. Клиентам, поддерживающим только Remote HTTP, понадобится отдельный мост stdio; Selvedge не предоставляет размещённую конечную точку. Агент с доступом к оболочке может вместо этого использовать selvedge log и команды для чтения данных.

Ниже приведены примеры интеграции. Выберите вариант для своего клиента или настройте другой MCP-клиент с поддержкой stdio, используя его формат параметров:

Claude Code

Необязательный плагин Claude Code

Две команды в Claude Code. Предварительно устанавливать pip не нужно: плагин самостоятельно настроит сервер с помощью uvx (или pipx):

/plugin marketplace add masondelan/selvedge
/plugin install selvedge@selvedge

На этом настройка всех возможностей для агента завершена:

MCP-сервер — 8 инструментов (log_change, prior_attempts, blame,

diff, history, changeset, search, stale_decisions);

skill, который подсказывает агенту, когда вызывать инструменты: перед редактированием отслеживаемой сущности и после каждого существенного изменения;
хук принудительной проверки PreToolUse — редактирование схемы или миграций блокируется до тех пор, пока в текущем сеансе не будет проверен результат prior_attempts; сообщение о блокировке содержит предшествующие рассуждения;
slash-команды — /selvedge:status, /selvedge:blame ,

/selvedge:history, /selvedge:prior-attempts .

Хранилище (.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 вручную

claude mcp add selvedge -- selvedge-server

Или добавьте в репозиторий файл .mcp.json для проекта, чтобы настроить сервер для всей команды:

{
  "mcpServers": {
    "selvedge": { "command": "selvedge-server" }
  }
}

Документация: https://code.claude.com/docs/en/mcp

Cursor

Файл .cursor/mcp.json (для проекта) или ~/.cursor/mcp.json (глобальная настройка):

{
  "mcpServers": {
    "selvedge": { "command": "selvedge-server" }
  }
}

В новой схеме Cursor также можно явно указать "type": "stdio". Вариант только с command тоже работает: Cursor автоматически определяет stdio по полю command.

Документация: https://cursor.com/docs/mcp

Windsurf

Файл ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "selvedge": { "command": "selvedge-server" }
  }
}

Windsurf автоматически перечитывает файл, поэтому перезапуск не требуется. Кнопка Plugins → View raw config в приложении открывает именно тот файл, который использует Cascade.

Документация: https://docs.devin.ai/desktop/cascade/mcp

Codex CLI

Файл ~/.codex/config.toml:

[mcp_servers.selvedge]
command = "selvedge-server"

Или выполните команду codex mcp add selvedge -- selvedge-server.

Документация: https://learn.chatgpt.com/docs/config-file/config-reference

Gemini CLI

Файл ~/.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

Любой другой MCP-клиент

В большинстве клиентов используется такая же структура JSON. Укажите следующую конфигурацию:

{
  "mcpServers": {
    "selvedge": { "command": "selvedge-server" }
  }
}

Если selvedge-server не найден, укажите его абсолютный путь (which selvedge-server).

Как это работает

Selvedge запускается как локальный MCP-сервер или CLI. Совместимые агенты вызывают его инструменты во время работы и записывают структурированные события об изменениях в локальную базу данных SQLite.

Для каждого события фиксируются:

Что изменилось (путь к сущности, тип изменения, diff)
Когда (временная метка)
Кто (агент, ID сессии)
Почему (обоснование, извлечённое из контекста агента в момент изменения)
Где (коммит git, проект)

За diff отвечает git. За объяснение причин — Selvedge.

Selvedge отслеживает собственную историю

В этом репозитории Selvedge используется для отслеживания изменений в самом себе: файл .selvedge/selvedge.db включён в коммиты, поэтому в свежей копии репозитория уже есть история причин изменений 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"` повторно открывает отменённое решение, не изменяя и не удаляя прежние записи; необязательные параметры `constraint` и `stale_when` позволяют искать принцип, лежащий в основе решения, и условие его утраты актуальности
`diff`	Показывает историю сущности или префикса сущности; в каждой строке указано значение `superseded_by`
`blame`	Показывает последнее изменение точной сущности и его контекст, а также вычисленный статус решения `status` (active / reverted / reopened)
`history`	Показывает историю всех сущностей с учётом фильтров
`changeset`	Группирует все события по заданному имени функции или задачи
`search`	Выполняет полнотекстовый поиск по всем событиям
`prior_attempts`	Показывает предыдущие попытки изменить сущность и предполагаемый результат (tried → reverted → re-opened). Вызывайте этот инструмент перед редактированием. Необязательный параметр `fuzzy` добавляет семантически похожие записи (требуется дополнение `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 [--agent CLIENT] [--json] Health check; optional project agent-hook diagnostics
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`	Используется, если база данных проекта не найдена
Шаблоны отслеживания hook	`.selvedge/config.toml`	`[hook]` `watch_globs = ["/migrations/", "db/*/.sql"]` — заменяет шаблоны схем и миграций, заданные по умолчанию для enforcement hook
Параметры проекта	`.selvedge/config.toml`	См. список ключей ниже: срок хранения, ограничения размера и шаблоны для удаления конфиденциальных данных
Глобальные параметры	`~/.selvedge/config.toml`	Те же ключи; если ключ задан в обоих файлах, приоритет имеет файл проекта
Отключение hook	`SELVEDGE_HOOK_DISABLE=1`	Отключает enforcement hook PreToolUse для shell
Дополнение для семантического поиска	`pip install "selvedge[semantic]"`	Включает `selvedge index` и `prior-attempts --fuzzy` (локальные эмбеддинги model2vec, около 30 MB; основной пакет от них не зависит)

`.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/

Сводка сгруппирована по сущностям; сначала в ней идут отменённые решения. Она формируется детерминированно: если новых событий не появилось, повторная генерация не приводит к изменениям строк. Благодаря этому сводку удобно проверять — она не превращается в шум, который все привыкают игнорировать. Якоря заголовков строятся на основе путей сущностей, поэтому ссылки на разделы продолжают работать по мере роста файла. Обновляйте сводку в том же коммите, что и код, или с помощью pre-commit hook.

Проверка покрытия

Хотите узнать, как часто ваш агент вызывает log_change? Это можно проверить двумя способами:

# Quick summary in the terminal
selvedge stats

# Cross-reference against git commits
python scripts/coverage_check.py --since 30d

Скрипт проверки покрытия сопоставляет журнал git с событиями Selvedge и показывает, для каких коммитов зарегистрированы связанные события изменений. Низкое покрытие обычно означает, что системный prompt нужно усилить. Рекомендации см. в docs/fallbacks.md.

В CI (GitHub Action)

Та же проверка доступна в виде составного 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.16   # 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

Action добавляет сводку по покрытию в сводку задания и передаёт значения coverage-ratio, covered и total в качестве выходных данных шага. Action сопоставляет историю 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.

Контекст решений для проверяющих

В общем журнале и Action для проверки PR представлены зафиксированные причины, отклонённые варианты, сведения об авторах и сессиях, а также данные о целостности затронутых сущностей. В пилотном исследовании с сопоставленными инъекциями описан каждый эксперимент; выводы ограничены проверенными синтетическими задачами.