Skip to main content
Glama

Memoria a largo plazo para bases de código escritas por IA, incluyendo lo que ya se probó y se rechazó.

La atribución de líneas te dice quién escribió algo. Selvedge le dice a tu agente qué no escribir a continuación: los enfoques que esta base de código ya probó, revirtió y por qué. Es un git blame para agentes de IA, para el por qué en lugar de qué modelo tocó qué línea — capturado en vivo, por el agente, a medida que ocurre el cambio, para que nada posterior tenga que adivinarlo.

Selvedge es un servidor MCP local. Los agentes de codificación con IA (Claude Code, Cursor, Copilot) lo llaman mientras trabajan para registrar eventos de cambio estructurados con razonamiento. Tus datos permanecen en un archivo SQLite bajo .selvedge/ junto a tu código.

Local primero por defecto, servidor de equipo por elección, cero-LLM siempre.


Hace seis meses, tu agente de IA añadió una columna llamada user_tier_v2. No sabes por qué. git blame apunta a un commit de claude-code con un mensaje generado que dice "Update schema." La sesión que hizo el cambio ya no existe — y también el prompt que lo produjo.

Con Selvedge, ejecutas esto en su lugar:

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

Ese razonamiento fue capturado por el agente en el momento — escrito en Selvedge desde el mismo contexto que produjo el cambio. No inferido del diff posteriormente por un segundo LLM. No es un mensaje de commit escrito a mano.



Para quién es Selvedge

Selvedge tiene dos audiencias. Misma herramienta, mismo pip install, mismo archivo SQLite bajo .selvedge/. Diferente escala de dolor.

Equipos que mantienen bases de código a largo plazo escritas por IA. Cuando el proyecto es lo suficientemente grande como para que tú (u otra persona) lo toques de nuevo en seis meses, doce meses, tres años — pero la mayor parte fue escrita por un agente cuyo contexto se evaporó el día en que cada PR se envió. git blame te dice qué cambió. Selvedge te dice por qué — incluso después de que la sesión del agente, la plantilla de prompt, el desarrollador que lo pidió y la versión del modelo hayan desaparecido. Este es el caso de uso original: bases de código de producción, decisiones de esquema, migraciones, cambios de dependencias que necesitan un rastro de auditoría que sobreviva a la rotación.

Desarrolladores en solitario que usan Claude Code en proyectos cotidianos. Proyectos secundarios, builds de fin de semana, la pequeña herramienta interna que sigues tocando. No necesitas gobernanza empresarial — solo necesitas recordar por qué tú (o tu agente) hiciste lo que hiciste ayer, la semana pasada, el último sprint. Ejecuta selvedge init una vez. Añade cuatro líneas a tu CLAUDE.md. A partir de entonces, selvedge blame es memoria muscular — una forma de hablar con tu yo pasado cuando tu yo pasado era un LLM.

Si alguna vez has vuelto a tu propio proyecto construido con IA y has pensado "¿para qué era esto otra vez?", Selvedge es la pieza que falta.


Related MCP server: claude-engram

El problema

El código escrito por humanos filtra intención en todas partes: mensajes de commit, descripciones de PR, comentarios en línea, el hilo de Slack que lo precedió. El código escrito por IA no. El agente tiene una claridad perfecta sobre por qué tomó cada decisión, pero ese contexto vive en el prompt y se evapora cuando la conversación termina.

Seis meses después, tu equipo está depurando una decisión de esquema sin rastro. git blame te dice qué cambió y cuándo. No puede decirte por qué.

Selvedge captura el por qué — en vivo, por el propio agente, a medida que se hace el cambio. El diff es trabajo de git. El por qué es de Selvedge.


Novedades en v0.3.10

La memoria llega al agente, y el almacén recibe sus controles. Dos temas, enviados juntos porque la mitad de configuración es lo que el resto necesitaba para leer los ajustes.

