Selvedge
Langzeitgedächtnis für KI-geschriebene Codebasen – einschließlich dessen, was bereits ausprobiert und verworfen wurde.
Zeilenattribution sagt dir, wer etwas geschrieben hat. Selvedge sagt deinem
Agenten, was er als Nächstes nicht schreiben soll: die Ansätze, die diese
Codebasis bereits ausprobiert und zurückgenommen hat, und warum. Es ist ein
git blame für KI-Agenten, für das Warum statt dafür, welches Modell welche
Zeile angefasst hat – live erfasst, vom Agenten selbst, während die Änderung
passiert, sodass niemand nachgelagert raten muss.
Selvedge ist ein lokaler MCP-Server. KI-Coding-Agenten (Claude Code, Cursor,
Copilot) rufen ihn während der Arbeit auf, um strukturierte
Änderungsereignisse mit Begründung zu protokollieren. Deine Daten bleiben in
einer SQLite-Datei unter .selvedge/ neben deinem Code.
Local-first standardmäßig, Team-Server nach Wahl, immer ohne LLM.
Vor sechs Monaten hat dein KI-Agent eine Spalte namens user_tier_v2
hinzugefügt. Du weißt nicht, warum. git blame verweist auf einen Commit von
claude-code mit einer generierten Nachricht, die „Update schema." lautet.
Die Sitzung, die die Änderung vorgenommen hat, ist längst vorbei – und damit
auch der Prompt, der sie erzeugt hat.
Mit Selvedge führst du stattdessen Folgendes aus:
$ 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.Diese Begründung wurde vom Agenten im Moment der Änderung erfasst – in Selvedge geschrieben aus demselben Kontext, der die Änderung hervorgebracht hat. Nicht nachträglich von einem zweiten LLM aus dem Diff abgeleitet. Keine handgetippte Commit-Nachricht.
Für wen Selvedge gedacht ist
Selvedge hat zwei Zielgruppen. Dasselbe Werkzeug, dasselbe pip install,
dieselbe SQLite-Datei unter .selvedge/. Unterschiedliches Ausmaß an Schmerz.
Teams, die langfristige, KI-geschriebene Codebasen betreiben.
Wenn das Projekt groß genug ist, dass du (oder jemand anderes) es in sechs
Monaten, zwölf Monaten, drei Jahren wieder anfassen wirst – aber der größte
Teil davon von einem Agenten geschrieben wurde, dessen Kontext an dem Tag
verdampfte, an dem jeder PR ausgeliefert wurde. git blame sagt dir, was sich
geändert hat. Selvedge sagt dir warum – selbst wenn die Agenten-Sitzung, die
Prompt-Vorlage, der Entwickler, der sie angefordert hat, und die
Modellversion längst weg sind. Das ist der ursprüngliche Anwendungsfall:
Produktionscodebasen, Schema-Entscheidungen, Migrationen,
Abhängigkeitsänderungen, die einen Prüfpfad brauchen, der Personalwechsel
überlebt.
Solo-Entwickler, die Claude Code für alltägliche Projekte nutzen.
Nebenprojekte, Wochenend-Builds, das kleine interne Tool, an dem du immer
wieder herumdokterst. Du brauchst keine Unternehmens-Governance – du musst
nur wissen, warum du (oder dein Agent) das getan hast, was du gestern,
letzte Woche, im letzten Sprint getan hast. Führe selvedge init einmal aus.
Füge vier Zeilen zu deiner CLAUDE.md hinzu. Ab dann ist selvedge blame
Muskelgedächtnis – eine Möglichkeit, mit deinem vergangenen Selbst zu
sprechen, wenn dein vergangenes Selbst ein LLM war.
Wenn du jemals zu deinem eigenen KI-gebauten Projekt zurückgekehrt bist und gedacht hast „wofür war das nochmal?", ist Selvedge das fehlende Puzzleteil.
Related MCP server: claude-engram
Das Problem
Menschengeschriebener Code gibt Absicht überall preis – Commit-Nachrichten, PR-Beschreibungen, Inline-Kommentare, der Slack-Thread davor. KI-geschriebener Code tut das nicht. Der Agent hat vollkommene Klarheit darüber, warum er jede Entscheidung getroffen hat, aber dieser Kontext lebt im Prompt und verdampft, wenn das Gespräch endet.
Sechs Monate später debuggt dein Team eine Schema-Entscheidung ohne
Nachverfolgbarkeit. git blame sagt dir, was sich geändert hat und wann.
Es kann dir nicht sagen, warum.
Selvedge erfasst das Warum – live, vom Agenten selbst, während die Änderung vorgenommen wird. Das Diff ist gits Aufgabe. Das Warum ist Selvedges.
Was es in v0.3.10 Neues gibt
Das Gedächtnis kommt zum Agenten, und der Speicher bekommt seine Stellschrauben. Zwei Themen, zusammen ausgeliefert, weil die Konfigurationshälfte das war, was der Rest brauchte, um Einstellungen zu lesen.
Zustellung. Selvedge blockierte bereits Neu-Bearbeitungen zurückgenommener Entitäten. Was fehlte, war die Zustellung, wenn es nichts zu vetoieren gibt. Zwei neue Hooks:
SessionStart injiziert eine kompakte Zusammenfassung, wenn eine Sitzung beginnt – Entscheidungen, die zur erneuten Prüfung anstehen, Entitäten, die ausprobiert und zurückgenommen wurden, aktuelle Änderungssätze.
PreCompact feuert kurz bevor die Kontextkomprimierung die Begründung dieser Sitzung zerstört, und benennt die überwachten Entitäten, die du bearbeitet, aber nie protokolliert hast.
Beide sind leise, wenn sie nichts zu sagen haben, größenbegrenzt, schreibgeschützt und vorlagenbasiert. Keiner von beiden kann etwas blockieren – PreCompact lehnt das Veto, das die Hook-API ihm anbietet, bewusst ab. Das ist die Antwort auf einen gemessenen Fehlermodus: Zwei Paper aus dem Jahr 2026 dokumentierten, dass Pull-Modell-Gedächtniswerkzeuge völlig ungenutzt blieben (null freiwillige Gedächtnisoperationen über 114 Turns gegen einen vorab befüllten Speicher), während deterministische Injektion jedes Mal ankam.
selvedge export --format markdown rendert den Speicher als
prüfbare Zusammenfassung, die du neben ihm committen kannst, sodass erfasste
Absicht in einem Pull-Request auftaucht, statt sich in einer Binärdatei zu
verstecken. Deterministisch – eine erneute Generierung ohne neue Ereignisse
ergibt ein Diff mit null Zeilen.
Konfiguration. .selvedge/config.toml ist jetzt erstklassig, mit einer
kanonischen Präzedenzkette, die selvedge doctor pro Einstellung ausgibt. Es
bringt:
selvedge prune --include-events– der erste Pfad, der erfasste Begründungen löschen kann, also braucht er sowohl eine Bestätigung als auchSELVEDGE_DESTRUCTIVE=1. Keines allein reicht, weil--yesin einem Cron-Eintrag eine Eingabeaufforderung aushebelt und ein Shell-Profil eine Umgebungsvariable. Die Aufbewahrung von Ereignissen ist standardmäßig auf „nie" eingestellt.Ereignisgrößen-Grenzen (
diff_bytes,reasoning_bytes), die laut kürzen – eine Markierung im Text, eine Warnung beim Schreiben, eine Zählung inselvedge stats.Warnungen vor Geheimnis-Mustern bei
log_change, erweiterbar überredaction_patterns, plus einedoctor-Zeile, die scannt, was bereits gespeichert ist. Warnen, nie ablehnen.
Außerdem: Fünf Review-Probleme geschlossen. Der Allow-Pfad des
Durchsetzungs-Hooks ist 40 % schneller (33,6 ms → 20,1 ms pro
abgesichertem Aufruf), und SELVEDGE_HOOK_DISABLE=1 greift endlich vor den
Imports, die laut Dokumentation übersprungen werden sollten; log_change
verwirft revisit_after / constraint / stale_when bei Umbenennungen und
Ersetzungen nicht mehr; das --json der CLI und die MCP-Tools geben jetzt
identische Strukturen zurück; und das Docker-Image enthält nicht mehr die
eigene Datenbank des Maintainers. Tests 826 → 984.
Was es in v0.3.9.3 Neues gibt
Behebt eine kaputte Installation und bringt einen vollständigen
Code-Qualitätsdurchgang. mcp 2.0.0 (veröffentlicht am 28.07.2026) entfernte
mcp.server.fastmcp, und Selvedge deklarierte mcp>=1.0.0 ohne obere Grenze –
also zog jedes pip install selvedge nach diesem Datum 2.0.0, und
selvedge-server scheiterte beim Import. Dieses Release pinnt die
Abhängigkeit. Wenn dein Server nicht mehr startet, ist das der Grund –
aktualisiere.
Es kommt zusammen mit einem Review, das neun unabhängige Durchgänge über die Codebasis machte und dann versuchte, jeden Befund zu widerlegen, bevor es handelte. Siebzehn bestätigte Fehler behoben. Die, die du tatsächlich bemerkt hättest:
Der Durchsetzungs-Hook blockierte Dinge, die er nicht blockieren sollte. Das Lesen einer überwachten Datei –
cat,git diff,pytest,ruff check– wurde blockiert, und die Abhilfe, die die Fehlermeldung dir zu laufen befahl, wurde von derselben Sperre blockiert, sodass es von der CLI aus keinen Ausweg gab. Zwei weitere Pfade speisten dieselben falschen Blockaden: eine auskommentierte SQL-Zeile zählte als echte Löschung, und jede Commit-Nachricht, die nur das Wort „revert" enthielt, markierte jede Datei, die sie berührte, als zurückgenommen.Nachschlagen wurde bei großem Umfang schnell. Der Haupt-Entitäts-Read scannte jede Zeile – gemessen 7,4 ms → 0,35 ms bei 100k Ereignissen, und der Hook hatte bei großen Speichern Sekunden gebraucht.
selvedge setupkann keine Teile deinerCLAUDE.mdmehr löschen, eine unterbrochene Sicherung kann deine letzte gute nicht mehr zerstören, und ein Upgrade bei zwei gleichzeitig laufenden Selvedge-Prozessen stürzt nicht mehr mit einem Fehler ab, der wie Datenbankkorruption aussah.
Tests gingen von 739 auf 826. Keine Schema-Änderung und keine Tool-Oberflächen-Änderung, also ist das Drop-in für alle auf 0.3.9.x.
Wo Selvedge hineinpasst
KI-Agenten rufen Selvedge während der Arbeit auf. Selvedge erfasst das Warum in einem dauerhaften, durchsuchbaren Speicher und gibt es wieder aus – als Agent Trace-Aufzeichnungen für werkzeugübergreifende Leser, als Observability-Metadaten, die sich in Sentry/Datadog-Stacktraces einbinden, und als Compliance-Artefakte für SOC-2- und EU-AI-Act-Audits.
Selvedge ersetzt nicht git (What/When auf Zeilenebene),
PR-Review-Tools (Qualität zum Review-Zeitpunkt), Agent-Observability
(LLM-Aufruf-Traces) oder allgemeine KI-Funktionen der Code-Hosting-Plattform.
Es sitzt dazwischen – die Schicht, in der Herkunftsnachweise
(Provenance) erstklassige Bürger sind und auf die sich alles andere bezieht.
Wie Selvedge im Vergleich abschneidet
Es gibt eine schnell wachsende Kategorie „git blame für KI-Agenten". Hier passt Selvedge hinein – und wo es bewusst nicht hineinpasst.
Abgelehnte Pfade | Quelle der Begründung | Granularität | Mechanismus | Gruppierung | Speicherung | |
Selvedge | Abfragbar — | Live erfasst, vom Agenten im selben Kontext, der die Änderung erzeugt hat | Entität — DB-Spalte, Tabelle, Env-Var, Dependency, API-Route, Funktion | MCP-Server — der Agent ruft ihn auf, während die Arbeit passiert | Changesets — benannte Feature-/Task-Slugs über viele Entitäten hinweg | SQLite, keine Abhängigkeiten |
Bereinigt — | Abgeleitet — Tree-Sitter-Statikanalyse des Code-Zustands, plus commit-gesteuerte Entscheidungsnotizen | AST-Knoten (18 Sprachen + 12 IaC) | MCP-Server — einmaliger Index + Commit-Zertifikate | Call-Graph-Kanten | SQLite-Graph in | |
Keine | Nachträglich abgeleitet von Claude Haiku aus dem Diff am Sitzungsende | Zeile | Claude-Code-Lifecycle-Hooks → lokaler Daemon | Sitzung/Aufgabe | JSONL auf der Platte | |
Keine | ed25519-signierte Cross-Agent-Herkunft | Zeile | Per-Agent-Editor-Hooks + Git-Hooks (Signatur beim Commit) | Keine | Signierte Traces in Git-Refs | |
Keine — | Prompt-Belege, live pro Turn erfasst | Zeile | Agent-Lifecycle-Hooks + Git-Post-Commit-Hook | Keine | Git-Notes + Sessions-Branch | |
Keine | Attributions-Metadaten | Zeile | Agent-aufgerufener Checkpoint → Git-Notes beim Commit | Keine | Git-Notes | |
Keine | Prompt-Belege — Prompt, Kosten, Tools; keine angegebene Begründung | Zeile | Agent-Lifecycle-Hooks + Post-Commit-Hook | Keine | Git-Notes |
Warum „abgelehnte Pfade" wichtig sind — der eine, der nicht kopierbar ist. Der teure
Fehlschlag ist nicht, zu vergessen, warum eine Spalte existiert. Es ist ein Agent, der
selbstbewusst etwas neu implementiert, das das Team bereits aus gutem Grund verworfen hat,
sechs Monate nachdem alle, die das wussten, den Kontextfenster verlassen haben. Keines der
Zeilen-Attributionswerkzeuge oben zeigt abgelehnte Pfade überhaupt an, und das ist keine
Funktionslücke, die sie in einem Release schließen können — ein zeilenorientierter Speicher
hat kein Konzept einer Entität, die einen Versuch → Rücknahme → Wiederholungs-Zyklus
überdauert hat. Siehe
docs/demos/prior-attempts.md.
Warum Determinsmus wichtig ist. Selvedges Begründung ist die eigene Absicht des Agenten, geschrieben aus demselben Kontextfenster, das die Änderung erzeugt hat. Es gibt kein Modell irgendwo im Speicher- oder Abrufpfad, daher liefert dieselbe Abfrage heute und in zwei Jahren dieselbe Antwort, über Modellversionen hinweg. Werkzeuge, die Begründungen nachträglich ableiten, führen eine zweite LLM aus, die den ursprünglichen Prompt nie gesehen hat: Was sie produziert, ist Paraphrase, und eine erneute Ausführung kann für dieselbe Änderung andere Kategorien erzeugen. Wie ein Hacker-News-Kommentator zu einem konkurrierenden Ansatz sagte: grep wird deinen Commit nicht finden, weil du „oauth-library" abgelehnt hast … es sei denn, es gibt deterministische Durchsetzung (0x457).
Determinismus allein ist kein Unterscheidungsmerkmal mehr — OpenLore ist ebenfalls determinismus-nativ und sagt das auch. Das zusammengesetzte Unterscheidungsmerkmal ist append-only-Testimonium: Begründung, die der Agent selbst geschrieben hat, aufbewahrt in einem Speicher, in dem eine Ablehnung ein erstklassiger Datensatz ist und kein inaktiver Status, der weggefegt wird.
Warum „Entitätsebene" wichtig ist. Die meisten Werkzeuge attribuieren Zeilen. Selvedge
attribuiert Dinge, nach denen du tatsächlich suchst: users.email,
env/STRIPE_SECRET_KEY, api/v1/checkout, deps/stripe. Die erste
Frage nach git blame ist normalerweise „Was ist die Geschichte dieser Spalte",
nicht „Was ist die Geschichte der Zeilen 40–48 von users.py".
Warum „live erfasst" wichtig ist. Kein Unterscheidungsmerkmal für sich — jedes
Werkzeug hier beansprucht eine Variante davon —, aber es ist der Mechanismus, der die
Begründung vertrauenswürdig macht. Im Moment der Änderung zu schreiben, aus dem Kontext,
der sie erzeugt hat, ist der Grund, warum es kein zweites Modell im Pfad gibt, das eine
Erklärung halluzinieren könnte. Ein leeres reasoning-Feld ist selbst ein ehrliches
Signal: Der Agent hatte keines.
Vergleich aktuell Stand 2026-08-05; OpenLore bei v2.1.8 / 265★, gegen seine Quelle verifiziert. Korrekturen sind als Issue willkommen.
Warum „Changesets" wichtig sind. Ein Stripe-Abrechnungs-Rollout betrifft die users-
Tabelle, zwei neue Env-Vars, drei neue API-Routen, eine Dependency und vier
Funktionen im gesamten Codebase. Markiere jedes Ereignis mit changeset:add-stripe-billing
und du kannst den gesamten Umfang später wieder abrufen — selbst wenn der ursprüngliche PR
über einen Monat in acht kleinere aufgeteilt wurde.
Selvedge ↔ Agent Trace. Agent Trace ist ein
offenes KI-Code-Attributions-Wire-Format, veröffentlicht von Cursor (RFC, Jan 2026). Seine
ursprüngliche GitHub-Heimat ging im August 2026 auf 404 und die Multi-Vendor-Dynamik
dahinter ist verblasst, aber die Spezifikation und das Schema sind weiterhin unter
agent-trace.dev auflösbar, eingefroren bei v0.1.0. Seit v0.3.9 emittiert
selvedge export --format agent-trace Agent-Trace-v0.1.0-Datensätze und
selvedge import --format agent-trace liest sie zurück — ein portables, dokumentiertes
Austauschformat für Datei/Zeilen-KI-Attribution, mit Begründung und Entitäts-Herkunft in den
dev.selvedge-Metadaten jedes Datensatzes. Die Zuordnung steht in
docs/agent-trace-interop.md; Selvedge
bündelt das Schema und hat keine Laufzeitabhängigkeit vom Upstream-Projekt.
Schnellstart
Claude Code — das Plugin installieren (empfohlen)
Zwei Befehle, innerhalb von Claude Code. Kein vorheriges pip install — das Plugin
startet den Server selbst über uvx (oder pipx):
/plugin marketplace add masondelan/selvedge
/plugin install selvedge@selvedgeDas ist die gesamte agentenorientierte Oberfläche in einem Schritt:
der MCP-Server — 8 Tools (
log_change,prior_attempts,blame,diff,history,changeset,search,stale_decisions);eine Skill, die dem Agenten sagt, wann er sie aufrufen soll — vor dem Bearbeiten einer verfolgten Entität, nach jeder substanziellen Änderung;
der PreToolUse-Durchsetzungs-Hook — Schema-/Migrations-Änderungen werden blockiert, bis
prior_attemptsin dieser Sitzung geprüft wurde, mit der früheren Begründung in der Blockierungsnachricht;Slash-Befehle —
/selvedge:status,/selvedge:blame <entity>,/selvedge:history,/selvedge:prior-attempts <entity>.
Der Speicher (.selvedge/selvedge.db) erstellt sich selbst bei der ersten protokollierten
Änderung. Zwei optionale Extras bleiben CLI-seitig: der Post-Commit-Hook, der jedes Ereignis
mit seinem Commit-Hash stempelt (selvedge install-hook), und — falls du den
selvedge-Befehl auf deinem eigenen Shell-PATH haben möchtest — pip install selvedge,
das der Launcher dann uvx für eine exakt gepinnte Version vorzieht.
Plugin oder
selvedge setupfür Claude Code? Wähle eines. Beide verdrahten den MCP- Server; beide auszuführen registriert ihn doppelt. Das Plugin ist der leichtere Weg und der, der sich selbst aktualisiert. Wenn du das Plugin nutzt und nur die Post-Commit-Commit-Hash-Stempelung möchtest, führeselvedge install-hookseparat aus.
Jeder andere MCP-Client — selvedge setup
Cursor, Copilot, Windsurf, Codex CLI, Gemini CLI und der Rest:
pip install selvedge
cd your-project
selvedge setupDas war's. selvedge setup ist ein interaktiver Assistent: Er erkennt, welche KI-
Tools du hast (Claude Code, Cursor, Copilot), schreibt den MCP-Eintrag in die
Konfiguration jedes einzelnen, legt den kanonischen Agenten-Anweisungsblock in die
Prompt-Datei deines Projekts (CLAUDE.md / .cursorrules /
copilot-instructions.md), installiert den PreToolUse-Durchsetzungs-Hook in
.claude/settings.json (nur Claude Code — blockiert Schema-/Migrations-Änderungen,
bis prior_attempts geprüft wurde; --skip-enforcement-hook zum
Opt-out), führt selvedge init aus und installiert den Post-Commit-Hook. Jede
modifizierte Datei erhält eine .bak-Sicherung neben sich, bevor eine Änderung die
Platte erreicht. Eine erneute Ausführung ist ein No-op.
Für CI-Bootstrap oder devcontainer.json postCreateCommand:
selvedge setup --non-interactive --yesDie Verdrahtung verifizieren — öffne ein zweites Terminal im selben Projekt:
selvedge watchNimm eine beliebige Änderung in deinem KI-Tool vor — füge eine Spalte hinzu, benenne eine
Funktion um, füge eine Env-Var hinzu. selvedge watch sollte das neue Ereignis innerhalb
einer Sekunde ausgeben, nachdem der Agent log_change aufgerufen hat. Wenn nichts
ankommt, führe selvedge doctor für einen Ein-Befehl-Health-Check aus, der dir sagt,
welcher Schritt stillschweigend kaputt ist.
Deine Historie abfragen:
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 CSVWenn du den Assistenten nicht ausführen möchtest, die vier manuellen Schritte, die er automatisiert:
1. In deinem Projekt initialisieren
cd your-project
selvedge init2. Den MCP-Server registrieren
Selvedge ist ein standardmäßiger Stdio-MCP-Server und funktioniert daher mit jedem MCP- Client — Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI und mehr. Siehe Funktioniert mit jedem MCP-Client für die genaue Konfiguration pro Client. Für Claude Code:
claude mcp add selvedge -- selvedge-server3. Deinem Agenten sagen, dass er es nutzen soll
selvedge prompt --install CLAUDE.mdRichte --install auf die Prompt-Datei, die dein Client liest — der Block
selbst ist über alle Clients hinweg identisch:
Client | Promptdatei |
Claude Code |
|
Codex CLI (and other |
|
Cursor |
|
Gemini CLI |
|
Dadurch wird der kanonische Agent-Anweisungsblock installiert, der mit Sentinel-Klammern
(<!-- selvedge:start --> / <!-- selvedge:end -->) versehen ist, sodass zukünftige
--install-Aufrufe den eingeklammerten Bereich aktualisieren, ohne etwas anderes in der Datei zu stören. Oder per Pipe:
selvedge prompt | tee -a CLAUDE.mdLieber kopieren und einfügen? Derselbe Block ist auf der Website nur einen Klick entfernt: selvedge.sh/prompt-block — mit einem Kopier-Button und Hinweisen dazu, was Ihr Agent damit macht.
4. Installieren Sie den Post-Commit-Hook
selvedge install-hookDas sind dieselben vier Schritte, die der Assistent ausführt.
Funktioniert mit jedem MCP-Client
Selvedge ist ein standardmäßiger stdio-MCP-Server — sein Startbefehl ist
selvedge-server, der von pip install selvedge in Ihren PATH aufgenommen wird. Jeder
MCP-fähige Client kann ihn ausführen. Wählen Sie Ihren:
claude mcp add selvedge -- selvedge-serverOder committen Sie eine projektweite .mcp.json, damit Ihr gesamtes Team sie erhält:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Dokumentation: https://code.claude.com/docs/en/mcp
.cursor/mcp.json (Projekt) oder ~/.cursor/mcp.json (global):
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Cursors neuere Schema-Version akzeptiert auch ein explizites "type": "stdio"; die
command-nur-Form funktioniert ebenfalls (Cursor leitet stdio aus command ab).
Dokumentation: https://cursor.com/docs/mcp
~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Windsurf lädt die Datei heiß neu — kein Neustart erforderlich. Die In-App-Schaltfläche Plugins → View raw config öffnet die genaue Datei, die Cascade liest. Dokumentation: https://docs.windsurf.com/windsurf/cascade/mcp
~/.codex/config.toml:
[mcp_servers.selvedge]
command = "selvedge-server"Oder führen Sie codex mcp add selvedge -- selvedge-server aus.
Dokumentation: https://developers.openai.com/codex/config-reference
~/.gemini/settings.json (oder .gemini/settings.json pro Projekt):
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Oder führen Sie gemini mcp add -s user selvedge selvedge-server aus.
Dokumentation: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
Die meisten Clients teilen dieselbe JSON-Struktur — richten Sie Ihren darauf aus:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Wenn selvedge-server nicht gefunden wird, verwenden Sie seinen absoluten Pfad (which selvedge-server).
So funktioniert es
Selvedge läuft als MCP-Server. KI-Agenten in Tools wie Claude Code rufen Selvedges Tools während ihrer Arbeit auf — und protokollieren strukturierte Änderungsereignisse in einer lokalen SQLite-Datenbank.
Jedes Ereignis erfasst:
Was sich geändert hat (Entitätspfad, Änderungstyp, Diff)
Wann (Zeitstempel)
Wer (Agent, Sitzungs-ID)
Warum (Begründung — aus dem Kontext des Agenten im Moment erfasst)
Wo (Git-Commit, Projekt)
Das Diff ist Sache von git. Das Warum ist Sache von Selvedge.
Selvedge verfolgt seine eigene Geschichte
Dieses Repository nutzt Selvedge selbst: Seine .selvedge/selvedge.db ist eingecheckt, sodass
ein frischer Klon mit Selvedges eigener Warum-Historie ausgeliefert wird. Klonen Sie es und fragen Sie, warum sich ein Teil von Selvedge geändert hat:
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 addedJedes Ereignis wurde von den Agenten protokolliert, die Selvedge gebaut haben — dieselben
log_change-Aufrufe, die diese README auch von Ihnen in Ihrem eigenen Projekt erwartet.
Konventionen für Entitätspfade
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 variablePräfixabfragen funktionieren überall: users gibt users, users.email,
users.created_at und jede andere Entität unter dem Namensraum users. zurück.
MCP-Tools
Wenn Selvedge als MCP-Server verbunden ist, stellt es Folgendes bereit:
Tool | Beschreibung |
| Zeichnet ein Änderungsereignis mit Entität, Diff und Begründung auf. |
| Verlauf für eine Entität oder einen Entitätspräfix, jede Zeile mit |
| Letzte Änderung + Kontext für eine exakte Entität, plus den abgeleiteten Entscheidungs- |
| Gefilterter Verlauf über alle Entitäten |
| Alle Ereignisse, gruppiert unter einem benannten Feature-/Task-Slug |
| Volltextsuche über alle Ereignisse |
| Frühere Änderungsversuche an einer Entität + abgeleitetes Ergebnis (versucht → zurückgenommen → erneut geöffnet) — vor dem Bearbeiten aufrufen. Optionale |
| Entscheidungen, die zur Überarbeitung anstehen: nach ihrem |
CLI-Referenz
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]Alle Lese-Befehle unterstützen --json für maschinenlesbare Ausgabe.
Relative Zeit in --since:
15m→ letzte 15 Minuten (m= Minuten)24h→ letzte 24 Stunden7d→ letzte 7 Tage5mo→ letzte 5 Monate (moodermon= Monate)1y→ letztes Jahr
Nicht interpretierbare Eingaben (z. B. --since yesterday) beenden mit einer klaren Fehlermeldung,
statt stillschweigend leere Ergebnisse zurückzugeben. ISO-8601-Zeitstempel
werden ebenfalls akzeptiert und auf UTC normalisiert.
Konfiguration
Methode | Format | Beispiel |
Umgebungsvariable |
| Überschreibung pro Sitzung |
Projekt-Init |
| Erstellt |
Globaler Fallback |
| Wird verwendet, wenn keine Projekt-DB gefunden wird |
Hook-Watch-Globs |
|
|
Projekteinstellungen |
| Siehe Schlüsselliste unten — Aufbewahrung, Größenbegrenzungen, Redaktionsmuster |
Globale Einstellungen |
| Gleiche Schlüssel; die Projektdatei gewinnt, wenn beide einen setzen |
Hook-Umgehung |
| Deaktiviert den PreToolUse-Durchsetzungs-Hook für die Shell |
Semantisches Extra |
| Aktiviert |
.selvedge/config.toml
Jeder Schlüssel ist optional; eine fehlende Datei bedeutet die untenstehenden Standardwerte. Die Rangfolge ist
CLI-Flag → Umgebungsvariable → Projekt-.selvedge/config.toml → globale
~/.selvedge/config.toml → Standard. SELVEDGE_DB ist die eine Ausnahme: Sie
gewinnt immer bei der Datenbankauflösung, weil die Konfigurationsdatei durch die Auflösung dieses Pfads gefunden wird. selvedge doctor gibt den effektiven Wert und den Schritt aus, der ihn für jede Einstellung erzeugt hat.
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"]Jeder Schlüssel hat auch eine Umgebungsüberschreibung (SELVEDGE_DIFF_BYTES,
SELVEDGE_RETENTION_DAYS_EVENTS, …).
Erfasste Absicht in einem Pull-Request überprüfen
.selvedge/selvedge.db ist eine SQLite-Datei, daher erscheint die darin enthaltene Begründung nicht in einem Diff. Exportieren Sie eine Markdown-Zusammenfassung daneben und committen Sie beide:
selvedge export --format markdown -o .selvedge/DECISIONS.md
git add .selvedge/Die Zusammenfassung ist nach Entität gruppiert, mit zurückgenommenen Entscheidungen zuerst, und sie ist deterministisch — eine erneute Generierung ohne neue Ereignisse erzeugt ein Diff mit null Zeilen, sodass sie überprüfbar bleibt, statt zu Rauschen zu werden, das jeder überspringt. Überschriftenanker leiten sich vom Entitätspfad ab, sodass Links hinein auch bei Wachstum funktionieren. Generieren Sie sie im selben Commit wie den Code neu oder aus einem Pre-Commit-Hook.
Abdeckungsprüfung
Fragen Sie sich, wie oft Ihr Agent tatsächlich log_change aufruft? Zwei Möglichkeiten zur Überprüfung:
# Quick summary in the terminal
selvedge stats
# Cross-reference against git commits
python scripts/coverage_check.py --since 30dDas Abdeckungsskript vergleicht Ihr Git-Log mit Selvedge-Ereignissen und zeigt,
welche Commits zugehörige Änderungsereignisse haben. Niedrige Abdeckung bedeutet normalerweise, dass der System-Prompt gestärkt werden muss — siehe docs/fallbacks.md für Anleitungen.
In der CI (GitHub Action)
Dieselbe Prüfung ist als Selvedge Coverage Check-Composite-Action enthalten, sodass Sie die Agent-Abdeckung bei jedem Push verfolgen können — und optional den Build fehlschlagen lassen, wenn sie sinkt:
# .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 onlySie schreibt eine Abdeckungszusammenfassung in die Job-Zusammenfassung und stellt coverage-ratio, covered und total als Schritt-Ausgaben bereit. Die Action kreuzreferenziert Ihre Git-Historie mit dem Selvedge-Ereignisprotokoll, daher benötigt der Runner die .selvedge/selvedge.db des Projekts (committen Sie sie oder stellen Sie sie vor diesem Schritt wieder her) und die vollständige Git-Historie (fetch-depth: 0). Eingaben: since, window, limit, fail-under, selvedge-version, python-version, working-directory, db-path.
Mitwirken
git clone https://github.com/masondelan/selvedge
cd selvedge
pip install -e ".[dev]"
pytestSiehe CLAUDE.md für Architekturdetails und die Phasen-Roadmap.
Lizenz
MIT — siehe LICENSE.
Available Tools
8 toolsblameBlame an entityARead-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.
Inputs: entity_path (required). Returns: id, diff, agent, error, +17 more
changesetGet a changesetARead-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."
Inputs: changeset_id (required). Returns: result
diffDiff an entity's historyARead-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.
Inputs: entity_path (required), limit. Returns: result
historyBrowse historyARead-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.
Inputs: limit, since, project, entity_path, +1 more. Returns: result
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.
Inputs: change_type (required), entity_path (required), diff, agent, +12 more. Returns: id, error, status, warnings, +2 more
prior_attemptsPrior attempts on an entityARead-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.
Inputs: fuzzy, limit, description, entity_path, +2 more. Returns: result
searchSearch eventsARead-onlyIdempotent
Full-text search across entity paths, diffs, reasoning, and agents.
Useful for questions like 'what changes were made for the billing feature?', 'which columns were added by cursor?', or 'show everything related to authentication'.
Inputs: query (required), limit. Returns: result
stale_decisionsStale decisions due for revisitARead-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.
Inputs: agent, limit, project, entity_path. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
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.'
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.
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.
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
Related MCP Connectors
One searchable history across every AI coding tool, with secret scanning and a shared task board.
Shared, scoped, reviewable team memory for AI coding agents.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThe shared AI context engine for git — save, search, and share the reasoning behind code changes. Captures the why behind every commit and slide on PRs for coding agents.MIT
- AlicenseBqualityBmaintenancePersistent memory and session intelligence for AI coding assistants. Auto-tracks mistakes, decisions, and context via hooks. Mines your full session history for patterns, predictions, and cross-session search.2116MIT
- AlicenseAqualityAmaintenanceLocal-first memory layer for AI coding agents — captures issues, attempts, fixes, and decisions, and warns at git commit before you repeat a mistake.19978 PyPI877MIT
- AlicenseNot gradedqualityDmaintenanceProvides a memory layer for AI coding agents with Git-powered version control, enabling automatic tracking of prompts, context, and code diffs.194MIT