Skip to main content
Glama
deenesjakoruzh
masondelan

Selvedge

by masondelan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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 auch SELVEDGE_DESTRUCTIVE=1. Keines allein reicht, weil --yes in 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 in selvedge stats.

  • Warnungen vor Geheimnis-Mustern bei log_change, erweiterbar über redaction_patterns, plus eine doctor-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 setup kann keine Teile deiner CLAUDE.md mehr 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 — prior_attempts liefert versucht → zurückgenommen → wieder geöffnet

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

OpenLore

Bereinigt — rejected ist ein inaktiver Status, der nach jedem Entscheidungs-Sync aus dem abfragbaren Speicher entfernt wird (die Annotation überlebt im synchronisierten Spec-Markdown)

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

AgentDiff (sunilmallya)

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

AgentDiff (codeprakhar25)

Keine

ed25519-signierte Cross-Agent-Herkunft

Zeile

Per-Agent-Editor-Hooks + Git-Hooks (Signatur beim Commit)

Keine

Signierte Traces in Git-Refs

Origin

Keine — rework markiert zurückgenommenen KI-Code nachträglich, ohne Begründung

Prompt-Belege, live pro Turn erfasst

Zeile

Agent-Lifecycle-Hooks + Git-Post-Commit-Hook

Keine

Git-Notes + Sessions-Branch

Git AI

Keine

Attributions-Metadaten

Zeile

Agent-aufgerufener Checkpoint → Git-Notes beim Commit

Keine

Git-Notes

BlamePrompt

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@selvedge

Das 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_attempts in 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 setup fü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ühre selvedge install-hook separat aus.

Jeder andere MCP-Client — selvedge setup

Cursor, Copilot, Windsurf, Codex CLI, Gemini CLI und der Rest:

pip install selvedge
cd your-project
selvedge setup

Das 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 --yes

Die Verdrahtung verifizieren — öffne ein zweites Terminal im selben Projekt:

selvedge watch

Nimm 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 CSV

Wenn du den Assistenten nicht ausführen möchtest, die vier manuellen Schritte, die er automatisiert:

1. In deinem Projekt initialisieren

cd your-project
selvedge init

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

3. Deinem Agenten sagen, dass er es nutzen soll

selvedge prompt --install CLAUDE.md

Richte --install auf die Prompt-Datei, die dein Client liest — der Block selbst ist über alle Clients hinweg identisch:

Client

Promptdatei

Claude Code

CLAUDE.md

Codex CLI (and other AGENTS.md-aware tools)

AGENTS.md

Cursor

.cursor/rules/selvedge.md (or legacy .cursorrules)

Gemini CLI

GEMINI.md

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

Lieber 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-hook

Das 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-server

Oder 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 added

Jedes 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 variable

Prä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

log_change

Zeichnet ein Änderungsereignis mit Entität, Diff und Begründung auf. rename_from + change_type="rename" zeichnet das duale Ereignismuster für Umbenennungen auf; change_type="supersede" öffnet eine zurückgenommene Entscheidung erneut (append-only); optionales constraint / stale_when hält das Prinzip der Entscheidung und ihre Ungültigkeitsbedingung abfragbar

diff

Verlauf für eine Entität oder einen Entitätspräfix, jede Zeile mit superseded_by annotiert

blame

Letzte Änderung + Kontext für eine exakte Entität, plus den abgeleiteten Entscheidungs-status (aktiv / zurückgenommen / erneut geöffnet)

history

Gefilterter Verlauf über alle Entitäten

changeset

Alle Ereignisse, gruppiert unter einem benannten Feature-/Task-Slug

search

Volltextsuche über alle Ereignisse

prior_attempts

Frühere Änderungsversuche an einer Entität + abgeleitetes Ergebnis (versucht → zurückgenommen → erneut geöffnet) — vor dem Bearbeiten aufrufen. Optionale fuzzy-Abfrage fügt semantisch ähnliche Datensätze hinzu (benötigt das semantic-Extra; fällt auf Teilstring zurück)

stale_decisions

