Skip to main content
Glama
deenesjakoruzh
masondelan

Selvedge

by masondelan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
entity_pathYesExact entity path (no prefix matching). Examples: 'users.email', 'src/auth.py::login', 'env/STRIPE_SECRET_KEY'.

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
diffYes
agentYes
errorYes
statusYes
projectYes
metadataYes
reasoningYes
timestampYes
constraintYes
git_commitYes
session_idYes
stale_whenYes
supersedesYes
change_typeYes
entity_pathYes
entity_typeYes
changeset_idYes
expires_whenYes
revisit_afterYes
superseded_byYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate safe read-only idempotent operation. The description adds value by detailing return fields (status, superseded_by) and error handling behavior (returns error object with isError: false). No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short paragraphs, no fluff. The first sentence immediately states the core purpose. Every sentence adds necessary context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a single parameter, existing output schema, and comprehensive annotations, the description covers the tool's functionality, return data, and error case fully and clearly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter with 100% schema coverage. The description adds the constraint 'exact entity path (no prefix matching)' and provides examples, enhancing the schema's description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves the most recent change to an entity, likening it to git blame for semantic entities. It distinguishes from siblings like history or diff by focusing on the latest change and including decision state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool does and notes error behavior when no history exists. It lacks explicit guidance on when not to use or alternatives, but the purpose is clear enough for correct selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
changeset_idYesThe changeset identifier (the same slug or UUID passed to `log_change`'s changeset_id parameter). Examples: 'add-stripe-billing', 'fix-auth-redirect'.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive. Description adds ordering (oldest first) and specific error format, going beyond annotations without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each with clear purpose. No wasted words. First sentence states what the tool does, second gives usage context and error handling.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple single-parameter tool with full schema coverage and an output schema, the description sufficiently covers ordering, error condition, and intended use. No gaps identified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and fully describes the changeset_id parameter. Description adds no new parameter semantics beyond what the schema provides, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'All events that share a changeset_id, oldest first.' It specifies the resource (events) and ordering, distinguishing it from siblings like 'history' (likely broader) and 'search' (different target).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use to reconstruct the full scope of a feature or task across multiple entities,' providing clear context. Also describes error behavior for empty changesets. Lacks explicit when-not or alternative comparisons.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of events to return.
entity_pathYesEntity path, or a DOTTED prefix of one: 'users' also covers 'users.email'. Not a raw string prefix — 'src/' matches nothing, and 'src/auth.py' does not cover 'src/auth.py::login'.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context: newest-first ordering, dotted-prefix matching scope, and the derived `superseded_by` id with empty-string semantics for the latest event. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded: the first sentence gives the core purpose, and the second provides high-value examples of prefix matching and derived data. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema and safety annotations, the description sufficiently covers the essential behavior: ordering, prefix semantics, and the derived superseded_by trail. It does not discuss sibling-tool selection, but the core functionality is thoroughly described.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers both parameters fully (100% coverage), so the baseline is 3. The description restates prefix matching with an example but does not add new parameter-level semantics beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns change history for a codebase entity, newest first, and highlights unique behaviors like prefix matching and the derived `superseded_by` field. However, it does not explicitly differentiate from the similarly-named sibling tool `history`, so it stops short of full sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied: call this when you need a chronological change history for an entity, especially with prefix matching. But the description does not compare this tool to alternatives like `history` or `blame`, nor does it mention exclusions or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of results.
sinceNoTime window — ISO 8601 datetime OR relative shorthand: '15m' (last 15 minutes), '24h' (last 24 hours), '7d' (last 7 days), '5mo' (last 5 months), '1y' (last year). 'm' means minutes; 'mo' or 'mon' means months. Unparseable values produce an error rather than silently returning empty results. Empty = all time.
projectNoFilter to a specific project/repository.
entity_pathNoFilter to an entity, or a DOTTED prefix of one ('users' also covers 'users.email'). Not a raw string prefix.
changeset_idNoFilter to a specific changeset (feature/task group).

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnly=true, idempotent=true, and destructive=false, so safety is covered. The description goes beyond by disclosing the error behavior for unparseable 'since' input, returning a JSON error array instead of silently returning empty results. This is valuable behavioral context not in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first states purpose and ordering, the second gives usage guidance and error handling. It is front-loaded, with no wasted words, and every sentence contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and the description covers purpose, filtering, ordering, and error behavior, the tool is fully specified for an agent. The description is complete for this 5-parameter optional-input tool without needing to explain return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed descriptions for each parameter, so the baseline is 3. The description adds minor value by explicitly stating these parameters can be combined, but it does not explain syntax or semantics beyond what the schema already provides. No compensation needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Filtered change history across all entities, newest first.' It uses a specific verb ('browse' implicitly via 'history') and resource ('all entities'), and the 'newest first' ordering adds precision. This distinguishes it from siblings like log_change, diff, and search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance on how to combine filter parameters ('since', 'entity_path', 'project', 'changeset_id') to scope results. It does not explicitly mention when not to use this tool or name alternatives, but the usage context is clear enough for an agent to know when to invoke it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
diffNoThe actual change — SQL migration text, code diff, or a human-readable description of what changed. Optional but strongly recommended for non-trivial changes.
agentNoName/ID of the AI agent making the change (e.g. 'claude-code', 'cursor', 'copilot', 'human').
projectNoRepository or project name. Useful when one DB tracks multiple projects.
reasoningNoWhy the change was made. Include the user's original request, the problem being solved, or any context that won't be obvious from the diff alone. Good example: 'User asked to add 2FA — needs phone number to send SMS verification codes.' Avoid generic placeholders like 'user request' or 'done' — these are flagged by the quality validator and returned in `warnings`.
constraintNoOptional: the testable principle behind the decision, kept queryable (e.g. 'card data in our own DB = PCI scope').
git_commitNoThe git commit hash this change will land in. Can be backfilled later via `selvedge backfill-commit` or the post-commit hook.
session_idNoThe agent session or conversation ID, if available.
stale_whenNoOptional: what would invalidate this decision (e.g. 'payment provider changed'). stale_decisions matches it against later events and flags 'review suggested' — surfacing only.
supersedesNoId of the prior event this change overrides; only valid with change_type='supersede'. Empty auto-links the entity's most recent removal event (remove/delete/index_remove/revert/reject) — so after a standalone rejection it re-opens the rejection. Append-only — the old verdict is never edited, just derived as superseded.
change_typeYesWhat kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate, revert (tried and rolled back), reject (considered and decided against, without writing the change), supersede (re-open a reverted decision). Invalid values are rejected — pick the closest match.
entity_pathYesDot/slash-notation path to the entity. Required and non-empty. Examples: 'users.email' (DB column), 'users' (DB table), 'src/auth.py::login' (function in file), 'src/auth.py' (file), 'api/v1/users' (API route), 'deps/stripe' (dependency), 'env/STRIPE_SECRET_KEY' (env variable).
entity_typeNoCategory of entity. One of: column, table, file, function, class, endpoint, dependency, env_var, index, schema, config, other. Unknown values are coerced to 'other'.other
rename_fromNoThe entity's previous path, when this change is a rename. Set it together with change_type='rename' and put the NEW path in entity_path. Selvedge records the dual-event rename pattern: a 'rename' event on the old path and a 'create' event on the new path whose metadata.renamed_from points back to the old one, so blame/diff/prior_attempts on the new path still see the history. Leave empty for any non-rename change.
changeset_idNoOptional grouping ID for related changes that belong to the same feature or task. Use a short slug like 'add-stripe-billing'. All events sharing a changeset_id can be queried together via the `changeset` tool.
expires_whenNoOptional machine-checkable expiry condition for this decision. Closed grammar, validated at write time: 'library:NAME>=VERSION' (revisit when the named dependency reaches a version, e.g. 'library:django>=5.0'), 'entity:PATH:changes' (revisit when that entity next changes, e.g. 'entity:users.email:changes'), 'date:ISO' (revisit on a date, e.g. 'date:2027-01-01'), or 'manual:LABEL' (opaque label for human review; never auto-fires). `stale_decisions` evaluates these from local state — no network, no LLM — and flags 'expired' with the pattern that fired. Values outside the grammar are rejected.
revisit_afterNoOptional revisit date for an architectural decision (table, schema, dependency, config). An ISO date OR a relative offset from this event's timestamp (e.g. '90d', '6mo'). `stale_decisions` surfaces it once it passes, if the entity is still in active use. Leave empty otherwise.

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
errorYes
statusYes
warningsYes
timestampYes
supersedesYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations carry near-zero information (all false except openWorldHint), so the description carries the full burden. It comprehensively discloses: the warnings array on quality-validator failure, the exact error shape on validation failure, the dual-event rename behavior, supersede auto-linking, and append-only semantics. No contradiction with annotations (readOnlyHint=false correctly implies a write).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long, but every section earns its place given the complexity — headers ('Renames:', 'Rejections:', 'Superseding a reverted decision:') with code examples make it scannable. Slightly verbose in repeating rename semantics already in the schema's rename_from field, but organized enough that the density is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Comprehensive for a 16-parameter write tool with 5 complex change_type workflows. The description covers all change types, the validation grammar, failure/error shapes, examples for each major flow, and the output schema exists. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, giving a baseline of 3, but the description adds genuine orchestration semantics beyond the schema: rename's dual-event pattern (rename on old path + create on new path with metadata.renamed_from), the reject naming requirement ('name what was rejected AND what was chosen instead'), and that empty supersedes auto-links the most recent removal event. This is behavioral glue the schemas don't spell out.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'Record a change to a codebase entity' — and immediately distinguishes itself: call it after a meaningful change, while siblings diff/blame/history/prior_attempts are read surfaces. An agent can clearly separate it from the sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use for each change_type: 'Call this immediately after making any meaningful change,' with dedicated workflows for rename, reject, revert, and supersede. Names why reject is preferable to re-deriving dead ends ('the next agent's prior_attempts query finds it as a high-confidence row') and why supersede beats editing history. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
fuzzyNoOptional semantic query: also return attempts on entities whose prior reasoning is similar to this text — catches renames (payment_token vs card_token). Rows are labeled match_type='fuzzy' with a similarity score; without the selvedge[semantic] extra it falls back to substring matching and says so in a leading note row.
limitNoMaximum number of results.
descriptionNoFree-text description of what you're about to do, when you don't have an exact entity_path. Matched as a substring against prior reasoning, diffs, and entity paths. Provide this OR `entity_path` (entity_path takes precedence if both are given).
entity_pathNoThe entity you're about to change. Exact path with prefix matching — 'users' also covers 'users.email'. Examples: 'src/auth.py::login', 'users.email', 'env/STRIPE_SECRET_KEY'. Provide this OR `description`.
min_confidenceNoConfidence floor. 'proximity_high' (default) returns the high-signal rows: attempts closed by an explicit revert/reject (confidence 'exact' — always clears this floor, including standalone rejections) plus attempts reverted within the window. Pass 'proximity_low' to also see the noisy tail (still-active changes and far-apart reverts).proximity_high
window_minutesNoProximity window in minutes for the add->remove revert heuristic — the tiebreaker for IMPLICIT removal types only. An attempt removed within this many minutes is 'proximity_high'; beyond it, 'proximity_low'. Attempts closed by an explicit revert/reject are 'exact' regardless of the window. Default 10080 (7 days).

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description reinforces and expands this with 'Templated and deterministic — no LLM call; pull-only.' It discloses nuanced behaviors: conservative defaults, the meaning of outcome/confidence values, and that an empty list is the preferred normal answer. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but information-dense, with a sensible structure: core purpose, usage timing, outcome semantics, and confidence policy. Every sentence carries meaningful guidance, though some sections could be tightened. The front-loading is effective; the most important instruction appears early.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description covers purpose, usage timing, result semantics, confidence filtering, recall widening, and edge cases like standalone rejections and reopen events. The output schema exists and the description also explains return fields thoroughly. Nothing critical is missing for an agent to select and invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema itself documents all parameters. The description adds meaningful extra context, such as the default min_confidence behavior, how 'exact' rows clear the confidence floor, and the role of window_minutes as a tiebreaker for implicit removals. This goes beyond simple schema repetition, though it could have been slightly more parameter-by-parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's purpose: retrieving prior change attempts on an entity with inferred outcomes. It states a specific action context ('Call this BEFORE editing an entity') and distinguishes the data it returns. However, it does not explicitly differentiate itself from siblings like 'history' or 'changeset', so an agent must infer which tool covers which kind of history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs when to use the tool: before editing an entity, to avoid repeating a rejected approach. It also explains how to widen recall via min_confidence. However, it does not say when NOT to use it or name any alternative tool, so the usage guidance is strong on 'when' but missing exclusions and alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
agentNoOptional filter to the agent that logged the decision.
limitNoMaximum number of results.
projectNoOptional filter to a specific project/repository.
entity_pathNoOptional filter to a single entity or path prefix — 'users' also covers 'users.email'. Empty = every entity.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Even with annotations marking readOnly, deterministic, and non-destructive, the description adds substantial behavioral detail: no LLM call, no network, no automatic un-retiring, fallback to manual_review when dependency state is unobservable, and effects of later supersede events. This is far beyond what annotations alone convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than average, but the tool has complex deterministic rules and edge cases that warrant the detail. It is front-loaded with the core purpose and organized by flag type, followed by output fields, ordering, and guarantees. The output field enumeration is slightly redundant with the existing output schema, preventing a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with this complexity, the description is complete: it explains all three surfacing mechanisms, non-obvious edge cases like manual_review, output shape, ordering, filtering, and determinism guarantees. Combined with the rich annotations and output schema, an agent has everything needed to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline of 3 applies. The description mentions filtering by entity_path, project, or agent, which reinforces the schema but does not add much new semantic depth. It does not describe parameter formats beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Decisions due for a revisit,' then enumerates the three deterministic rules and their resulting flags. It clearly distinguishes this tool from siblings by emphasizing it is surfacing-only, deterministic, and local-state-based.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when results surface: expiry-based, date-based, and condition-based rules, with explicit caveats like 'pure age alone never surfaces' and 'manual:LABEL never auto-fires.' It does not explicitly name sibling alternatives for exclusion, but the behavioral specificity makes intended usage unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.3.14
    • Changedprior_attempts1 field changed
      • changedInput schema / properties / window_minutes / maximum
        Previous value: -1000New value: +10080
  2. 2 tool updates
    • Changedlog_change3 fields changed
      • changedInput schema / properties / change_type / description
        Previous value: -"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate, revert (tried and rolled back), supersede (re-open a reverted decision). Invalid values are rejected — pick the closest match."New value: +"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate, revert (tried and rolled back), reject (considered and decided against, without writing the change), supersede (re-open a reverted decision). Invalid values are rejected — pick the closest match."
      • addedInput schema / properties / expires_when
        Added value: +{
+  "default": "",
+  "description": "Optional machine-checkable expiry condition for this decision. Closed grammar, validated at write time: 'library:NAME>=VERSION' (revisit when the named dependency reaches a version, e.g. 'library:django>=5.0'), 'entity:PATH:changes' (revisit when that entity next changes, e.g. 'entity:users.email:changes'), 'date:ISO' (revisit on a date, e.g. 'date:2027-01-01'), or 'manual:LABEL' (opaque label for human review; never auto-fires). `stale_decisions` evaluates these from local state — no network, no LLM — and flags 'expired' with the pattern that fired. Values outside the grammar are rejected.",
+  "title": "Expires When",
+  "type": "string"
+}
      • changedInput schema / properties / supersedes / description
        Previous value: -"Id of the prior event this change overrides; only valid with change_type='supersede'. Empty auto-links the entity's most recent remove/delete. Append-only — the old verdict is never edited, just derived as superseded."New value: +"Id of the prior event this change overrides; only valid with change_type='supersede'. Empty auto-links the entity's most recent removal event (remove/delete/index_remove/revert/reject) — so after a standalone rejection it re-opens the rejection. Append-only — the old verdict is never edited, just derived as superseded."
    • Changedprior_attempts2 fields changed
      • changedInput schema / properties / min_confidence / description
        Previous value: -"Confidence floor. 'proximity_high' (default) returns only attempts that were clearly tried and then reverted within the window — the high-signal 'rejected before' cases. Pass 'proximity_low' to also see the noisy tail (still-active changes and far-apart reverts)."New value: +"Confidence floor. 'proximity_high' (default) returns the high-signal rows: attempts closed by an explicit revert/reject (confidence 'exact' — always clears this floor, including standalone rejections) plus attempts reverted within the window. Pass 'proximity_low' to also see the noisy tail (still-active changes and far-apart reverts)."
      • changedInput schema / properties / window_minutes / description
        Previous value: -"Proximity window in minutes for the add->remove revert heuristic. An attempt removed within this many minutes is 'proximity_high'; beyond it, 'proximity_low'. Default 10080 (7 days)."New value: +"Proximity window in minutes for the add->remove revert heuristic — the tiebreaker for IMPLICIT removal types only. An attempt removed within this many minutes is 'proximity_high'; beyond it, 'proximity_low'. Attempts closed by an explicit revert/reject are 'exact' regardless of the window. Default 10080 (7 days)."
  3. 5 tool updatesv0.3.11
    • Changeddiff2 fields changed
      • changedInput schema / properties / entity_path / description
        Previous value: -"Entity path or path prefix. Prefix matching is supported: 'users' returns history for the users table AND all its columns ('users.email', 'users.created_at', etc.). Use a more specific path to narrow the result."New value: +"Entity path, or a DOTTED prefix of one: 'users' also covers 'users.email'. Not a raw string prefix — 'src/' matches nothing, and 'src/auth.py' does not cover 'src/auth.py::login'."
      • addedInput schema / properties / limit / maximum
        Added value: +1000
    • Changedhistory2 fields changed
      • changedInput schema / properties / entity_path / description
        Previous value: -"Filter to a specific entity or path prefix."New value: +"Filter to an entity, or a DOTTED prefix of one ('users' also covers 'users.email'). Not a raw string prefix."
      • addedInput schema / properties / limit / maximum
        Added value: +1000
    • Changedprior_attempts2 fields changed
      • addedInput schema / properties / limit / maximum
        Added value: +1000
      • addedInput schema / properties / window_minutes / maximum
        Added value: +1000
    • Changedsearch1 field changed
      • addedInput schema / properties / limit / maximum
        Added value: +1000
    • Changedstale_decisions1 field changed
      • addedInput schema / properties / limit / maximum
        Added value: +1000
  4. 3 tool updatesv0.3.10
    • Changedblame6 fields changed
      • addedOutput schema / properties / constraint
        Added value: +{
+  "title": "Constraint",
+  "type": "string"
+}
      • addedOutput schema / properties / stale_when
        Added value: +{
+  "title": "Stale When",
+  "type": "string"
+}
      • addedOutput schema / properties / status
        Added value: +{
+  "title": "Status",
+  "type": "string"
+}
      • addedOutput schema / properties / superseded_by
        Added value: +{
+  "title": "Superseded By",
+  "type": "string"
+}
      • addedOutput schema / properties / supersedes
        Added value: +{
+  "title": "Supersedes",
+  "type": "string"
+}
      • changedOutput schema / required
        Previous value: -[
-  "id",
-  "timestamp",
-  "entity_type",
-  "entity_path",
-  "change_type",
-  "diff",
-  "reasoning",
-  "agent",
-  "session_id",
-  "git_commit",
-  "project",
-  "changeset_id",
-  "metadata",
-  "revisit_after",
-  "expires_when",
-  "error"
-]New value: +[
+  "id",
+  "timestamp",
+  "entity_type",
+  "entity_path",
+  "change_type",
+  "diff",
+  "reasoning",
+  "agent",
+  "session_id",
+  "git_commit",
+  "project",
+  "changeset_id",
+  "metadata",
+  "revisit_after",
+  "expires_when",
+  "supersedes",
+  "constraint",
+  "stale_when",
+  "superseded_by",
+  "status",
+  "error"
+]
    • Changedlog_change6 fields changed
      • changedInput schema / properties / change_type / description
        Previous value: -"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate. Invalid values are rejected — pick the closest match."New value: +"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate, revert (tried and rolled back), supersede (re-open a reverted decision). Invalid values are rejected — pick the closest match."
      • addedInput schema / properties / constraint
        Added value: +{
+  "default": "",
+  "description": "Optional: the testable principle behind the decision, kept queryable (e.g. 'card data in our own DB = PCI scope').",
+  "title": "Constraint",
+  "type": "string"
+}
      • addedInput schema / properties / stale_when
        Added value: +{
+  "default": "",
+  "description": "Optional: what would invalidate this decision (e.g. 'payment provider changed'). stale_decisions matches it against later events and flags 'review suggested' — surfacing only.",
+  "title": "Stale When",
+  "type": "string"
+}
      • addedInput schema / properties / supersedes
        Added value: +{
+  "default": "",
+  "description": "Id of the prior event this change overrides; only valid with change_type='supersede'. Empty auto-links the entity's most recent remove/delete. Append-only — the old verdict is never edited, just derived as superseded.",
+  "title": "Supersedes",
+  "type": "string"
+}
      • addedOutput schema / properties / supersedes
        Added value: +{
+  "title": "Supersedes",
+  "type": "string"
+}
      • changedOutput schema / required
        Previous value: -[
-  "id",
-  "timestamp",
-  "status",
-  "error",
-  "warnings"
-]New value: +[
+  "id",
+  "timestamp",
+  "status",
+  "error",
+  "warnings",
+  "supersedes"
+]
    • Changedprior_attempts1 field changed
      • addedInput schema / properties / fuzzy
        Added value: +{
+  "default": "",
+  "description": "Optional semantic query: also return attempts on entities whose prior reasoning is similar to this text — catches renames (payment_token vs card_token). Rows are labeled match_type='fuzzy' with a similarity score; without the selvedge[semantic] extra it falls back to substring matching and says so in a leading note row.",
+  "title": "Fuzzy",
+  "type": "string"
+}
  5. 4 tool updatesv0.3.8
    • Changedblame3 fields changed
      • addedOutput schema / properties / expires_when
        Added value: +{
+  "title": "Expires When",
+  "type": "string"
+}
      • addedOutput schema / properties / revisit_after
        Added value: +{
+  "title": "Revisit After",
+  "type": "string"
+}
      • changedOutput schema / required
        Previous value: -[
-  "id",
-  "timestamp",
-  "entity_type",
-  "entity_path",
-  "change_type",
-  "diff",
-  "reasoning",
-  "agent",
-  "session_id",
-  "git_commit",
-  "project",
-  "changeset_id",
-  "metadata",
-  "error"
-]New value: +[
+  "id",
+  "timestamp",
+  "entity_type",
+  "entity_path",
+  "change_type",
+  "diff",
+  "reasoning",
+  "agent",
+  "session_id",
+  "git_commit",
+  "project",
+  "changeset_id",
+  "metadata",
+  "revisit_after",
+  "expires_when",
+  "error"
+]
    • Changedlog_change2 fields changed
      • addedInput schema / properties / rename_from
        Added value: +{
+  "default": "",
+  "description": "The entity's previous path, when this change is a rename. Set it together with change_type='rename' and put the NEW path in entity_path. Selvedge records the dual-event rename pattern: a 'rename' event on the old path and a 'create' event on the new path whose metadata.renamed_from points back to the old one, so blame/diff/prior_attempts on the new path still see the history. Leave empty for any non-rename change.",
+  "title": "Rename From",
+  "type": "string"
+}
      • addedInput schema / properties / revisit_after
        Added value: +{
+  "default": "",
+  "description": "Optional revisit date for an architectural decision (table, schema, dependency, config). An ISO date OR a relative offset from this event's timestamp (e.g. '90d', '6mo'). `stale_decisions` surfaces it once it passes, if the entity is still in active use. Leave empty otherwise.",
+  "title": "Revisit After",
+  "type": "string"
+}
    • Addedprior_attempts
    • Addedstale_decisions
  6. 6 tool updatesv0.3.2
    • Changedblame2 fields changed
      • addedInput schema / properties / entity_path / description
        Added value: +"Exact entity path (no prefix matching). Examples: 'users.email', 'src/auth.py::login', 'env/STRIPE_SECRET_KEY'."
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "properties": {
+    "agent": {
+      "title": "Agent",
+      "type": "string"
+    },
+    "change_type": {
+      "title": "Change Type",
+      "type": "string"
+    },
+    "changeset_id": {
+      "title": "Changeset Id",
+      "type": "string"
+    },
+    "diff": {
+      "title": "Diff",
+      "type": "string"
+    },
+    "entity_path": {
+      "title": "Entity Path",
+      "type": "string"
+    },
+    "entity_type": {
+      "title": "Entity Type",
+      "type": "string"
+    },
+    "error": {
+      "title": "Error",
+      "type": "string"
+    },
+    "git_commit": {
+      "title": "Git Commit",
+      "type": "string"
+    },
+    "id": {
+      "title": "Id",
+      "type": "string"
+    },
+    "metadata": {
+      "additionalProperties": true,
+      "title": "Metadata",
+      "type": "object"
+    },
+    "project": {
+      "title": "Project",
+      "type": "string"
+    },
+    "reasoning": {
+      "title": "Reasoning",
+      "type": "string"
+    },
+    "session_id": {
+      "title": "Session Id",
+      "type": "string"
+    },
+    "timestamp": {
+      "title": "Timestamp",
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "timestamp",
+    "entity_type",
+    "entity_path",
+    "change_type",
+    "diff",
+    "reasoning",
+    "agent",
+    "session_id",
+    "git_commit",
+    "project",
+    "changeset_id",
+    "metadata",
+    "error"
+  ],
+  "title": "BlameResult",
+  "type": "object"
+}
    • Changedchangeset1 field changed
      • addedInput schema / properties / changeset_id / description
        Added value: +"The changeset identifier (the same slug or UUID passed to `log_change`'s changeset_id parameter). Examples: 'add-stripe-billing', 'fix-auth-redirect'."
    • Changeddiff3 fields changed
      • addedInput schema / properties / entity_path / description
        Added value: +"Entity path or path prefix. Prefix matching is supported: 'users' returns history for the users table AND all its columns ('users.email', 'users.created_at', etc.). Use a more specific path to narrow the result."
      • addedInput schema / properties / limit / description
        Added value: +"Maximum number of events to return."
      • addedInput schema / properties / limit / minimum
        Added value: +1
    • Changedhistory6 fields changed
      • addedInput schema / properties / changeset_id / description
        Added value: +"Filter to a specific changeset (feature/task group)."
      • addedInput schema / properties / entity_path / description
        Added value: +"Filter to a specific entity or path prefix."
      • addedInput schema / properties / limit / description
        Added value: +"Maximum number of results."
      • addedInput schema / properties / limit / minimum
        Added value: +1
      • addedInput schema / properties / project / description
        Added value: +"Filter to a specific project/repository."
      • addedInput schema / properties / since / description
        Added value: +"Time window — ISO 8601 datetime OR relative shorthand: '15m' (last 15 minutes), '24h' (last 24 hours), '7d' (last 7 days), '5mo' (last 5 months), '1y' (last year). 'm' means minutes; 'mo' or 'mon' means months. Unparseable values produce an error rather than silently returning empty results. Empty = all time."
    • Changedlog_change11 fields changed
      • addedInput schema / properties / agent / description
        Added value: +"Name/ID of the AI agent making the change (e.g. 'claude-code', 'cursor', 'copilot', 'human')."
      • addedInput schema / properties / change_type / description
        Added value: +"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate. Invalid values are rejected — pick the closest match."
      • addedInput schema / properties / changeset_id / description
        Added value: +"Optional grouping ID for related changes that belong to the same feature or task. Use a short slug like 'add-stripe-billing'. All events sharing a changeset_id can be queried together via the `changeset` tool."
      • addedInput schema / properties / diff / description
        Added value: +"The actual change — SQL migration text, code diff, or a human-readable description of what changed. Optional but strongly recommended for non-trivial changes."
      • addedInput schema / properties / entity_path / description
        Added value: +"Dot/slash-notation path to the entity. Required and non-empty. Examples: 'users.email' (DB column), 'users' (DB table), 'src/auth.py::login' (function in file), 'src/auth.py' (file), 'api/v1/users' (API route), 'deps/stripe' (dependency), 'env/STRIPE_SECRET_KEY' (env variable)."
      • addedInput schema / properties / entity_type / description
        Added value: +"Category of entity. One of: column, table, file, function, class, endpoint, dependency, env_var, index, schema, config, other. Unknown values are coerced to 'other'."
      • addedInput schema / properties / git_commit / description
        Added value: +"The git commit hash this change will land in. Can be backfilled later via `selvedge backfill-commit` or the post-commit hook."
      • addedInput schema / properties / project / description
        Added value: +"Repository or project name. Useful when one DB tracks multiple projects."
      • addedInput schema / properties / reasoning / description
        Added value: +"Why the change was made. Include the user's original request, the problem being solved, or any context that won't be obvious from the diff alone. Good example: 'User asked to add 2FA — needs phone number to send SMS verification codes.' Avoid generic placeholders like 'user request' or 'done' — these are flagged by the quality validator and returned in `warnings`."
      • addedInput schema / properties / session_id / description
        Added value: +"The agent session or conversation ID, if available."
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "properties": {
+    "error": {
+      "title": "Error",
+      "type": "string"
+    },
+    "id": {
+      "title": "Id",
+      "type": "string"
+    },
+    "status": {
+      "title": "Status",
+      "type": "string"
+    },
+    "timestamp": {
+      "title": "Timestamp",
+      "type": "string"
+    },
+    "warnings": {
+      "items": {
+        "type": "string"
+      },
+      "title": "Warnings",
+      "type": "array"
+    }
+  },
+  "required": [
+    "id",
+    "timestamp",
+    "status",
+    "error",
+    "warnings"
+  ],
+  "title": "LogChangeResult",
+  "type": "object"
+}
    • Changedsearch3 fields changed
      • addedInput schema / properties / limit / description
        Added value: +"Maximum number of results."
      • addedInput schema / properties / limit / minimum
        Added value: +1
      • addedInput schema / properties / query / description
        Added value: +"Search string (case-insensitive substring). Searches across entity_path, diff, reasoning, and agent fields. SQL LIKE wildcards (`_` and `%`) are escaped, so 'stripe_customer_id' matches the literal underscore rather than any single char."
  7. 6 tool updatesv0.3.1
    • First observedblame
    • First observedchangeset
    • First observeddiff
    • First observedhistory
    • First observedlog_change
    • First observedsearch
Deploy Server
Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

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
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Projectmem

    riponcm
    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.
    17
    850
    MIT