Entrega. Selvedge ya bloqueaba re-ediciones de entidades revertidas. Lo que faltaba era la entrega cuando no hay nada que vetar. Dos nuevos hooks:

  • SessionStart inyecta un resumen compacto al comenzar una sesión — decisiones pendientes de revisión, entidades que se probaron y se revirtieron, cambios recientes.

  • PreCompact se dispara justo antes de que la compactación de contexto destruya el razonamiento de esta sesión y nombra las entidades vigiladas que editaste pero nunca registraste.

Ambos son silenciosos cuando no tienen nada que decir, con límite de tamaño, de solo lectura y con plantillas. Ninguno puede bloquear nada — PreCompact rechaza deliberadamente el veto que la API del hook le ofrece. Esta es la respuesta a un modo de fallo medido: dos artículos de 2026 registraron que las herramientas de memoria de modelo pull no se usaron en absoluto (cero operaciones de memoria voluntarias en 114 turnos contra un almacén pre-sembrado) mientras que la inyección determinista aterrizó cada vez.

selvedge export --format markdown renderiza el almacén como un resumen revisable para commitear junto a él, de modo que la intención capturada aparezca en una pull request en lugar de esconderse dentro de un binario. Determinista — regenerar sin nuevos eventos es un diff de cero líneas.

Configuración. .selvedge/config.toml ahora es de primera clase, con una cadena de precedencia canónica que selvedge doctor imprime por ajuste. Trae:

  • selvedge prune --include-events — el primer camino que puede eliminar razonamiento capturado, por lo que necesita ambas una confirmación y SELVEDGE_DESTRUCTIVE=1. Ninguna por sí sola es suficiente, porque --yes en una entrada de cron anula un prompt y un perfil de shell anula una variable de entorno. La retención de eventos por defecto es nunca.

  • Límites de tamaño de evento (diff_bytes, reasoning_bytes) que truncan de forma ruidosa — un marcador en el texto, una advertencia al escribir, un contador en selvedge stats.

  • Advertencias de forma de secreto en log_change, extensibles mediante redaction_patterns, más una fila de doctor que escanea lo que ya está almacenado. Advertir, nunca rechazar.

También: cinco problemas de revisión cerrados. La ruta de permitir del hook de cumplimiento es 40% más rápida (33.6 ms → 20.1 ms por llamada controlada) y SELVEDGE_HOOK_DISABLE=1 finalmente cortocircuita antes de las importaciones que estaba documentado que omitiera; log_change ya no descarta revisit_after / constraint / stale_when en renombres y supersedes; el --json de la CLI y las herramientas MCP ahora devuelven estructuras idénticas; y la imagen Docker ya no incluye la base de datos del mantenedor. Pruebas 826 → 984.


Novedades en v0.3.9.3

Corrige una instalación rota y trae una pasada completa de calidad de código. mcp 2.0.0 (lanzado el 2026-07-28) eliminó mcp.server.fastmcp, y Selvedge declaraba mcp>=1.0.0 sin límite superior — así que cualquier pip install selvedge después de esa fecha traía 2.0.0 y selvedge-server fallaba al importar. Esta versión fija la dependencia. Si tu servidor dejó de arrancar, esta es la razón — actualiza.

Se envía junto con una revisión que hizo nueve pasadas independientes sobre el código y luego intentó refutar cada hallazgo antes de actuar sobre él. Diecisiete defectos confirmados corregidos. Los que realmente habrías notado:

  • El hook de cumplimiento dejó de bloquear cosas que no debería. Leer un archivo rastreado — cat, git diff, pytest, ruff check — estaba bloqueado, y la corrección que el mensaje de error te decía que ejecutaras estaba bloqueada por la misma puerta, así que no había salida desde la CLI. Dos caminos más alimentaban los mismos falsos bloqueos: una línea de SQL comentada contaba como una eliminación real, y cualquier mensaje de commit que simplemente contuviera la palabra "revert" marcaba cada archivo que tocaba como revertido.

  • Las búsquedas se volvieron rápidas a escala. La lectura principal de entidades escaneaba cada fila — medido 7.4 ms → 0.35 ms con 100k eventos, y el hook había estado tardando segundos en almacenes grandes.

  • selvedge setup ya no puede eliminar partes de tu CLAUDE.md, una copia de seguridad interrumpida ya no puede destruir la última buena, y actualizar mientras dos procesos de Selvedge están en ejecución ya no falla con un error que parecía corrupción de base de datos.

