knoten

Cada idea es un archivo markdown en git, marcado como vivo, muerto o retractado. Si murió, el nodo contiene la razón, qué lo reabriría y el código para reproducirlo.

Cómo funciona

Un grafo es una carpeta. Un nodo es un archivo markdown: frontmatter para máquinas, prosa para humanos, código para reproducirlo.

---
id: hyp-self-consistency
type: hypothesis
status: dead
cause: weak_baseline
links:
  - {rel: kn:killedByGate, to: method-compute-matched-baseline}
repro:
  script: experiments/self_consistency.py
  model: Qwen3-8B-Instruct
  data: GSM8K test, 1319 questions
  cmd: python experiments/self_consistency.py --n 5 --temp 0.7
results:
  acc_greedy: 0.741
  acc_self_consistency: 0.792
  acc_compute_matched_baseline: 0.788
  tokens_per_question: 1420
  n_independent: 1319
---

# Self-consistency (sample 5, majority vote) beats greedy decoding

## Verdict: DEAD
Sampling 5 chains and taking the majority scored 79.2% vs 74.1% greedy. +5.1 points.
It looked like a free win.

## Why it died
It is not free. It costs **5x the tokens**, and given the same budget a longer-CoT
baseline reaches **78.8%**. The entire gain was compute, not method.

```python
# reproduce the kill:
python experiments/self_consistency.py --n 5 --compare compute_matched
```

## What would reopen this
A task where the majority-vote *aggregation* does real work, i.e. where the gain
survives a compute-matched baseline. Plausible for code execution or theorem proving.
GSM8K is not that task.

Tres meses después, cuando alguien vuelva a proponer autocoherencia:

$ knoten query "self-consistency"

  [✗ DEAD] hyp-self-consistency
      killed by : method-compute-matched-baseline
      reopen if : A task where the majority-vote aggregation does real work, i.e.
                  where the gain survives a compute-matched baseline…

Related MCP server: hive-memory

Úsalo

pip install -e .                  # the CLI is the agent surface; add ".[mcp]" only for shell-less clients

knoten init my-topic              # a new graph (it's a folder)

# deciding what to do
knoten frontier                   # what should I work on next?
knoten index                      # the whole graph, one line per node
knoten index --tag decoding       # ...narrowed to one corner of it
knoten index --since 2026-08-01   # ...or to what moved this month
knoten query <term>               # has this been tried, by keyword?
knoten show <node>                # edges, results, attachments
knoten gates                      # what must a claim survive here?

# recording what happened
knoten new hypothesis hyp-idea    # scaffold a node with whatever the rules demand
knoten commit <node> --frontmatter <f> --body <f>   # file a claim, gate-checked before it touches disk
knoten update <node> --status dead --append <f>     # move a node through its lifecycle, append to it
knoten attach <node> <file>...    # attach a script, plot or notebook
knoten detach <node> <file>

# keeping it honest
knoten validate                   # enforce this graph's own rules
knoten hook                       # make `git commit` refuse a broken graph
knoten path A B                   # how did we get from A to B?

Todos los comandos de lectura anteriores también aceptan --json; la prosa es el valor predeterminado porque es más barata de leer (ver "Para agentes de codificación" más abajo), --json está ahí para scripts y datos anidados.

Cada grafo declara sus propias reglas en graph.yaml. knoten no sabe nada sobre tu campo. Hace cumplir lo que tú dijiste que importa. El grafo de ejemplo exige que cada afirmación reporte tokens_per_question y que se base en al menos 30 preguntas independientes; un tema diferente exigiría algo completamente distinto.

rules:
  - id: underpowered
    when_type: hypothesis
    require_result_min: {n_independent: 30}
    message: A result on fewer than 30 independent questions is noise, not evidence.

  - id: deaths-must-name-a-cause
    when_status: dead
    require_field_one_of:
      cause: [no_signal, cost_hurdle, weak_baseline, underpowered, crowding_decay]
    message: A cause of death you cannot filter on is a story, not an index.