Entscheidungen, die zur Überarbeitung anstehen: nach ihrem revisit_after und noch aktiv in Verwendung (flag="revisit_due"), oder deren stale_when-Bedingung mit einer späteren Änderung übereinstimmte (flag="review_suggested")

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 Stunden

  • 7d → letzte 7 Tage

  • 5mo → letzte 5 Monate (mo oder mon = 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

SELVEDGE_DB=/path/to/db

Überschreibung pro Sitzung

Projekt-Init

selvedge init

Erstellt .selvedge/selvedge.db im aktuellen Arbeitsverzeichnis

Globaler Fallback

~/.selvedge/selvedge.db

Wird verwendet, wenn keine Projekt-DB gefunden wird

Hook-Watch-Globs

.selvedge/config.toml

[hook]watch_globs = ["**/migrations/**", "db/**/*.sql"] — ersetzt die Standard-Schema-/Migrations-Globs des Durchsetzungs-Hooks

Projekteinstellungen

.selvedge/config.toml

Siehe Schlüsselliste unten — Aufbewahrung, Größenbegrenzungen, Redaktionsmuster

Globale Einstellungen

~/.selvedge/config.toml

Gleiche Schlüssel; die Projektdatei gewinnt, wenn beide einen setzen

Hook-Umgehung

SELVEDGE_HOOK_DISABLE=1

Deaktiviert den PreToolUse-Durchsetzungs-Hook für die Shell

Semantisches Extra

pip install "selvedge[semantic]"

Aktiviert selvedge index + prior-attempts --fuzzy (lokale model2vec-Einbettungen, ~30 MB; der Kern hängt nie davon ab)

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

Das 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 only

Sie 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]"
pytest

Siehe CLAUDE.md für Architekturdetails und die Phasen-Roadmap.

Lizenz

MIT — siehe LICENSE.

Available Tools

8 tools
blameBlame an entityA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
entity_pathYesExact entity path (no prefix matching). Examples: 'users.email', 'src/auth.py::login', 'env/STRIPE_SECRET_KEY'.

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
diffYes
agentYes
errorYes
statusYes
projectYes
metadataYes
reasoningYes
timestampYes
constraintYes
git_commitYes
session_idYes
stale_whenYes
supersedesYes
change_typeYes
entity_pathYes
entity_typeYes
changeset_idYes
expires_whenYes
revisit_afterYes
superseded_byYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate safe read-only idempotent operation. The description adds value by detailing return fields (status, superseded_by) and error handling behavior (returns error object with isError: false). No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short paragraphs, no fluff. The first sentence immediately states the core purpose. Every sentence adds necessary context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a single parameter, existing output schema, and comprehensive annotations, the description covers the tool's functionality, return data, and error case fully and clearly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter with 100% schema coverage. The description adds the constraint 'exact entity path (no prefix matching)' and provides examples, enhancing the schema's description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves the most recent change to an entity, likening it to git blame for semantic entities. It distinguishes from siblings like history or diff by focusing on the latest change and including decision state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool does and notes error behavior when no history exists. It lacks explicit guidance on when not to use or alternatives, but the purpose is clear enough for correct selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

changesetGet a changesetA
Read-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."