Las pruebas pasaron de 739 a 826. Sin cambio de esquema y sin cambio en la superficie de herramientas, así que esto es drop-in para cualquiera en 0.3.9.x.


Dónde encaja Selvedge

Los agentes de IA llaman a Selvedge mientras trabajan. Selvedge captura el por qué en un almacén duradero y consultable y lo emite de vuelta — como registros de Agent Trace para lectores entre herramientas, como metadatos de observabilidad que se enlazan con trazas de pila de Sentry/Datadog, y como artefactos de cumplimiento para auditorías de SOC 2 y la Ley de IA de la UE.

Selvedge no reemplaza a git (qué/cuándo a nivel de línea), las herramientas de revisión de PR (calidad en el momento de la revisión), la observabilidad de agentes (trazas de llamadas de LLM) ni las funciones de IA de propósito general del host de código. Se sitúa entre ellos — la capa de procedencia como ciudadano de primera clase a la que todo lo demás hace referencia.


Cómo se compara Selvedge

Existe una categoría en rápido crecimiento de "git blame para agentes de IA". Aquí es donde encaja Selvedge — y donde deliberadamente no lo hace.

Rutas rechazadas

Fuente de razonamiento

Granularidad

Mecanismo

Agrupación

Almacenamiento

Selvedge

Consultable — prior_attempts devuelve intentado → revertido → reabierto

Capturado en vivo, por el agente en el mismo contexto que produjo el cambio

Entidad — columna de BD, tabla, variable de entorno, dependencia, ruta de API, función

Servidor MCP — el agente lo llama mientras trabaja

Changesets — slugs de características/tareas con nombre en muchas entidades

SQLite, cero dependencias

OpenLore

Purgado — rejected es un estado inactivo, eliminado del almacén consultable tras cada sincronización de decisiones (la anotación sobrevive en el markdown de especificación sincronizado)

Derivado — análisis estático tree-sitter del estado del código, más notas de decisión controladas por commits

Nodo de AST (18 lenguajes + 12 IaC)

Servidor MCP — indexación única + certificados en el commit

Aristas del grafo de llamadas

Grafo SQLite en .openlore/

AgentDiff (sunilmallya)

Ninguna

Inferido a posteriori por Claude Haiku a partir del diff al final de la sesión

Línea

Hooks del ciclo de vida de Claude Code → demonio local

Sesión/tarea

JSONL en disco

AgentDiff (codeprakhar25)

Ninguna

Procedencia entre agentes firmada con ed25519

Línea

Hooks de editor por agente + hooks de git (firma en el commit)

Ninguna

Trazas firmadas en refs de git

Origin

Ninguna — rework marca código de IA revertido a posteriori, sin justificación

Recibos de prompt, capturados en vivo por turno

Línea

Hooks del ciclo de vida del agente + hook post-commit de git

Ninguna

Notas de git + rama de sesiones

Git AI

Ninguna

Metadatos de atribución

Línea

Punto de control invocado por el agente → notas de git en el commit

Ninguna

Notas de git

BlamePrompt

Ninguna

Recibos de prompt — prompt, costo, herramientas; sin justificación declarada

Línea

Hooks del ciclo de vida del agente + hook post-commit

Ninguna

Notas de git

Por qué importan las "rutas rechazadas" — la que no se puede copiar. El fallo costoso no es olvidar por qué existe una columna. Es un agente reimplementando con confianza algo que el equipo ya descartó por una buena razón, seis meses después de que todos los que lo sabían salieran de la ventana de contexto. Ninguna de las herramientas de atribución por línea anteriores muestra rutas rechazadas, y no es una brecha de funcionalidad que puedan cerrar en una versión — un almacén orientado a líneas no tiene noción de una entidad que persistió a través de un ciclo intentar → revertir → reintentar. Ver docs/demos/prior-attempts.md.