Eso último es lo que hace que un callejón sin salida sea reutilizable. Una vez que la causa es un campo en lugar de una oración, la pregunta que realmente haces seis meses después es una consulta:

knoten index --where cause=weak_baseline    # we have a stronger baseline now — what reopens?

Tu grafo también declara su propio vocabulario, y eso también se hace cumplir:

node_types: [hypothesis, experiment, finding, method, source]
statuses:   [open, alive, dead, retracted, superseded, active]
tags:       [decoding, reasoning, prompting, evaluation, gate]

type: hypthesis es un error tipográfico, no un nuevo tipo. status: ded es peor que estar mal — haría que la afirmación se eliminara silenciosamente de toda consulta, que es exactamente el tipo de podredumbre silenciosa que esta herramienta existe para prevenir. Ambos son ahora infracciones. También lo es tags: [decodng]: las etiquetas son el eje sobre el que filtras un grafo grande, así que una etiqueta mal escrita deja el nodo en el grafo pero fuera de toda vista del mismo. No declares tags: y el etiquetado sigue siendo libre — el núcleo no inventa vocabulario, solo hace cumplir el que declaraste.

Una clave de regla — o una clave de configuración — que knoten no reconoce es un error grave, no un encogimiento de hombros. La configuración que no hace cumplir nada es decoración, y una regla que no hace cumplir nada es peor que ninguna regla, porque crees que estás cubierto.

knoten new lee esas reglas y pre-rellena exactamente lo que exigen — nada en el andamio es opinión de knoten, es la de tu grafo. Los valores son TODO a propósito, así que new + validate es una lista de verificación en lugar de un juego de adivinanzas:

$ knoten new hypothesis hyp-my-idea --status dead

  + nodes/hyp-my-idea.md  (hypothesis, dead)
    pre-filled what THIS graph's rules require:
      ## Why it died, ## What would reopen this, tokens_per_question, n_independent

El fallo que esta herramienta existe para prevenir fue causado por fricción, así que la ruta de escritura es donde la fricción duele más. Escribe prosa, no texto repetitivo que tuviste que ser rechazado para descubrir.

La puerta es un hook de git

knoten hook     # after `git init`

git commit ahora ejecuta knoten validate y rechaza un grafo que rompe sus propias reglas:

$ git commit -m "self-consistency is a win"

  ✗ hyp-self-consistency
      [live-claims-must-cite-their-gates] An unchallenged claim is not a finding, it is a hope.

  1 violation(s) — commit REJECTED

Una regla que solo se activa cuando recuerdas preguntar es la regla que dejó pudrirse el último intento. Ponlo en algún lugar por donde no puedas pasar de largo. (git commit --no-verify lo evita — deberías tener una razón.)

Adjunta el código y los gráficos

Un nodo no es solo una afirmación. Lleva lo que necesitas para volver a ejecutarlo.

knoten attach hyp-self-consistency experiments/self_consistency.py accuracy_vs_budget.png

Los archivos se copian a attachments/<node-id>/, se listan en el frontmatter, y las imágenes se incrustan en el cuerpo del nodo para que se rendericen en GitHub:

attachments/hyp-self-consistency/
  self_consistency.py        the script that KILLED it
  accuracy_vs_budget.png     the plot that shows why

knoten validate entonces falla si un nodo lista un adjunto que no está ahí. Una reproducción rota es un nodo roto.

knoten show hyp-self-consistency     # edges, results, attachments
knoten detach hyp-self-consistency accuracy_vs_budget.png

¿Y ahora qué?

Un grafo que solo responde "¿se ha intentado esto?" es un archivador. frontier es la única pantalla que responde "¿qué sigue?":

$ knoten frontier

  OPEN — started, never settled
    hyp-batch-schedule        Does the LR schedule interact with batch size?

  REOPENABLE — died, but said what would bring them back
    hyp-self-consistency      Self-consistency (sample 5, majority vote) beats greedy
      reopen if : A task where the majority-vote aggregation is doing real work…

  UNTESTED GATES — no claim has been through them
    method-holdout-period     Gate: hold out the last 20%

