El problema

Cómo se despliega esto. En qué orden. Qué se rompe si lo haces al revés. Por qué el puerto es el 3307 y no el 3306.

Nada de eso se puede derivar leyendo el código: se descubre ejecutando. Y sin embargo, cada vez que alguien pregunta, un agente lanza tres exploradores a inferirlo desde los archivos. Es caro, se repite en cada sesión, y de todas formas responde mal, porque está adivinando algo que sólo se supo haciéndolo.

Peor: cuando un humano sí sabe la respuesta —"si levantas la BD en el 3306 no funciona en nuestro servidor"— ese conocimiento no tiene dónde aterrizar. Vive en su cabeza, la IA no puede adivinarlo, y si esa persona se va, se va con ella.

La idea

El humano aporta la hipótesis que la IA no puede sacar del código: reglas de firewall, decisiones de hace tres años, cicatrices de incidentes. La IA aporta la verificación que el humano no tiene tiempo de hacer.

Por separado son intuición sin respaldo y ejecución sin dirección. Juntas son conocimiento.

Tekmerion cierra ese ciclo y deja el resultado versionado junto al código, con su procedencia: quién lo afirmó, con qué comando se comprobó, cuándo, y contra qué commit.

Tekmerion (τεκμήριον): en griego clásico, la prueba concluyente —la que decide—, por oposición al semeion, que es apenas un indicio.

Instalación

npm i -g tekmerion
cd tu-proyecto
tekmerion instalar

Abre tu agente en ese repo y listo. El proceso local se levanta solo, el conocimiento se inyecta al arrancar la sesión sin que ejecutes ningún comando, y la web queda en http://127.0.0.1:7317.

El proceso es de la máquina, no del repositorio: uno solo atiende todos los repos donde tengas sesiones abiertas, y la web los muestra en un selector. Cada uno conserva su propio ledger —el conocimiento no se mezcla ni se comparte entre proyectos—; lo único compartido es el proceso que los sirve. El segundo repositorio no levanta un proceso nuevo: se registra en el que ya está corriendo.

instalar detecta qué agentes usa el repositorio y se registra en todos: no tienes que saber con qué mecanismo se engancha cada uno. Si quieres decidirlo tú, --agente claude|opencode|todos.

La primera vez te va a pedir tu nombre de usuario —una sola vez por máquina, no por repositorio—. Sin eso no se registra ningún respaldo: en una pieza respaldada, la identidad es la evidencia. Puedes darlo por donde te quede más a mano, en la web o sin salir de la terminal:

tekmerion identidad tu-nombre

Lo tecleas tú, siempre. Ninguna herramienta acepta la identidad como parámetro: si un agente pudiera elegir a nombre de quién se respalda algo, la evidencia de una pieza respaldada sería inventada por el modelo.

Actualizar

npm update -g tekmerion

No tienes que recorrer tus repositorios después. Cuando una versión cambia lo que el instalador deja escrito —la dirección del servidor MCP, por ejemplo—, cada repositorio se corrige solo la próxima vez que abras una sesión ahí, y el aviso te dice qué cambió. Como tu agente ya leyó su configuración al arrancar, la corrección rige desde la sesión siguiente.

El proceso local que estaba corriendo se releva solo cuando arranca una versión más nueva, conservando los repositorios que atendía.

Para mirar el estado sin abrir una sesión:

tekmerion diagnostico   # compara CLI, proceso local y dirección escrita
tekmerion version

Instalar desde el repositorio (npm i -g github:NicBJ/tekmerion) sirve para trabajar sobre el código sin publicar, pero no es equivalente: compila en tu máquina y el número de versión no se mueve, así que nada puede distinguir un build de otro ni avisarte de que quedaste atrás.

Cómo funciona

Capturar. Mientras trabajas, sueltas al pasar algo como "ojo que el smoke falla si no levantaste el server antes". El agente lo reconoce como conocimiento operacional y te pide confirmación en una línea.

Comprobar. Antes de darlo por bueno, propone un check ejecutable derivado de tu afirmación. Tú lo apruebas, lo corriges, o lo descartas diciendo por qué. Si el check pasa, la pieza queda comprobada; si no, queda respaldada por tu palabra y a tu nombre.