Por qué importa el determinismo. El razonamiento de Selvedge es la intención propia del agente, escrita desde la misma ventana de contexto que produjo el cambio. No hay ningún modelo en la ruta de almacenamiento o recuperación, así que la misma consulta devuelve la misma respuesta hoy y dentro de dos años, a través de versiones de modelos. Las herramientas que infieren razonamiento a posteriori están ejecutando un segundo LLM que nunca vio el prompt original: lo que produce es una paráfrasis, y volver a ejecutarlo puede producir categorías diferentes para el mismo cambio. Como dijo un comentarista de Hacker News sobre un enfoque competidor, "grep no encontrará tu commit porque rechazaste 'oauth-library'… a menos que haya aplicación determinista" (0x457).

El determinismo por sí solo ya no es un diferenciador — OpenLore también es nativamente determinista, y lo dice. El compuesto que separa es testimonio de solo añadidura: razonamiento que el propio agente escribió, guardado en un almacén donde un rechazo es un registro de primera clase en lugar de un estado inactivo que se barre.

Por qué importa el "nivel de entidad". La mayoría de las herramientas atribuyen líneas. Selvedge atribuye cosas que realmente buscas: users.email, env/STRIPE_SECRET_KEY, api/v1/checkout, deps/stripe. La primera pregunta después de git blame suele ser "¿cuál es el historial de esta columna?", no "¿cuál es el historial de las líneas 40–48 de users.py?".

Por qué importa "capturado en vivo". No es un diferenciador por sí solo — todas las herramientas aquí reclaman alguna variante — pero es el mecanismo que hace confiable el razonamiento. Escribir en el momento del cambio, desde el contexto que lo produjo, es la razón por la que no hay un segundo modelo en la ruta que pueda alucinar una explicación. Un campo reasoning vacío es en sí mismo una señal honesta: el agente no tenía una.

Comparativa vigente al 2026-08-05; OpenLore en v2.1.8 / 265★, verificada contra su código fuente. Las correcciones son bienvenidas como issue.

Por qué importan los "changesets". Un despliegue de facturación de Stripe toca la tabla users, dos nuevas variables de entorno, tres nuevas rutas de API, una dependencia y cuatro funciones en todo el código base. Etiqueta cada evento con changeset:add-stripe-billing y podrás recuperar todo el alcance más tarde — incluso si el PR original se dividió en ocho más pequeños durante un mes.

Selvedge ↔ Agent Trace. Agent Trace es un formato abierto de cableado para atribución de código de IA publicado por Cursor (RFC, enero 2026). Su hogar original en GitHub devolvió 404 en agosto de 2026 y el impulso multivenedor detrás de él se ha desvanecido, pero la especificación y el esquema aún se resuelven en agent-trace.dev, congelados en v0.1.0. Desde v0.3.9, selvedge export --format agent-trace emite registros Agent Trace v0.1.0 y selvedge import --format agent-trace los lee de vuelta — un formato de intercambio portátil y documentado para atribución de IA por archivo/línea, con razonamiento y procedencia a nivel de entidad transportados en los metadatos dev.selvedge de cada registro. El mapeo está en docs/agent-trace-interop.md; Selvedge incluye el esquema y no tiene dependencia de tiempo de ejecución del proyecto ascendente.


Inicio rápido

Claude Code — instala el plugin (recomendado)

Dos comandos, dentro de Claude Code. Sin pip install previo — el plugin inicializa el servidor por sí mismo mediante uvx (o pipx):

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

Esa es toda la superficie orientada al agente en un solo paso:

  • el servidor MCP — 8 herramientas (log_change, prior_attempts, blame, diff, history, changeset, search, stale_decisions);

  • una skill que le dice al agente cuándo llamarlas — antes de editar una entidad rastreada, después de cualquier cambio sustancial;

  • el hook de aplicación PreToolUse — las ediciones de esquema/migración se bloquean hasta que prior_attempts se haya verificado en esta sesión, con el razonamiento previo en el mensaje de bloqueo;

  • comandos de barra — /selvedge:status, /selvedge:blame <entidad>, /selvedge:history, /selvedge:prior-attempts <entidad>.

