Ein Session-Start-Hook schreibt beim Öffnen einer neuen Sitzung einen kurzen Vertragstext in den Kontext des Agenten. Darin steht: Vor jeder Repository-Suche zuerst den lokalen Index befragen und teuer erarbeitete Fundstellen dort ablegen. Mehr ist es nicht: kein Wrapper, keine Middleware, keine erzwungenen Tool-Aufrufe. Nur ein Hinweis, den das Modell lesen und befolgen kann oder nicht. Dahinter steht capn-hook, ein kleines CLI-Werkzeug von Cyrus Nuevo Dia unter MIT-Lizenz. Es beschreibt sich als persistentes Gedächtnis für Coding Agents. Wer regelmäßig mit Claude Code oder Codex arbeitet, kennt den Reibungsverlust: Dieselbe Frage nach dem Ort eines Handlers wird Woche für Woche neu beantwortet, mit derselben Kette aus grep, Datei öffnen und wieder verwerfen.
Warum Coding Agents zwischen den Sessions alles vergessen
Jede Sitzung beginnt bei null. Ein Agent, der gestern herausgefunden hat, dass die Payment-Webhooks in src/api/webhooks.ts beginnen und die Handler unter src/billing/handlers/ liegen, weiß das morgen nicht mehr. Die Route von der Frage zum Fundort kostet Zeit und Tokens und endet mit der Sitzung. Genau dort setzt das Werkzeug an. Token sparen gelingt weniger über ein größeres Kontextfenster als über die Entscheidung, welche Funde man behält.
Das Projekt fasst sein Motiv so: „Don’t grep the same mystery twice.“ Der Satz spricht nicht von Wissen, sondern von einem Weg. Es geht nicht darum, dem Modell die Codebasis zu erklären, sondern den einmal gegangenen Pfad zu behalten. Wer eine Codebasis schneller erkunden will, braucht weniger ein Lexikon als eine Wegbeschreibung, die noch stimmt.
Codebasen verändern sich. Eine Wegbeschreibung, die gestern korrekt war, kann morgen in die Irre führen. Ein Gedächtnis mit veralteten Antworten ist schlimmer als keins, weil der Agent dem falschen Pfad folgt und den Fehler erst spät bemerkt. Die ganze Konstruktion von capn-hook dreht sich um diesen Punkt.
Drei Befehle: fragen, kartieren, verwerfen
Der rote Faden des Werkzeugs ist kartografisch. Der Agent kartiert, was er erkundet hat. Verschiebt sich die Küstenlinie, wird die alte Karte weggeworfen und beim nächsten Anlauf neu gezeichnet. Deshalb heißen die Befehle chart und unchart und nicht add und update. Die Namen folgen dieser Idee.
Der erste Zug ist eine Frage vor der Suche. Der Agent setzt capn ask "where are payment webhooks handled?" ab, bevor er grep anwirft. Ein Treffer liefert JSONL mit den Dateien, die die Frage beantworten, und überspringt die Erkundung. Ein Fehlschlag endet mit Exit-Code 1 und einem Hinweis auf stderr: explorieren und das Gefundene kartieren. Ein Miss kostet Sekunden, eine erneute Erkundung Minuten. Damit ist die Richtung klar.
Der zweite Zug speichert, was teuer war. Hat der Agent eine Antwort auf dem harten Weg erarbeitet, legt er eine kleine, beantwortbare Frage plus die Dateien ab, die sie beantworten: capn chart "..." --files a.ts,b.ts --details "...". Die Details sind optional, gedacht für Zeilennummern oder Fallstricke. Beim Speichern wird jede hinterlegte Datei per SHA-256 gefingerprintet. Der Eintrag hängt damit an einem konkreten Inhaltszustand.
Der dritte Zug ist der automatische Verfall. Ändert sich eine hinterlegte Datei oder verschwindet sie, wird der Eintrag entfernt, bevor er noch einmal antworten kann. capn ask räumt ungültige Einträge auf, bevor es etwas zurückgibt. Gespeicherte Antworten werden nie editiert. Eine Antwort ist entweder noch wahr oder wertlos. Manuell geht auch: capn prune räumt alle veralteten Einträge ab, capn bust <pfad> löscht alles, was an einer bestimmten Datei hängt, capn unchart <id> entfernt einen einzelnen Eintrag.
Installation in Claude Code und Codex: ein Hook, eine Zeile
Die Einrichtung bleibt schmal. Nach npm install -g capn-hook oder dem Bun-Pendant folgt im Projektverzeichnis capn init. Das legt den Ordner .capn/ an, erzeugt den QMD-Index, registriert die Hooks und trägt eine Zeile in die .gitignore ein, damit das Gedächtnis lokal bleibt. Mit capn init --git bekommt man zusätzlich einen Post-Commit-Hook, der veraltete Einträge automatisch ausdünnt.
Für Claude Code landet der Session-Start-Hook in .claude/settings.json, für Codex in .codex/hooks.json. In beiden Fällen lautet das Kommando /usr/bin/env capn context und bewirkt dasselbe: Der Agent bekommt zu Beginn jeder Sitzung den kurzen Vertrag eingespielt, erst fragen, dann suchen, danach kartieren. Codex-Hooks zu installieren heißt hier also nicht, eine eigene Verdrahtung zu bauen, sondern denselben Befehl in eine andere Konfigurationsdatei zu schreiben.
Die mitgelieferte INSTALL.md ist ausdrücklich für den Agenten geschrieben, nicht für den Menschen, der sie abschreibt. Wer die Einrichtung delegieren will, schickt seinen Agenten los, die Datei zu holen und zu befolgen. Das Werkzeug richtet sich an Automaten und traut ihnen die Lektüre zu.
Was die Messung mit 60 Fragen zeigt
Der Autor nennt eine eigene Auswertung: 60 Entwicklerfragen auf fünf Produktionscodebasen, darunter Dub, Polar, PostHog, Twenty und Documenso. Ein Agent, der aus capn recallte, verbrauchte laut diesen Zahlen 77 Prozent weniger Tokens als ein Agent, der kalt explorierte. In beiden Armen seien alle Antworten korrekt gewesen, die richtige Karte sei bei allen 60 Fragen zurückgekommen, und eine Kartierungssitzung amortisiere sich nach etwa 1,6 Recalls.
Die Zahlen sind die Selbstevaluation des Projektautors, keine unabhängige Studie, und 60 Fragen sind eine kleine Stichprobe. Wichtiger ist die Formulierung „bei wiederholten Fragen“. Der erste Besuch einer Codebasis wird durch capn-hook nicht billiger, im Gegenteil: Das Kartieren kommt als Zusatzaufwand dazu. Der Gewinn entsteht beim zweiten und dritten Mal. Die Amortisationsschwelle von 1,6 Recalls ist daher die aussagekräftigere Kennzahl, nicht die 77 Prozent.
Für die Praxis heißt das: Das Werkzeug ist ein Cache mit Rechenschaftslegung, kein Lernsystem. Es belohnt Projekte, in denen dieselben Fragen wiederkehren, also die meisten realen Codebasen. In Wegwerf-Repositories oder bei einmaligen Audits trägt es nichts und kostet nur Setup.
Der Aufbau unter .capn/: Markdown als Quelle der Wahrheit
Jede kartierte Frage liegt als eigene Markdown-Datei unter .capn/entries/<id>.md. Der Kopf enthält Frontmatter mit ID, Zeitstempel und einer Liste der hinterlegten Dateien samt Hash; darunter stehen die Frage und die optionalen Details. Diese Dateien sind lesbarer Text, du kannst sie öffnen und durchsehen. Das Gedächtnis ist damit nicht nur für Tools zugänglich, sondern auch für Menschen, die wissen wollen, was ihr Agent sich gemerkt hat.
Daneben gibt es .capn/map.json, einen abgeleiteten Rückwärtsindex von Dateipfad zu Hash und Eintrags-IDs. Fehlt oder verrottet diese Datei, baut capn sie aus den Frontmatter-Daten neu auf. .capn/config.json hält lokale Optionen wie den Embedding-Schalter, und .capn/qmd/index.sqlite ist der vom QMD-SDK erzeugte Suchindex mit den üblichen WAL- und SHM-Begleitdateien. Die Abhängigkeit läuft in eine Richtung: Das Markdown bleibt die dauerhafte Quelle, der Index ist wegwerfbar und jederzeit rekonstruierbar.
Der Recall läuft standardmäßig semantisch über eine hybride Suche, also Vektoren plus Keyword-Treffer. Mit capn init --no-embedding schaltest du auf reine BM25-Keywordsuche um. Diese Variante lädt nichts nach, ist vollständig deterministisch und damit für Umgebungen geeignet, in denen Reproduzierbarkeit mehr zählt als Trefferqualität bei ungenauen Formulierungen.
Eine Konsequenz sollte man klar benennen: capn init trägt .capn/ in die Gitignore ein. Das Gedächtnis gehört damit dem einzelnen Arbeitsverzeichnis und der einzelnen Entwicklerin, nicht dem Team. Es gibt keinen geteilten Wissensstand, keine gemeinsam gepflegte Karte. Für manche ist das ein Datenschutzvorteil, für andere eine fehlende Funktion.
Wo die Grenzen liegen und was das für den Alltag bedeutet
Die hybride Suche hat einen Preis. Beim ersten Gebrauch lädt der Standardpfad Embedding-Modelle nach, rund 300 Megabyte, für die volle Pipeline bis zu zwei Gigabyte. Ein kalter capn ask kann danach einige Sekunden brauchen, weil das Modell erst geladen werden muss. Wer das nicht will, nimmt den BM25-Pfad, der nichts nachlädt und sofort antwortet.
Die Invalidierung über Inhaltshashes ist bewusst grob. Ein Whitespace-Fix in einer Datei löscht jeden Eintrag, der auf ihr basiert, auch wenn die Antwort inhaltlich stimmt. Das ist der Preis für eine Regel ohne Judgment Call: keine Interpretation, keine Heuristik, kein Modell, das rät, ob eine Änderung relevant war. Eine falsche Antwort kommt praktisch nicht vor. Dafür gibt es gelegentlich Nacharbeit, die aber genau der Arbeit entspricht, die ohne das Werkzeug ohnehin angefallen wäre.
Der Kern der CLI weiß nichts von Claude Code. Die Hooks sind ein dünner Adapter, andere Agents integrieren sich durch Aufruf derselben Kommandos, und der Recall läuft prozessintern über das SDK gegen die eigene SQLite-Datei, isoliert von einer eventuell vorhandenen qmd-Installation. Kein Daemon, kein Server, nichts, was im Hintergrund laufen muss. Das ist eine Architekturentscheidung, die man unterschätzen kann, bis man das erste Mal ein Werkzeug mit Hintergrunddienst in einer CI oder auf einem entfernten Rechner debuggen musste.
capn-hook löst kein Wissensproblem, es löst ein Wiederholungsproblem, und es löst es mit einer strengen Regel: Eine gespeicherte Antwort ist entweder durch Hashes gedeckt oder sie existiert nicht. Für Teams, die täglich mit denselben Coding Agents auf derselben Codebasis arbeiten, ist das ein kleiner, sauberer Baustein, der sich nach wenigen Recalls rechnet. Wer ihn ausprobiert, sollte ihn als Cache behandeln, nicht als Beschreibung der Codebasis.
Quelle: github.com
