knoten

Jede Idee ist eine Markdown-Datei in Git, markiert als lebendig, tot oder zurückgezogen. Wenn sie gestorben ist, trägt der Knoten den Grund, was sie wiederbeleben würde und den Code zur Reproduktion.

So funktioniert es

Ein Graph ist ein Ordner. Ein Knoten ist eine Markdown-Datei: Frontmatter für Maschinen, Prosa für Menschen, Code zur Reproduktion.

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

Drei Monate später, wenn jemand erneut Self-Consistency vorschlägt:

$ 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

Nutzung

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?

Jeder Lese-Befehl oben akzeptiert auch --json; Prosa ist der Standard, weil es günstiger zu lesen ist (siehe „Für Codierungs-Agenten" unten), --json ist für Skripte und verschachtelte Daten da.

Jeder Graph deklariert seine eigenen Regeln in graph.yaml. knoten weiß nichts über dein Fachgebiet. Es erzwingt, was du als wichtig definiert hast. Der Beispiel-Graph verlangt von jeder Behauptung, tokens_per_question zu melden und auf mindestens 30 unabhängigen Fragen zu basieren; ein anderes Thema würde etwas völlig anderes verlangen.

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.

Das letzte macht eine Sackgasse wiederverwendbar. Sobald die Ursache ein Feld statt eines Satzes ist, wird die Frage, die du sechs Monate später tatsächlich stellst, zu einer Abfrage:

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

Dein Graph deklariert auch sein eigenes Vokabular, und das wird ebenfalls durchgesetzt:

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

type: hypthesis ist ein Tippfehler, kein neuer Typ. status: ded ist schlimmer als falsch – es würde die Behauptung stillschweigend aus jeder Abfrage entfernen, genau die Art von leiser Fäulnis, die dieses Werkzeug verhindern soll. Beides sind jetzt Verstöße. Ebenso tags: [decodng]: Tags sind die Achse, nach der du einen großen Graphen filterst, also lässt ein vertippter Tag den Knoten im Graphen, aber außerhalb jeder Ansicht davon. Deklarierst du keine tags:, bleibt das Tagging frei – der Kern erfindet kein Vokabular, er erzwingt nur das von dir deklarierte.

Ein Regel-Schlüssel – oder ein Konfig-Schlüssel – den knoten nicht kennt, ist ein harter Fehler, kein Achselzucken. Konfiguration, die nichts erzwingt, ist Dekoration, und eine Regel, die nichts erzwingt, ist schlimmer als keine Regel, weil du denkst, du wärst abgesichert.

knoten new liest diese Regeln und füllt genau das vor, was sie verlangen – nichts im Gerüst ist knotens Meinung, es ist die deines Graphen. Die Werte sind absichtlich TODO, damit new + validate eine Checkliste und kein Ratespiel ist:

$ 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

Das Versagen, das dieses Werkzeug verhindern soll, wurde durch Reibung verursacht, also ist der Schreibpfad die Stelle, an der Reibung am meisten wehtut. Schreibe Prosa, keinen Boilerplate, den du erst durch Ablehnung entdecken musstest.

Das Tor ist ein Git-Hook

knoten hook     # after `git init`

git commit führt nun knoten validate aus und lehnt einen Graphen ab, der seine eigenen Regeln bricht:

$ 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

Eine Regel, die nur feuert, wenn du dich erinnerst zu fragen, ist die Regel, die den letzten Versuch verrotten ließ. Lege sie an einen Ort, an dem du nicht vorbeigehen kannst. (git commit --no-verify umgeht sie – du solltest einen Grund haben.)

Code und Diagramme anhängen

Ein Knoten ist nicht nur eine Behauptung. Er enthält, was du zum erneuten Ausführen benötigst.

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

Die Dateien werden nach attachments/<node-id>/ kopiert, im Frontmatter aufgelistet, und Bilder werden in den Knotentext eingebettet, damit sie auf GitHub gerendert werden:

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

knoten validate schlägt dann fehl, wenn ein Knoten einen Anhang auflistet, der nicht vorhanden ist. Eine kaputte Reproduktion ist ein kaputter Knoten.

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

Was nun?

Ein Graph, der nur die Frage „Wurde das schon versucht?" beantwortet, ist ein Aktenschrank. frontier ist der eine Bildschirm, der „Was nun?" beantwortet:

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

Eine Sackgasse mit einem bestehenden Angebot ist ein günstigeres Experiment als eine neue Idee, weil das Design bereits aufgeschrieben ist. Dafür ist ## Was würde das wieder öffnen da: ohne eine Möglichkeit, es anzuzeigen, bedeutet das Handeln danach, alle Post-Mortems im Graphen erneut zu lesen.

knoten entscheidet nicht, ob eine Bedingung erfüllt ist. Das ist ein Urteil, und es ist die Forschung. Es stellt die Angebote dorthin, wo du nicht vorbeigehen kannst.

„Wurde das schon versucht?" – und „etwas Ähnliches?"

Zwei unterschiedliche Fragen. query beantwortet die erste per Stichwort, sortiert nach Übereinstimmungsgrad jedes Knotens – partielle Treffer werden angezeigt, sodass eine Frage, die in Worten formuliert ist, die der Knoten nie verwendet hat, ihn trotzdem findet:

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

Aber die Stichwortsuche kann die zweite nicht beantworten. Eine Idee, die anders formuliert ist als der Knoten, der sie bereits getötet hat, wird nicht übereinstimmen, und ein selbstbewusstes „keine Vorarbeit gefunden" ist das eine Versagen dieses Werkzeugs, das echte Arbeit kostet. Also gibt index den gesamten Graphen aus, eine Zeile pro Knoten, und überlässt dem Leser das Urteil:

$ knoten index --tag decoding

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

Das ist günstig genug, um es vollständig zu lesen – den gesamten Graphen, keine Vermutung darüber, welcher Teil relevant ist. Für einen Agenten ist es noch günstiger als eine breite query, weil eine Zeile eine Behauptung statt eines ganzen Knotens ist: Bei einem 500-Knoten-Graphen lieferte eine breite Abfrage ~83k Token, der gleiche Graph als Index ~9k, und ein einzelnes Tag grenzt es auf ~2,5k ein.

Was eine Behauptung überstehen muss

Eine Behauptung kann nur als alive markiert werden, wenn sie ein Tor zitiert, das sie überstanden hat. Ein Agent, der das Tor zum Commit-Zeitpunkt erfüllt, hat bereits die Rechenleistung für ein Experiment aufgewendet, dessen Ergebnis nicht abgelegt werden kann. gates stellt die Spezifikation vor die Arbeit:

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

Der Eintrag rechts ist kostenlos – die Rückverweise existieren bereits – und er ist die interessantere Hälfte. Ein Tor, das weder etwas getötet noch etwas validiert hat, wurde nie angewandt, was entweder eine nutzlose Prüfung oder eine Prüfung ist, die niemand ausführt.

Zwei Leser, eine Datei

Menschen überfliegen die Prosa und erhalten die Geschichte: was versucht wurde, was es getötet hat, was noch offen ist. Keine Datenbank, keine Benutzeroberfläche, nur Markdown, das du in jedem Editor oder auf GitHub lesen kannst.

Agenten durchlaufen das Frontmatter: typisierte Kanten (kn:killedByGate, kn:survivedGate), strukturierte results, einen repro-Block mit dem genauen Skript/Modell/Daten/Befehl und den Pfaden aller angehängten Skripte und Diagramme, die sie direkt lesen und erneut ausführen können. Ein Agent beantwortet „Wurde das schon versucht?" und „Wie reproduziere ich es?", ohne ein Wort der Prosa zu lesen.

Die gleiche Datei dient beiden. Das ist das gesamte Design.

Für Codierungs-Agenten

SKILL.md im Repository-Stammverzeichnis ist, wie ein Agent knoten lernt – weise Claude Code oder alles andere mit einer Shell darauf hin. Die Schleife ist das CLI selbst, und es sammelt Wissen über ein Thema über Sitzungen hinweg, anstatt jedes Mal kalt zu starten:

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?

Die Ausgabe ist standardmäßig Prosa – lies sie. --json gibt es bei jedem Lese-Befehl oben, für Skripte und verschachtelte Daten, aber es kostet mehr zu lesen, als es spart: Der gleiche 55-Knoten-Graph sind ~1.185 Token als Spaltenprosa gegenüber ~2.551 als JSON (21 vs 46 Token/Knoten – 2,2x). Greife zu --json; mach es nicht zum Standard.

--frontmatter, --body und --append akzeptieren jeweils einen Dateipfad oder - für stdin. knoten update akzeptiert auch --result key=value (wiederholbar, zeichnet ein Ergebnis auf) und --link rel=to (wiederholbar, fügt eine Kante hinzu – z.B. das Tor, das eine Behauptung gerade überstanden hat):

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

knoten update hängt an, verschiebt den Status und setzt die Felder, die ein Tod benennen soll:

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

--field setzt einen beliebigen Top-Level-Schlüssel, auch einen bereits aufgezeichneten. --result weigert sich immer noch, eine Zahl zu ändern, die der Knoten bereits trägt – das Anhängen an eine Behauptung ist der Lebenszyklus, und das Umschreiben eines veröffentlichten Ergebnisses ist das, wofür die Zurückziehung da ist.

Was eine Bearbeitung begrenzt, sind die eigenen Regeln des Graphen, nicht eine Liste von Feldnamen: Der geänderte Knoten wird im Speicher geparst und geprüft und erreicht nie die Festplatte, wenn er fehlschlägt. validate weigert sich auch, ein Frontmatter id: zu akzeptieren, das nicht mit dem Dateinamen übereinstimmt – der Dateiname ist die ID, also lügt ein Knoten, der etwas anderes behauptet, über sich selbst, während jede Abfrage ihn immer noch auflöst.

Der Exit-Code ist das Signal: 0 bedeutet Erfolg, 1 bedeutet Verweigerung oder Regelverstoß. Eine Verweigerung ist das Feature – lies die Nachricht, korrigiere den Knoten, führe ihn erneut aus.

Ein Experiment, das eine Woche dauert, endet nicht in der Sitzung, die es gestartet hat. Also kann der Agent eine Hypothese als open eröffnen (knoten index --status open zeigt, was gestartet und nie beendet wurde), später zurückkommen und sie schließen. knoten update hängt an und verschiebt den Status; es kann Prosa nicht umschreiben oder ein bereits aufgezeichnetes Ergebnis ändern, und es durchläuft das gleiche Tor wie knoten commit – also kann eine Behauptung immer noch nicht alive werden, ohne etwas zu zitieren, das sie überstanden hat. Eine Korrektur einer Behauptung ist immer noch ein neuer Knoten. Git bewahrt das Vorher und Nachher.

Der Agent liest den Graphen, bevor er ein Experiment ausführt, und schreibt zurück, wenn es fertig ist, auch wenn das Experiment fehlschlägt. Eine tote Hypothese mit einer dokumentierten Todesursache ist der wertvollste Knoten im Graphen und derjenige, der sonst verloren wäre. Er schreibt die Beweise ebenfalls zurück: knoten attach legt das ausgeführte Skript und das erstellte Diagramm in den Knoten – eine Behauptung, die du nicht erneut ausführen kannst, ist eine Behauptung, der in sechs Monaten niemand vertraut.

Es sagt dem Agenten auch, wann er kurz davor ist, dieselbe Frage ein zweites Mal abzulegen. Eine Schleife, die Wochen läuft, wird eine Idee, die sie bereits geklärt hat, erneut vorschlagen, anders formuliert, unter einer neuen ID – also meldet knoten commit geklärte Behauptungen, denen der neue Knoten ähnelt, und lehnt einen ab, der ein glänzendes Ergebnis aufzeichnet, ohne einen bestandenen Test zu zitieren:

{"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 enthält die eine Implementierung hinter jedem Lese-Befehl – index, query, frontier, gates, show, validate, path – als einfache Funktion, die ein Diktat zurückgibt. Das CLI rendert dieses Diktat als Prosa oder gibt es mit --json aus; commit und update sind ebenfalls gemeinsame Funktionen. Es gibt ein Verhalten, das korrekt zu halten ist, nicht zwei, die auseinanderdriften können.

Clients ohne Shell (MCP)

Nicht jeder Agent hat Bash. Für eine Chat-Oberfläche, die an MCP-Server angeschlossen ist, statt an einen Codierungs-Agenten, ist der Graph immer noch erreichbar – nur zu einem Preis, den das CLI nicht zahlt: MCP lädt ~2.340 Token an Tool-Schema und Anweisungen in jede Sitzung, egal ob der Agent den Graphen berührt oder nicht (1.928 Schema + 412 Anweisungen), während knoten --help ~304 kostet, und nur auf Anfrage. Verwende das CLI und SKILL.md oben, wenn der Client eines ausführen kann.

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

Der Server übergibt diese Reihenfolge dem Client beim Verbindungsaufbau als seine instructions, also wird dem Agenten einmalig erklärt, wie die Schleife zusammenhängt, anstatt dass er es aus zehn Tool-Beschreibungen erraten muss. Jedes Tool hier ist ein dünner Wrapper um dieselben ops / commit / update-Funktionen, die das CLI aufruft – gleiche Tore, gleiche Verweigerungen, gleiches oben gezeigtes JSON, nur serialisiert als Tool-Ergebnis statt als Prosa ausgegeben.

Warum der Aufwand

Du hörst auf, Experimente zu wiederholen, die du bereits durchgeführt und vergessen hast. Sackgassen tauchen wieder auf mit ihrer Todesursache und einem Befehl, sie erneut auszuführen.

Und Arbeit, die die Sitzung überdauert, wird trotzdem abgeschlossen. Ein Agent eröffnet eine Hypothese, führt eine Woche lang ein Experiment durch und zeichnet das Urteil auf demselben Knoten auf, wenn er zurückkommt – also bleibt was noch offen ist? eine echte Antwort, anstatt sich mit Fragen zu füllen, die geklärt und nie abgelegt wurden.

Und du kannst dich nicht mehr so leicht hinters Licht führen: Eine Behauptung kann nur als alive markiert werden, wenn sie einen Test zitiert, den sie überstanden hat, also kann ein gut aussehendes Ergebnis, das nie überprüft wurde, nicht stillschweigend zu einem Befund werden.

Und ein kaputter Knoten ist ein lauter Fehler, kein leiser. Unlesbares Frontmatter, eine unbekannte Kantenrelation (kn:killdByGate – ein Buchstabe fehlt), ein Regelschlüssel, der nicht existiert: Alles sind Fehler. Ein Graph, der stillschweigend fallen lässt, was er nicht parsen kann, meldet sich selbst als gesund, während er fault.

Und eine Behauptung, die jemand später zurückgezogen hat, sagt das. query zeigt die Zurückziehung von beiden Seiten an, also wird einem Agenten, der „Wurde das schon versucht?" zu einer Behauptung fragt, die später zurückgezogen wurde, gesagt, dass sie zurückgezogen wurde – nicht nur, was die Behauptung besagte:

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

Siehe examples/llm-research/ für einen ausgearbeiteten Graphen und SPEC.md für das Design.

MIT. Eine Laufzeitabhängigkeit: PyYAML. Der MCP-Fallback benötigt zusätzlich das mcp-SDK (2.x – pip install -U 'knoten[mcp]' wenn du von einem älteren knoten kommst). Kein Framework, keine Datenbank, kein Build-Schritt: eine Handvoll kleiner Module, die du in einem Durchgang lesen kannst.