ParametersJSON Schema
NameRequiredDescriptionDefault
changeset_idYesThe changeset identifier (the same slug or UUID passed to `log_change`'s changeset_id parameter). Examples: 'add-stripe-billing', 'fix-auth-redirect'.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive. Description adds ordering (oldest first) and specific error format, going beyond annotations without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each with clear purpose. No wasted words. First sentence states what the tool does, second gives usage context and error handling.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple single-parameter tool with full schema coverage and an output schema, the description sufficiently covers ordering, error condition, and intended use. No gaps identified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and fully describes the changeset_id parameter. Description adds no new parameter semantics beyond what the schema provides, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'All events that share a changeset_id, oldest first.' It specifies the resource (events) and ordering, distinguishing it from siblings like 'history' (likely broader) and 'search' (different target).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use to reconstruct the full scope of a feature or task across multiple entities,' providing clear context. Also describes error behavior for empty changesets. Lacks explicit when-not or alternative comparisons.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

diffDiff an entity's historyA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of events to return.
entity_pathYesEntity path, or a DOTTED prefix of one: 'users' also covers 'users.email'. Not a raw string prefix — 'src/' matches nothing, and 'src/auth.py' does not cover 'src/auth.py::login'.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context: newest-first ordering, dotted-prefix matching scope, and the derived `superseded_by` id with empty-string semantics for the latest event. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded: the first sentence gives the core purpose, and the second provides high-value examples of prefix matching and derived data. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema and safety annotations, the description sufficiently covers the essential behavior: ordering, prefix semantics, and the derived superseded_by trail. It does not discuss sibling-tool selection, but the core functionality is thoroughly described.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers both parameters fully (100% coverage), so the baseline is 3. The description restates prefix matching with an example but does not add new parameter-level semantics beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns change history for a codebase entity, newest first, and highlights unique behaviors like prefix matching and the derived `superseded_by` field. However, it does not explicitly differentiate from the similarly-named sibling tool `history`, so it stops short of full sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied: call this when you need a chronological change history for an entity, especially with prefix matching. But the description does not compare this tool to alternatives like `history` or `blame`, nor does it mention exclusions or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

historyBrowse historyA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of results.
sinceNoTime window — ISO 8601 datetime OR relative shorthand: '15m' (last 15 minutes), '24h' (last 24 hours), '7d' (last 7 days), '5mo' (last 5 months), '1y' (last year). 'm' means minutes; 'mo' or 'mon' means months. Unparseable values produce an error rather than silently returning empty results. Empty = all time.
projectNoFilter to a specific project/repository.
entity_pathNoFilter to an entity, or a DOTTED prefix of one ('users' also covers 'users.email'). Not a raw string prefix.
changeset_idNoFilter to a specific changeset (feature/task group).

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnly=true, idempotent=true, and destructive=false, so safety is covered. The description goes beyond by disclosing the error behavior for unparseable 'since' input, returning a JSON error array instead of silently returning empty results. This is valuable behavioral context not in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first states purpose and ordering, the second gives usage guidance and error handling. It is front-loaded, with no wasted words, and every sentence contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and the description covers purpose, filtering, ordering, and error behavior, the tool is fully specified for an agent. The description is complete for this 5-parameter optional-input tool without needing to explain return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed descriptions for each parameter, so the baseline is 3. The description adds minor value by explicitly stating these parameters can be combined, but it does not explain syntax or semantics beyond what the schema already provides. No compensation needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Filtered change history across all entities, newest first.' It uses a specific verb ('browse' implicitly via 'history') and resource ('all entities'), and the 'newest first' ordering adds precision. This distinguishes it from siblings like log_change, diff, and search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance on how to combine filter parameters ('since', 'entity_path', 'project', 'changeset_id') to scope results. It does not explicitly mention when not to use this tool or name alternatives, but the usage context is clear enough for an agent to know when to invoke it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
diffNoThe actual change — SQL migration text, code diff, or a human-readable description of what changed. Optional but strongly recommended for non-trivial changes.
agentNoName/ID of the AI agent making the change (e.g. 'claude-code', 'cursor', 'copilot', 'human').
projectNoRepository or project name. Useful when one DB tracks multiple projects.
reasoningNoWhy the change was made. Include the user's original request, the problem being solved, or any context that won't be obvious from the diff alone. Good example: 'User asked to add 2FA — needs phone number to send SMS verification codes.' Avoid generic placeholders like 'user request' or 'done' — these are flagged by the quality validator and returned in `warnings`.
constraintNoOptional: the testable principle behind the decision, kept queryable (e.g. 'card data in our own DB = PCI scope').
git_commitNoThe git commit hash this change will land in. Can be backfilled later via `selvedge backfill-commit` or the post-commit hook.
session_idNoThe agent session or conversation ID, if available.
stale_whenNoOptional: what would invalidate this decision (e.g. 'payment provider changed'). stale_decisions matches it against later events and flags 'review suggested' — surfacing only.
supersedesNoId of the prior event this change overrides; only valid with change_type='supersede'. Empty auto-links the entity's most recent removal event (remove/delete/index_remove/revert/reject) — so after a standalone rejection it re-opens the rejection. Append-only — the old verdict is never edited, just derived as superseded.
change_typeYesWhat kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate, revert (tried and rolled back), reject (considered and decided against, without writing the change), supersede (re-open a reverted decision). Invalid values are rejected — pick the closest match.
entity_pathYesDot/slash-notation path to the entity. Required and non-empty. Examples: 'users.email' (DB column), 'users' (DB table), 'src/auth.py::login' (function in file), 'src/auth.py' (file), 'api/v1/users' (API route), 'deps/stripe' (dependency), 'env/STRIPE_SECRET_KEY' (env variable).
entity_typeNoCategory of entity. One of: column, table, file, function, class, endpoint, dependency, env_var, index, schema, config, other. Unknown values are coerced to 'other'.other
rename_fromNoThe entity's previous path, when this change is a rename. Set it together with change_type='rename' and put the NEW path in entity_path. Selvedge records the dual-event rename pattern: a 'rename' event on the old path and a 'create' event on the new path whose metadata.renamed_from points back to the old one, so blame/diff/prior_attempts on the new path still see the history. Leave empty for any non-rename change.
changeset_idNoOptional grouping ID for related changes that belong to the same feature or task. Use a short slug like 'add-stripe-billing'. All events sharing a changeset_id can be queried together via the `changeset` tool.
expires_whenNoOptional machine-checkable expiry condition for this decision. Closed grammar, validated at write time: 'library:NAME>=VERSION' (revisit when the named dependency reaches a version, e.g. 'library:django>=5.0'), 'entity:PATH:changes' (revisit when that entity next changes, e.g. 'entity:users.email:changes'), 'date:ISO' (revisit on a date, e.g. 'date:2027-01-01'), or 'manual:LABEL' (opaque label for human review; never auto-fires). `stale_decisions` evaluates these from local state — no network, no LLM — and flags 'expired' with the pattern that fired. Values outside the grammar are rejected.
revisit_afterNoOptional revisit date for an architectural decision (table, schema, dependency, config). An ISO date OR a relative offset from this event's timestamp (e.g. '90d', '6mo'). `stale_decisions` surfaces it once it passes, if the entity is still in active use. Leave empty otherwise.

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
errorYes
statusYes
warningsYes
timestampYes
supersedesYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations carry near-zero information (all false except openWorldHint), so the description carries the full burden. It comprehensively discloses: the warnings array on quality-validator failure, the exact error shape on validation failure, the dual-event rename behavior, supersede auto-linking, and append-only semantics. No contradiction with annotations (readOnlyHint=false correctly implies a write).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long, but every section earns its place given the complexity — headers ('Renames:', 'Rejections:', 'Superseding a reverted decision:') with code examples make it scannable. Slightly verbose in repeating rename semantics already in the schema's rename_from field, but organized enough that the density is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Comprehensive for a 16-parameter write tool with 5 complex change_type workflows. The description covers all change types, the validation grammar, failure/error shapes, examples for each major flow, and the output schema exists. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, giving a baseline of 3, but the description adds genuine orchestration semantics beyond the schema: rename's dual-event pattern (rename on old path + create on new path with metadata.renamed_from), the reject naming requirement ('name what was rejected AND what was chosen instead'), and that empty supersedes auto-links the most recent removal event. This is behavioral glue the schemas don't spell out.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'Record a change to a codebase entity' — and immediately distinguishes itself: call it after a meaningful change, while siblings diff/blame/history/prior_attempts are read surfaces. An agent can clearly separate it from the sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use for each change_type: 'Call this immediately after making any meaningful change,' with dedicated workflows for rename, reject, revert, and supersede. Names why reject is preferable to re-deriving dead ends ('the next agent's prior_attempts query finds it as a high-confidence row') and why supersede beats editing history. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