El almacén (.selvedge/selvedge.db) se crea solo con el primer cambio registrado. Dos extras opcionales permanecen en el lado de la CLI: el hook post-commit que sella cada evento con su hash de commit (selvedge install-hook), y — si quieres el comando selvedge en el PATH de tu propia shell — pip install selvedge, que el lanzador prefiere sobre uvx para una versión exacta fijada.

¿Plugin o selvedge setup para Claude Code? Elige uno. Ambos conectan el servidor MCP; ejecutar ambos lo registra dos veces. El plugin es la ruta más ligera y la que se actualiza a sí misma. Si estás en el plugin y solo quieres el sellado de hash de commit post-commit, ejecuta selvedge install-hook por separado.

Cualquier otro cliente MCP — selvedge setup

Cursor, Copilot, Windsurf, Codex CLI, Gemini CLI y el resto:

pip install selvedge
cd your-project
selvedge setup

Eso es todo. selvedge setup es un asistente interactivo: detecta qué herramientas de IA tienes (Claude Code, Cursor, Copilot), escribe la entrada MCP en la configuración de cada una, coloca el bloque canónico de instrucciones del agente en el archivo de prompt de tu proyecto (CLAUDE.md / .cursorrules / copilot-instructions.md), instala el hook de aplicación PreToolUse en .claude/settings.json (solo Claude Code — bloquea ediciones de esquema/migración hasta que prior_attempts se haya verificado; --skip-enforcement-hook para optar por no participar), ejecuta selvedge init e instala el hook post-commit. Cada archivo modificado recibe un .bak escrito junto a él antes de que cualquier cambio llegue al disco. Volver a ejecutarlo es un no-op.

Para el arranque de CI o postCreateCommand de devcontainer.json:

selvedge setup --non-interactive --yes

Verifica la conexión — abre una segunda terminal en el mismo proyecto:

selvedge watch

Haz cualquier cambio en tu herramienta de IA — añade una columna, renombra una función, añade una variable de entorno. selvedge watch debería imprimir el nuevo evento en menos de un segundo después de que el agente llame a log_change. Si no llega nada, ejecuta selvedge doctor para una verificación de salud de un solo comando que te dice qué paso está fallando en silencio.

Consulta tu historial:

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

Si no quieres ejecutar el asistente, los cuatro pasos manuales que automatiza:

1. Inicializa en tu proyecto

cd your-project
selvedge init

2. Registra el servidor MCP

Selvedge es un servidor MCP estándar de stdio, así que funciona con cualquier cliente MCP — Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI y más. Ver Funciona con cualquier cliente MCP para la configuración exacta por cliente. Para Claude Code:

claude mcp add selvedge -- selvedge-server

3. Dile a tu agente que lo use

selvedge prompt --install CLAUDE.md

Apunta --install al archivo de prompt que lea tu cliente — el bloque en sí es idéntico entre clientes:

Cliente

Archivo de prompt

Claude Code

CLAUDE.md

Codex CLI (y otras herramientas compatibles con AGENTS.md)

AGENTS.md

Cursor

.cursor/rules/selvedge.md (o el heredado .cursorrules)

Gemini CLI

GEMINI.md

Esto instala el bloque canónico de instrucciones para el agente, delimitado por centinelas (<!-- selvedge:start --> / <!-- selvedge:end -->) para que futuras llamadas a --install actualicen la región delimitada sin alterar nada más del archivo. O canalízalo:

selvedge prompt | tee -a CLAUDE.md

¿Prefieres copiar y pegar? El mismo bloque está a un clic en el sitio web: selvedge.sh/prompt-block — con un botón de copiar y notas sobre qué hace tu agente con él.

4. Instala el hook post-commit

selvedge install-hook

Esos son los mismos cuatro pasos que ejecuta el asistente.


Funciona con cualquier cliente MCP

Selvedge es un servidor MCP estándar de stdio — su comando de lanzamiento es selvedge-server, que pip install selvedge coloca en tu PATH. Cualquier cliente compatible con MCP puede ejecutarlo. Elige el tuyo:

claude mcp add selvedge -- selvedge-server

O confirma un .mcp.json a nivel de proyecto para que todo tu equipo lo tenga:

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