Un callejón sin salida con una oferta vigente es un experimento más barato que una idea nueva, porque el diseño ya está escrito. Para eso sirve ## ¿Qué lo reabriría?: sin un lugar donde mostrarlo, actuar sobre uno implica releer cada autopsia en el grafo.

knoten no decide si una condición se cumple. Eso es un juicio, y es la investigación. Pone las ofertas donde no puedas pasarlas por alto.

"¿Se ha intentado esto?" — y "¿algo parecido?"

Dos preguntas diferentes. query responde a la primera por palabra clave, clasificada por qué tan bien coincide cada nodo — las coincidencias parciales salen a la superficie, así que una pregunta formulada con palabras que el nodo nunca usó aún lo encuentra:

$ knoten query "has anyone tried self-consistency?"

  [✗ DEAD] hyp-self-consistency
      killed by : method-compute-matched-baseline
      reopen if : A task where the majority-vote aggregation does real work…

Pero la búsqueda por palabra clave no puede responder a la segunda. Una idea expresada de manera diferente al nodo que ya la mató no coincidirá, y un "no se encontró trabajo previo" seguro es el único fallo de esta herramienta que cuesta trabajo real. Así que index imprime todo el grafo, una línea por nodo, y deja que el lector juzgue:

$ knoten index --tag decoding

  hyp-self-consistency  ✗ DEAD  [decoding,reasoning]  Self-consistency (sample 5, majority vote) beats greedy decoding

Eso es lo suficientemente barato para leerlo completo — el grafo entero, no una suposición sobre qué parte es relevante. Para un agente es aún más barato que una query amplia, porque una fila es una afirmación en lugar de un nodo completo: en un grafo de 500 nodos, una consulta amplia devolvió ~83k tokens, el índice del mismo grafo es ~9k, y una etiqueta lo reduce a ~2.5k.

Lo que una afirmación debe superar

Una afirmación solo puede marcarse viva si cita una puerta que superó. Un agente que cumple la puerta en el momento del commit ya ha gastado el cómputo en un experimento cuyo resultado no puede archivarse. gates pone la especificación delante del trabajo:

$ knoten gates

  method-compute-matched-baseline  (killed 1, survived by 1)
    Gate: compute-matched baseline
    the rule : Any method that spends more inference compute must be compared against a
               baseline given the same budget — not against greedy decoding at 1x.

El registro de la derecha es gratuito — los enlaces inversos ya existen — y es la mitad más interesante. Una puerta que no ha matado nada y no ha validado nada nunca se ha aplicado, lo que es o una verificación inútil o una verificación que nadie está ejecutando.

Dos lectores, un archivo

Humanos hojean la prosa y obtienen la historia: qué se intentó, qué lo mató, qué sigue abierto. Sin base de datos, sin interfaz de usuario, solo markdown que puedes leer en cualquier editor o en GitHub.

Agentes recorren el frontmatter: aristas tipadas (kn:killedByGate, kn:survivedGate), results estructurados, un bloque repro con el script/modelo/datos/comando exactos, y las rutas de cualquier script y gráfico adjuntos, que pueden leer y volver a ejecutar directamente. Un agente responde a "¿se ha intentado esto?" y "¿cómo lo reproduzco?" sin leer una palabra de prosa.

El mismo archivo sirve para ambos. Ese es todo el diseño.

Para agentes de codificación

SKILL.md, en la raíz del repositorio, es cómo un agente aprende knoten — apunta Claude Code, o cualquier otra cosa con un shell, a él. El bucle es la propia CLI, y acumula conocimiento sobre un tema a través de sesiones en lugar de empezar desde cero cada vez:

knoten frontier                                                 # 1. what should I work on next?
knoten index --tag decoding                                     # 2. anything LIKE this been tried?
knoten query "self-consistency"                                 #    ...or by keyword, if it has a name
knoten show hyp-self-consistency                                # 3. the full node, post-mortem included
knoten gates                                                    # 4. what must the result survive?
knoten commit hyp-idea --frontmatter fm.yaml --body body.md     # 5. file it, pass or fail
knoten update hyp-idea --status dead --append postmortem.md     #    ...or close one opened earlier
knoten attach hyp-idea script.py plot.png                       # 6. and the code that proves it
knoten path A B                                                 # how did we get from A to B?