Caducar. Cada pieza se ancla a los archivos que podrían invalidarla. Cuando esos archivos cambian, su evidencia caduca y se re-verifica sola en segundo plano. Los respaldos humanos vencen por tiempo, para que alguien los vuelva a mirar.

Inyectar. Al arrancar una sesión, el agente recibe un índice compacto de lo relevante —no el volcado completo, que reproduciría el problema que vinimos a resolver—. El cuerpo se pide bajo demanda por MCP.

Niveles de evidencia

Cada pieza lleva el suyo, y nunca se presenta como hecho lo que no se comprobó:

| Nivel | Qué significa | |---|---| | claimed | Alguien lo afirmó. No se comprobó ni lo respalda nadie. Nunca se presenta como hecho. | | vouched | No se pudo comprobar ejecutando, y una persona identificada respondió por ello. Utilizable, siempre distinguible de lo verificado. | | verified | Se comprobó ejecutando. Queda con el comando, el momento y el commit. | | refuted | Se comprobó falso. Se conserva: un callejón sin salida evita que otro lo recorra. | | stale | La evidencia caducó porque cambió el código anclado o venció el respaldo. |

Dos reglas que sostienen todo lo demás: nada llega a verified sin evidencia de ejecución —ni por antigüedad, ni por repetición, ni por juicio de un modelo— y el respaldo humano es el último recurso, nunca un atajo: si algo se puede comprobar, se comprueba y no se le pide la palabra a nadie.

Dónde vive

.tekmerion/
  ledger/       El conocimiento. Un evento por archivo, versionado.
  checks/       Los checks ejecutables, versionados.
  config.yaml   La política del equipo (plazo de vencimiento).
  index.db      Derivado. Gitignored, se reconstruye del ledger.

El ledger es append-only y se revisa en un PR como cualquier otro cambio. Un evento por archivo hace que dos ramas que capturan conocimiento en paralelo se mezclen sin conflicto, por construcción.

Ningún camino de escritura se salta la redacción de secretos: el ledger va a git, y de git un token no se borra.

Comandos

tekmerion instalar      Deja el repositorio listo (--agente claude|opencode|todos)
tekmerion arrancar      Levanta el proceso local (web + MCP + re-verificación).
                        Si ya hay uno, le registra este repositorio
tekmerion consolidar    Re-evalúa anclajes y busca contradicciones tras integrar una rama
tekmerion identidad     Quién responde por el conocimiento. Sin nombre, muestra la vigente
tekmerion diagnostico   Compara CLI, proceso local y dirección escrita en este repositorio
tekmerion desinstalar   Saca hook, skill, MCP y derivados
tekmerion version       La versión instalada

Qué no hace

No documenta la estructura del código. Dónde vive un símbolo, quién llama a qué, diagramas de arquitectura: eso se re-deriva leyendo, y lo hacen mejor otras herramientas. Tekmerion cubre sólo lo que no se puede re-derivar.

No rompe tu build. La re-verificación corre en segundo plano y no bloquea commits ni sesiones.

No resuelve contradicciones por su cuenta. Cuando dos piezas se contradicen, marca ambas, deja de presentarlas como hecho y escala a un humano con la evidencia de los dos lados.

No reemplaza la memoria de tu agente. Esa es un diario personal en una base local; esto es un manual de equipo versionado en el repo. Conviven bien.

Estado

Funciona y está en uso, pero es joven. Node ≥ 22.

Las superficies soportadas son Claude Code y OpenCode, y el conocimiento es el mismo en las dos: el ledger no se bifurca por cliente. Cambia sólo cómo se engancha cada una — Claude Code por hook de arranque, OpenCode por plugin, porque no tiene un hook que devuelva contexto. Un detalle de OpenCode: lee su configuración una sola vez al arrancar, así que después de instalar hay que reiniciarlo.

Si lo pruebas y algo no captura lo que debería, mira los huecos de conocimiento en la web local: ahí queda registrado lo que se preguntó y nadie pudo responder, que es la señal más útil para saber qué falta.

Licencia

MIT