prior_attemptsPrior attempts on an entityA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
fuzzyNoOptional semantic query: also return attempts on entities whose prior reasoning is similar to this text — catches renames (payment_token vs card_token). Rows are labeled match_type='fuzzy' with a similarity score; without the selvedge[semantic] extra it falls back to substring matching and says so in a leading note row.
limitNoMaximum number of results.
descriptionNoFree-text description of what you're about to do, when you don't have an exact entity_path. Matched as a substring against prior reasoning, diffs, and entity paths. Provide this OR `entity_path` (entity_path takes precedence if both are given).
entity_pathNoThe entity you're about to change. Exact path with prefix matching — 'users' also covers 'users.email'. Examples: 'src/auth.py::login', 'users.email', 'env/STRIPE_SECRET_KEY'. Provide this OR `description`.
min_confidenceNoConfidence floor. 'proximity_high' (default) returns the high-signal rows: attempts closed by an explicit revert/reject (confidence 'exact' — always clears this floor, including standalone rejections) plus attempts reverted within the window. Pass 'proximity_low' to also see the noisy tail (still-active changes and far-apart reverts).proximity_high
window_minutesNoProximity window in minutes for the add->remove revert heuristic — the tiebreaker for IMPLICIT removal types only. An attempt removed within this many minutes is 'proximity_high'; beyond it, 'proximity_low'. Attempts closed by an explicit revert/reject are 'exact' regardless of the window. Default 10080 (7 days).

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description reinforces and expands this with 'Templated and deterministic — no LLM call; pull-only.' It discloses nuanced behaviors: conservative defaults, the meaning of outcome/confidence values, and that an empty list is the preferred normal answer. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but information-dense, with a sensible structure: core purpose, usage timing, outcome semantics, and confidence policy. Every sentence carries meaningful guidance, though some sections could be tightened. The front-loading is effective; the most important instruction appears early.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description covers purpose, usage timing, result semantics, confidence filtering, recall widening, and edge cases like standalone rejections and reopen events. The output schema exists and the description also explains return fields thoroughly. Nothing critical is missing for an agent to select and invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema itself documents all parameters. The description adds meaningful extra context, such as the default min_confidence behavior, how 'exact' rows clear the confidence floor, and the role of window_minutes as a tiebreaker for implicit removals. This goes beyond simple schema repetition, though it could have been slightly more parameter-by-parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's purpose: retrieving prior change attempts on an entity with inferred outcomes. It states a specific action context ('Call this BEFORE editing an entity') and distinguishes the data it returns. However, it does not explicitly differentiate itself from siblings like 'history' or 'changeset', so an agent must infer which tool covers which kind of history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs when to use the tool: before editing an entity, to avoid repeating a rejected approach. It also explains how to widen recall via min_confidence. However, it does not say when NOT to use it or name any alternative tool, so the usage guidance is strong on 'when' but missing exclusions and alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