Documentación: https://code.claude.com/docs/en/mcp

.cursor/mcp.json (proyecto) o ~/.cursor/mcp.json (global):

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

El esquema más reciente de Cursor también acepta un "type": "stdio" explícito; la forma solo con command también funciona (Cursor infiere stdio a partir de command). Documentación: https://cursor.com/docs/mcp

~/.codeium/windsurf/mcp_config.json:

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

Windsurf recarga el archivo en caliente — no hace falta reiniciar. El botón Plugins → View raw config de la aplicación abre el archivo exacto que lee Cascade. Documentación: https://docs.windsurf.com/windsurf/cascade/mcp

~/.codex/config.toml:

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

O ejecuta codex mcp add selvedge -- selvedge-server. Documentación: https://developers.openai.com/codex/config-reference

~/.gemini/settings.json (o .gemini/settings.json por proyecto):

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

O ejecuta gemini mcp add -s user selvedge selvedge-server. Documentación: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md

La mayoría de los clientes comparten la misma forma JSON — apunta el tuyo a:

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

Si no se encuentra selvedge-server, usa su ruta absoluta (which selvedge-server).


Cómo funciona

Selvedge se ejecuta como un servidor MCP. Los agentes de IA en herramientas como Claude Code llaman a las herramientas de Selvedge mientras trabajan — registrando eventos de cambio estructurados en una base de datos SQLite local.

Cada evento registra:

  • Qué cambió (ruta de la entidad, tipo de cambio, diff)

  • Cuándo (marca de tiempo)

  • Quién (agente, ID de sesión)

  • Por qué (razonamiento — capturado del contexto del agente en el momento)

  • Dónde (commit de git, proyecto)

El diff es trabajo de git. El por qué es de Selvedge.


Selvedge rastrea su propia historia

Este repositorio usa Selvedge en sí mismo: su .selvedge/selvedge.db está confirmado, así que un clon nuevo incluye el historial de porqués de Selvedge. Clónalo y pregunta por qué cambió cualquier parte de 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

Cada evento fue registrado por los agentes que construyeron Selvedge — las mismas llamadas a log_change que este README te pide hacer en tu propio proyecto.


Convenciones de rutas de entidad

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

Las consultas por prefijo funcionan en todas partes: users devuelve users, users.email, users.created_at y cualquier otra entidad bajo el espacio de nombres users..


Herramientas MCP

Cuando está conectado como servidor MCP, Selvedge expone:

Herramienta

Descripción

log_change

Registra un evento de cambio con entidad, diff y razonamiento. rename_from + change_type="rename" registra el patrón de doble evento de renombrado; change_type="supersede" reabre una decisión revertida (solo añade); constraint / stale_when opcionales mantienen consultable el principio de la decisión y su condición de invalidación

diff

Historial de una entidad o prefijo de entidad, cada fila anotada con superseded_by

blame

Cambio más reciente + contexto de una entidad exacta, más el status derivado de la decisión (activa / revertida / reabierta)

history

Historial filtrado en todas las entidades

changeset

Todos los eventos agrupados bajo un slug de característica/tarea con nombre

search

Búsqueda de texto completo en todos los eventos

prior_attempts

Intentos de cambio anteriores en una entidad + resultado inferido (intentado → revertido → reabierto) — llámalo antes de editar. La consulta fuzzy opcional añade registros semánticamente similares (necesita el extra semantic; si no, usa subcadena)

stale_decisions

Decisiones que requieren revisión: pasada su revisit_after y aún en uso activo (flag="revisit_due"), o cuya condición stale_when coincidió con un cambio posterior (flag="review_suggested")


Referencia de 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]

Todos los comandos de lectura admiten --json para salida legible por máquina.

Tiempo relativo en --since:

  • 15m → últimos 15 minutos (m = minutos)

  • 24h → últimas 24 horas

  • 7d → últimos 7 días

  • 5mo → últimos 5 meses (mo o mon = meses)

  • 1y → último año