La salida es prosa por defecto — léela. --json existe en todos los comandos de lectura anteriores, para scripts y datos anidados, pero cuesta más leerlo de lo que ahorra: el mismo grafo de 55 nodos es ~1,185 tokens como prosa en columnas frente a ~2,551 como JSON (21 vs 46 tokens/nodo — 2.2x). Recurre a --json; no lo uses por defecto.

--frontmatter, --body y --append toman cada uno una ruta de archivo o - para stdin. knoten update también toma --result key=value (repetible, registra un resultado) y --link rel=to (repetible, añade una arista — p. ej., la puerta que una afirmación acaba de superar):

knoten update hyp-idea --status alive --link kn:survivedGate=method-compute-matched-baseline

knoten update añade, mueve el estado y establece los campos que una muerte debe nombrar:

knoten update hyp-self-consistency --status dead \
  --append post-mortem.md --field cause=weak_baseline

--field establece cualquier clave de nivel superior, incluyendo una ya registrada. --result aún se niega a cambiar un número que el nodo ya lleva — añadir a una afirmación es el ciclo de vida, y reescribir un resultado publicado es para lo que sirve la retractación.

Lo que limita una edición son las propias reglas del grafo, no una lista de nombres de campo: el nodo modificado se analiza y verifica en memoria, y nunca llega al disco si falla. validate también rechaza un id: del frontmatter que no coincida con el nombre de archivo — el nombre de archivo es el id, así que un nodo que diga lo contrario miente sobre sí mismo mientras que toda consulta aún lo resuelve.

El código de salida es la señal: 0 tuvo éxito, 1 significa rechazado o violó una regla. Un rechazo es la característica — lee el mensaje, arregla el nodo, ejecútalo de nuevo.

Un experimento que lleva una semana no termina en la sesión que lo inició. Así que el agente puede abrir una hipótesis como abierta (knoten index --status open muestra lo que se inició y nunca se terminó), volver más tarde y cerrarla. knoten update añade y mueve el estado; no puede reescribir prosa ni cambiar un resultado que ya fue registrado, y ejecuta la misma puerta que knoten commit — así que una afirmación aún no puede volverse viva sin citar algo que superó. Una corrección a una afirmación sigue siendo un nuevo nodo. Git contiene el antes y el después.

El agente lee el grafo antes de ejecutar un experimento y escribe de vuelta cuando termina, incluyendo cuando el experimento falla. Una hipótesis muerta con una causa de muerte documentada es el nodo más valioso del grafo, y el que de otro modo se perdería. Escribe de vuelta la evidencia también: knoten attach pone el script que ejecutó y el gráfico que hizo en el nodo — una afirmación que no puedes volver a ejecutar es una afirmación en la que nadie confía en seis meses.

También le dice al agente cuándo está a punto de archivar la misma pregunta dos veces. Un bucle que se ejecuta durante semanas volverá a proponer una idea que ya resolvió, expresada de manera diferente, bajo un nuevo id — así que knoten commit reporta afirmaciones resueltas a las que se parece el nuevo nodo, y rechaza una que registra un resultado brillante sin citar una prueba que superó:

{"status": "COMMITTED",
 "similar": [{"id": "hyp-self-consistency", "verdict": "DEAD",
              "why_it_died": "The gain was compute, not method…"}],
 "warning": "This resembles 1 settled claim. If it is the same question, supersede or
             retract that node rather than leaving two answers in the graph."}

{"status": "REJECTED",
 "violations": [{"rule": "live-claims-must-cite-their-gates",
                 "message": "An unchallenged claim is not a finding, it is a hope."}]}

ops.py contiene la única implementación detrás de cada lectura — index, query, frontier, gates, show, validate, path — como una función simple que devuelve un dict. La CLI renderiza ese dict como prosa o lo vuelca con --json; commit y update también son funciones compartidas. Hay un comportamiento que mantener correcto, no dos que puedan divergir.

Clientes sin shell (MCP)

No todos los agentes tienen Bash. Para una interfaz de chat conectada a servidores MCP en lugar de un agente de codificación, el grafo sigue siendo accesible — solo que a un precio que la CLI no paga: MCP carga ~2,340 tokens de esquema de herramientas e instrucciones en cada sesión, ya sea que el agente toque el grafo o no (1,928 de esquema + 412 de instrucciones), mientras que knoten --help cuesta ~304, y solo cuando se pide. Usa la CLI y SKILL.md más arriba si el cliente puede ejecutar una.

pip install -e ".[mcp]"      # needs mcp 2.x

{"mcpServers": {"knoten": {
  "command": "knoten-mcp",
  "env": {"KNOTEN_GRAPH": "/path/to/llm-research"}
}}}

knoten_frontier()                                    ← 1. what should I work on next?
knoten_index(tags=["decoding"])                      ← 2. has anything LIKE this been tried?
knoten_query("self-consistency")                     ←    ...or by keyword, if it has a name
knoten_get("hyp-self-consistency")                   ← 3. the full node, post-mortem included
knoten_gates()                                       ← 4. what must the result survive?
knoten_commit(node)                                  ← 5. file it, pass or fail
knoten_update(node, status="dead", append=…)         ←    ...or close one opened earlier
knoten_attach(node, [script, plot])                  ← 6. and the code that proves it
knoten_path(a, b)                                    ← how did we get from A to B?
knoten_validate()                                    ← run the graph's own rules

El servidor entrega esa orden al cliente en el momento de la conexión como sus instructions, así que el agente recibe una explicación de cómo encaja el bucle una vez, en lugar de adivinarlo a partir de diez descripciones de herramientas. Cada herramienta aquí es un envoltorio fino sobre las mismas funciones ops / commit / update que la CLI llama — mismas puertas, mismos rechazos, mismo JSON mostrado arriba, solo serializado como resultado de herramienta en lugar de impreso como prosa.

Por qué molestarse

Dejas de rehacer experimentos que ya hiciste y olvidaste. Los callejones sin salida vuelven con su causa de muerte y un comando para volver a ejecutarlos.

Y el trabajo que sobrevive a la sesión aún se cierra. Un agente abre una hipótesis, ejecuta un experimento durante una semana y registra el veredicto en el mismo nodo cuando regresa — así que ¿qué sigue abierto? sigue siendo una respuesta real en lugar de llenarse con preguntas que se resolvieron y nunca se archivaron.

Y no puedes engañarte tan fácilmente: una afirmación solo puede marcarse viva si cita una prueba que superó, así que un resultado de buen aspecto que nunca fue verificado no puede convertirse silenciosamente en un hallazgo.

Y un nodo roto es un fallo ruidoso, no uno silencioso. Frontmatter ilegible, una relación de arista desconocida (kn:killdByGate — una letra omitida), una clave de regla que no existe: todo son errores. Un grafo que descarta silenciosamente lo que no puede analizar se reporta saludable mientras se pudre.

Y una afirmación que alguien retiró después lo dice. query muestra la retractación desde ambos lados, así que un agente que pregunta "¿se ha intentado esto?" sobre una afirmación que luego fue retractada recibe la respuesta de que fue retractada — no solo lo que decía la afirmación:

  [✓ ALIVE] hyp-few-shot-format
      survived     : method-compute-matched-baseline
      RETRACTED by : ret-oops

Consulta examples/llm-research/ para un grafo desarrollado y SPEC.md para el diseño.

MIT. Una dependencia de ejecución: PyYAML. La alternativa MCP necesita además el SDK mcp (2.x — pip install -U 'knoten[mcp]' si vienes de una versión anterior de knoten). Sin framework, sin base de datos, sin paso de compilación: un puñado de módulos pequeños que puedes leer de una sentada.