stale_decisionsStale decisions due for revisitA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
agentNoOptional filter to the agent that logged the decision.
limitNoMaximum number of results.
projectNoOptional filter to a specific project/repository.
entity_pathNoOptional filter to a single entity or path prefix — 'users' also covers 'users.email'. Empty = every entity.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Even with annotations marking readOnly, deterministic, and non-destructive, the description adds substantial behavioral detail: no LLM call, no network, no automatic un-retiring, fallback to manual_review when dependency state is unobservable, and effects of later supersede events. This is far beyond what annotations alone convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than average, but the tool has complex deterministic rules and edge cases that warrant the detail. It is front-loaded with the core purpose and organized by flag type, followed by output fields, ordering, and guarantees. The output field enumeration is slightly redundant with the existing output schema, preventing a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with this complexity, the description is complete: it explains all three surfacing mechanisms, non-obvious edge cases like manual_review, output shape, ordering, filtering, and determinism guarantees. Combined with the rich annotations and output schema, an agent has everything needed to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline of 3 applies. The description mentions filtering by entity_path, project, or agent, which reinforces the schema but does not add much new semantic depth. It does not describe parameter formats beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Decisions due for a revisit,' then enumerates the three deterministic rules and their resulting flags. It clearly distinguishes this tool from siblings by emphasizing it is surfacing-only, deterministic, and local-state-based.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when results surface: expiry-based, date-based, and condition-based rules, with explicit caveats like 'pure age alone never surfaces' and 'manual:LABEL never auto-fires.' It does not explicitly name sibling alternatives for exclusion, but the behavioral specificity makes intended usage unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.3.14
    • Changedprior_attempts1 field changed
      • changedInput schema / properties / window_minutes / maximum
        Previous value: -1000New value: +10080
  2. 2 tool updates
    • Changedlog_change3 fields changed
      • changedInput schema / properties / change_type / description
        Previous value: -"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate, revert (tried and rolled back), supersede (re-open a reverted decision). Invalid values are rejected — pick the closest match."New value: +"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate, revert (tried and rolled back), reject (considered and decided against, without writing the change), supersede (re-open a reverted decision). Invalid values are rejected — pick the closest match."
      • addedInput schema / properties / expires_when
        Added value: +{
+  "default": "",
+  "description": "Optional machine-checkable expiry condition for this decision. Closed grammar, validated at write time: 'library:NAME>=VERSION' (revisit when the named dependency reaches a version, e.g. 'library:django>=5.0'), 'entity:PATH:changes' (revisit when that entity next changes, e.g. 'entity:users.email:changes'), 'date:ISO' (revisit on a date, e.g. 'date:2027-01-01'), or 'manual:LABEL' (opaque label for human review; never auto-fires). `stale_decisions` evaluates these from local state — no network, no LLM — and flags 'expired' with the pattern that fired. Values outside the grammar are rejected.",
+  "title": "Expires When",
+  "type": "string"
+}
      • changedInput schema / properties / supersedes / description
        Previous value: -"Id of the prior event this change overrides; only valid with change_type='supersede'. Empty auto-links the entity's most recent remove/delete. Append-only — the old verdict is never edited, just derived as superseded."New value: +"Id of the prior event this change overrides; only valid with change_type='supersede'. Empty auto-links the entity's most recent removal event (remove/delete/index_remove/revert/reject) — so after a standalone rejection it re-opens the rejection. Append-only — the old verdict is never edited, just derived as superseded."
    • Changedprior_attempts2 fields changed
      • changedInput schema / properties / min_confidence / description
        Previous value: -"Confidence floor. 'proximity_high' (default) returns only attempts that were clearly tried and then reverted within the window — the high-signal 'rejected before' cases. Pass 'proximity_low' to also see the noisy tail (still-active changes and far-apart reverts)."New value: +"Confidence floor. 'proximity_high' (default) returns the high-signal rows: attempts closed by an explicit revert/reject (confidence 'exact' — always clears this floor, including standalone rejections) plus attempts reverted within the window. Pass 'proximity_low' to also see the noisy tail (still-active changes and far-apart reverts)."
      • changedInput schema / properties / window_minutes / description
        Previous value: -"Proximity window in minutes for the add->remove revert heuristic. An attempt removed within this many minutes is 'proximity_high'; beyond it, 'proximity_low'. Default 10080 (7 days)."New value: +"Proximity window in minutes for the add->remove revert heuristic — the tiebreaker for IMPLICIT removal types only. An attempt removed within this many minutes is 'proximity_high'; beyond it, 'proximity_low'. Attempts closed by an explicit revert/reject are 'exact' regardless of the window. Default 10080 (7 days)."
  3. 5 tool updatesv0.3.11
    • Changeddiff2 fields changed
      • changedInput schema / properties / entity_path / description
        Previous value: -"Entity path or path prefix. Prefix matching is supported: 'users' returns history for the users table AND all its columns ('users.email', 'users.created_at', etc.). Use a more specific path to narrow the result."New value: +"Entity path, or a DOTTED prefix of one: 'users' also covers 'users.email'. Not a raw string prefix — 'src/' matches nothing, and 'src/auth.py' does not cover 'src/auth.py::login'."
      • addedInput schema / properties / limit / maximum
        Added value: +1000
    • Changedhistory2 fields changed
      • changedInput schema / properties / entity_path / description
        Previous value: -"Filter to a specific entity or path prefix."New value: +"Filter to an entity, or a DOTTED prefix of one ('users' also covers 'users.email'). Not a raw string prefix."
      • addedInput schema / properties / limit / maximum
        Added value: +1000
    • Changedprior_attempts2 fields changed
      • addedInput schema / properties / limit / maximum
        Added value: +1000
      • addedInput schema / properties / window_minutes / maximum
        Added value: +1000
    • Changedsearch1 field changed
      • addedInput schema / properties / limit / maximum
        Added value: +1000
    • Changedstale_decisions1 field changed
      • addedInput schema / properties / limit / maximum
        Added value: +1000
  4. 3 tool updatesv0.3.10
    • Changedblame6 fields changed
      • addedOutput schema / properties / constraint
        Added value: +{
+  "title": "Constraint",
+  "type": "string"
+}
      • addedOutput schema / properties / stale_when
        Added value: +{
+  "title": "Stale When",
+  "type": "string"
+}
      • addedOutput schema / properties / status
        Added value: +{
+  "title": "Status",
+  "type": "string"
+}
      • addedOutput schema / properties / superseded_by
        Added value: +{
+  "title": "Superseded By",
+  "type": "string"
+}
      • addedOutput schema / properties / supersedes
        Added value: +{
+  "title": "Supersedes",
+  "type": "string"
+}
      • changedOutput schema / required
        Previous value: -[
-  "id",
-  "timestamp",
-  "entity_type",
-  "entity_path",
-  "change_type",
-  "diff",
-  "reasoning",
-  "agent",
-  "session_id",
-  "git_commit",
-  "project",
-  "changeset_id",
-  "metadata",
-  "revisit_after",
-  "expires_when",
-  "error"
-]New value: +[
+  "id",
+  "timestamp",
+  "entity_type",
+  "entity_path",
+  "change_type",
+  "diff",
+  "reasoning",
+  "agent",
+  "session_id",
+  "git_commit",
+  "project",
+  "changeset_id",
+  "metadata",
+  "revisit_after",
+  "expires_when",
+  "supersedes",
+  "constraint",
+  "stale_when",
+  "superseded_by",
+  "status",
+  "error"
+]
    • Changedlog_change6 fields changed
      • changedInput schema / properties / change_type / description
        Previous value: -"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate. Invalid values are rejected — pick the closest match."New value: +"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate, revert (tried and rolled back), supersede (re-open a reverted decision). Invalid values are rejected — pick the closest match."
      • addedInput schema / properties / constraint
        Added value: +{
+  "default": "",
+  "description": "Optional: the testable principle behind the decision, kept queryable (e.g. 'card data in our own DB = PCI scope').",
+  "title": "Constraint",
+  "type": "string"
+}
      • addedInput schema / properties / stale_when
        Added value: +{
+  "default": "",
+  "description": "Optional: what would invalidate this decision (e.g. 'payment provider changed'). stale_decisions matches it against later events and flags 'review suggested' — surfacing only.",
+  "title": "Stale When",
+  "type": "string"
+}
      • addedInput schema / properties / supersedes
        Added value: +{
+  "default": "",
+  "description": "Id of the prior event this change overrides; only valid with change_type='supersede'. Empty auto-links the entity's most recent remove/delete. Append-only — the old verdict is never edited, just derived as superseded.",
+  "title": "Supersedes",
+  "type": "string"
+}
      • addedOutput schema / properties / supersedes
        Added value: +{
+  "title": "Supersedes",
+  "type": "string"
+}
      • changedOutput schema / required
        Previous value: -[
-  "id",
-  "timestamp",
-  "status",
-  "error",
-  "warnings"
-]New value: +[
+  "id",
+  "timestamp",
+  "status",
+  "error",
+  "warnings",
+  "supersedes"
+]
    • Changedprior_attempts1 field changed
      • addedInput schema / properties / fuzzy
        Added value: +{
+  "default": "",
+  "description": "Optional semantic query: also return attempts on entities whose prior reasoning is similar to this text — catches renames (payment_token vs card_token). Rows are labeled match_type='fuzzy' with a similarity score; without the selvedge[semantic] extra it falls back to substring matching and says so in a leading note row.",
+  "title": "Fuzzy",
+  "type": "string"
+}
  5. 4 tool updatesv0.3.8
    • Changedblame3 fields changed
      • addedOutput schema / properties / expires_when
        Added value: +{
+  "title": "Expires When",
+  "type": "string"
+}
      • addedOutput schema / properties / revisit_after
        Added value: +{
+  "title": "Revisit After",
+  "type": "string"
+}
      • changedOutput schema / required
        Previous value: -[
-  "id",
-  "timestamp",
-  "entity_type",
-  "entity_path",
-  "change_type",
-  "diff",
-  "reasoning",
-  "agent",
-  "session_id",
-  "git_commit",
-  "project",
-  "changeset_id",
-  "metadata",
-  "error"
-]New value: +[
+  "id",
+  "timestamp",
+  "entity_type",
+  "entity_path",
+  "change_type",
+  "diff",
+  "reasoning",
+  "agent",
+  "session_id",
+  "git_commit",
+  "project",
+  "changeset_id",
+  "metadata",
+  "revisit_after",
+  "expires_when",
+  "error"
+]
    • Changedlog_change2 fields changed
      • addedInput schema / properties / rename_from
        Added value: +{
+  "default": "",
+  "description": "The entity's previous path, when this change is a rename. Set it together with change_type='rename' and put the NEW path in entity_path. Selvedge records the dual-event rename pattern: a 'rename' event on the old path and a 'create' event on the new path whose metadata.renamed_from points back to the old one, so blame/diff/prior_attempts on the new path still see the history. Leave empty for any non-rename change.",
+  "title": "Rename From",
+  "type": "string"
+}
      • addedInput schema / properties / revisit_after
        Added value: +{
+  "default": "",
+  "description": "Optional revisit date for an architectural decision (table, schema, dependency, config). An ISO date OR a relative offset from this event's timestamp (e.g. '90d', '6mo'). `stale_decisions` surfaces it once it passes, if the entity is still in active use. Leave empty otherwise.",
+  "title": "Revisit After",
+  "type": "string"
+}
    • Addedprior_attempts
    • Addedstale_decisions
  6. 6 tool updatesv0.3.2
    • Changedblame2 fields changed
      • addedInput schema / properties / entity_path / description
        Added value: +"Exact entity path (no prefix matching). Examples: 'users.email', 'src/auth.py::login', 'env/STRIPE_SECRET_KEY'."
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "properties": {
+    "agent": {
+      "title": "Agent",
+      "type": "string"
+    },
+    "change_type": {
+      "title": "Change Type",
+      "type": "string"
+    },
+    "changeset_id": {
+      "title": "Changeset Id",
+      "type": "string"
+    },
+    "diff": {
+      "title": "Diff",
+      "type": "string"
+    },
+    "entity_path": {
+      "title": "Entity Path",
+      "type": "string"
+    },
+    "entity_type": {
+      "title": "Entity Type",
+      "type": "string"
+    },
+    "error": {
+      "title": "Error",
+      "type": "string"
+    },
+    "git_commit": {
+      "title": "Git Commit",
+      "type": "string"
+    },
+    "id": {
+      "title": "Id",
+      "type": "string"
+    },
+    "metadata": {
+      "additionalProperties": true,
+      "title": "Metadata",
+      "type": "object"
+    },
+    "project": {
+      "title": "Project",
+      "type": "string"
+    },
+    "reasoning": {
+      "title": "Reasoning",
+      "type": "string"
+    },
+    "session_id": {
+      "title": "Session Id",
+      "type": "string"
+    },
+    "timestamp": {
+      "title": "Timestamp",
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "timestamp",
+    "entity_type",
+    "entity_path",
+    "change_type",
+    "diff",
+    "reasoning",
+    "agent",
+    "session_id",
+    "git_commit",
+    "project",
+    "changeset_id",
+    "metadata",
+    "error"
+  ],
+  "title": "BlameResult",
+  "type": "object"
+}
    • Changedchangeset1 field changed
      • addedInput schema / properties / changeset_id / description
        Added value: +"The changeset identifier (the same slug or UUID passed to `log_change`'s changeset_id parameter). Examples: 'add-stripe-billing', 'fix-auth-redirect'."
    • Changeddiff3 fields changed
      • addedInput schema / properties / entity_path / description
        Added value: +"Entity path or path prefix. Prefix matching is supported: 'users' returns history for the users table AND all its columns ('users.email', 'users.created_at', etc.). Use a more specific path to narrow the result."
      • addedInput schema / properties / limit / description
        Added value: +"Maximum number of events to return."
      • addedInput schema / properties / limit / minimum
        Added value: +1
    • Changedhistory6 fields changed
      • addedInput schema / properties / changeset_id / description
        Added value: +"Filter to a specific changeset (feature/task group)."
      • addedInput schema / properties / entity_path / description
        Added value: +"Filter to a specific entity or path prefix."
      • addedInput schema / properties / limit / description
        Added value: +"Maximum number of results."
      • addedInput schema / properties / limit / minimum
        Added value: +1
      • addedInput schema / properties / project / description
        Added value: +"Filter to a specific project/repository."
      • addedInput schema / properties / since / description
        Added value: +"Time window — ISO 8601 datetime OR relative shorthand: '15m' (last 15 minutes), '24h' (last 24 hours), '7d' (last 7 days), '5mo' (last 5 months), '1y' (last year). 'm' means minutes; 'mo' or 'mon' means months. Unparseable values produce an error rather than silently returning empty results. Empty = all time."
    • Changedlog_change11 fields changed
      • addedInput schema / properties / agent / description
        Added value: +"Name/ID of the AI agent making the change (e.g. 'claude-code', 'cursor', 'copilot', 'human')."
      • addedInput schema / properties / change_type / description
        Added value: +"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate. Invalid values are rejected — pick the closest match."
      • addedInput schema / properties / changeset_id / description
        Added value: +"Optional grouping ID for related changes that belong to the same feature or task. Use a short slug like 'add-stripe-billing'. All events sharing a changeset_id can be queried together via the `changeset` tool."
      • addedInput schema / properties / diff / description
        Added value: +"The actual change — SQL migration text, code diff, or a human-readable description of what changed. Optional but strongly recommended for non-trivial changes."
      • addedInput schema / properties / entity_path / description
        Added value: +"Dot/slash-notation path to the entity. Required and non-empty. Examples: 'users.email' (DB column), 'users' (DB table), 'src/auth.py::login' (function in file), 'src/auth.py' (file), 'api/v1/users' (API route), 'deps/stripe' (dependency), 'env/STRIPE_SECRET_KEY' (env variable)."
      • addedInput schema / properties / entity_type / description
        Added value: +"Category of entity. One of: column, table, file, function, class, endpoint, dependency, env_var, index, schema, config, other. Unknown values are coerced to 'other'."
      • addedInput schema / properties / git_commit / description
        Added value: +"The git commit hash this change will land in. Can be backfilled later via `selvedge backfill-commit` or the post-commit hook."
      • addedInput schema / properties / project / description
        Added value: +"Repository or project name. Useful when one DB tracks multiple projects."
      • addedInput schema / properties / reasoning / description
        Added value: +"Why the change was made. Include the user's original request, the problem being solved, or any context that won't be obvious from the diff alone. Good example: 'User asked to add 2FA — needs phone number to send SMS verification codes.' Avoid generic placeholders like 'user request' or 'done' — these are flagged by the quality validator and returned in `warnings`."
      • addedInput schema / properties / session_id / description
        Added value: +"The agent session or conversation ID, if available."
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "properties": {
+    "error": {
+      "title": "Error",
+      "type": "string"
+    },
+    "id": {
+      "title": "Id",
+      "type": "string"
+    },
+    "status": {
+      "title": "Status",
+      "type": "string"
+    },
+    "timestamp": {
+      "title": "Timestamp",
+      "type": "string"
+    },
+    "warnings": {
+      "items": {
+        "type": "string"
+      },
+      "title": "Warnings",
+      "type": "array"
+    }
+  },
+  "required": [
+    "id",
+    "timestamp",
+    "status",
+    "error",
+    "warnings"
+  ],
+  "title": "LogChangeResult",
+  "type": "object"
+}
    • Changedsearch3 fields changed
      • addedInput schema / properties / limit / description
        Added value: +"Maximum number of results."
      • addedInput schema / properties / limit / minimum
        Added value: +1
      • addedInput schema / properties / query / description
        Added value: +"Search string (case-insensitive substring). Searches across entity_path, diff, reasoning, and agent fields. SQL LIKE wildcards (`_` and `%`) are escaped, so 'stripe_customer_id' matches the literal underscore rather than any single char."
  7. 6 tool updatesv0.3.1
    • First observedblame
    • First observedchangeset
    • First observeddiff
    • First observedhistory
    • First observedlog_change
    • First observedsearch
Deploy Server
Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

A4.2/5.0

Scored across 8 tools

Disambiguation4/5

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

Naming Consistency3/5

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.

Tool Count5/5

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.

Completeness5/5

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

ActivityActive
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Projectmem

    riponcm
    A
    license
    A
    quality
    A
    maintenance
    Local-first memory layer for AI coding agents — captures issues, attempts, fixes, and decisions, and warns at git commit before you repeat a mistake.
    17
    850
    MIT