Las entradas no analizables (p. ej. --since yesterday) salen con un error claro en lugar de devolver resultados vacíos en silencio. Las marcas de tiempo ISO 8601 también se aceptan y se normalizan a UTC.


Configuración

Método

Formato

Ejemplo

Variable de entorno

SELVEDGE_DB=/path/to/db

Anulación por sesión

Inicialización de proyecto

selvedge init

Crea .selvedge/selvedge.db en el directorio de trabajo actual

Respaldo global

~/.selvedge/selvedge.db

Se usa si no se encuentra una base de datos de proyecto

Globs de vigilancia del hook

.selvedge/config.toml

[hook]watch_globs = ["**/migrations/**", "db/**/*.sql"] — reemplaza los globs de esquema/migraciones predeterminados del hook de cumplimiento

Ajustes de proyecto

.selvedge/config.toml

Consulta la lista de claves a continuación — retención, límites de tamaño, patrones de redacción

Ajustes globales

~/.selvedge/config.toml

Mismas claves; el archivo de proyecto gana donde ambos definen una

Bypass del hook

SELVEDGE_HOOK_DISABLE=1

Desactiva el hook de cumplimiento PreToolUse para la shell

Extra semántico

pip install "selvedge[semantic]"

Habilita selvedge index + prior-attempts --fuzzy (embeddings locales model2vec, ~30 MB; el núcleo nunca depende de él)

.selvedge/config.toml

Toda clave es opcional; un archivo ausente significa los valores predeterminados de abajo. La precedencia es bandera de CLI → variable de entorno → .selvedge/config.toml del proyecto → ~/.selvedge/config.toml global → predeterminado. SELVEDGE_DB es la única excepción: siempre gana para la resolución de la base de datos, porque el archivo de configuración se encuentra mediante la resolución de esa ruta. selvedge doctor imprime el valor efectivo y el paso que lo produjo para cada ajuste.

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"]

Cada clave también tiene una anulación por entorno (SELVEDGE_DIFF_BYTES, SELVEDGE_RETENTION_DAYS_EVENTS, …).


Revisar la intención capturada en una solicitud de extracción

.selvedge/selvedge.db es un archivo SQLite, así que el razonamiento que contiene no aparece en un diff. Exporta un resumen en Markdown junto a él y confirma ambos:

selvedge export --format markdown -o .selvedge/DECISIONS.md
git add .selvedge/

El resumen se agrupa por entidad con las decisiones revertidas primero, y es determinista — regenerarlo sin eventos nuevos produce un diff de cero líneas, así que sigue siendo revisable en lugar de convertirse en ruido que todos aprenden a saltarse. Los anclajes de encabezado derivan de la ruta de la entidad, así que los enlaces hacia él siguen funcionando a medida que crece. Regenera el resumen en el mismo commit que el código, o desde un hook pre-commit.


Verificación de cobertura

¿Te preguntas con qué frecuencia tu agente realmente llama a log_change? Dos formas de comprobarlo:

# Quick summary in the terminal
selvedge stats

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

El script de cobertura compara tu historial de git con los eventos de Selvedge y muestra qué commits tienen eventos de cambio asociados. Una cobertura baja suele significar que el prompt del sistema necesita reforzarse — consulta docs/fallbacks.md para orientación.

En CI (GitHub Action)

La misma comprobación se distribuye como la acción compuesta Selvedge Coverage Check, así que puedes rastrear la cobertura del agente en cada push — y opcionalmente fallar la compilación cuando baje:

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

Escribe un resumen de cobertura en el resumen del trabajo y expone coverage-ratio, covered y total como salidas de paso. La acción cruza tu historial de git con el registro de eventos de Selvedge, así que el runner necesita el .selvedge/selvedge.db del proyecto (confírmalo, o restáuralo antes de este paso) y el historial completo de git (fetch-depth: 0). Entradas: since, window, limit, fail-under, selvedge-version, python-version, working-directory, db-path.


Contribuciones

git clone https://github.com/masondelan/selvedge
cd selvedge
pip install -e ".[dev]"
pytest

Consulta CLAUDE.md para detalles de arquitectura y la hoja de ruta de fases.


Licencia

MIT — ver 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