Sitzungs-Graph

<!-- translations:start -->

English · 한국어 · 中文 · 日本語 · Русский · Español · Français

<!-- translations:end -->

Der Sitzungs-Graph von Tesserae verwandelt deine Claude Code / Codex-Konversationen über ein Projekt in erstklassige Knoten im typisierten Wissensgraphen, verknüpft mit den Dokumenten, die zur Sprache kamen. Nach einer Kompilierung kannst du tesserae ask "was haben wir über 3D Gaussian Splatting entschieden?" fragen und konkrete Insight / Decision / Question / TODO / Hypothesis / Takeaway-Knoten mit Provenienz zurück zur Sitzung erhalten, die sie hervorgebracht hat.

Funktionsweise

Zwei Durchgänge pro Sitzung:

1. Strukturell (immer aktiv, kein LLM). Liest die normalisierten HarnessSession-Datensätze, die tesserae sessions discover --import in .tesserae/harness_sessions/ schreibt. Für jede Sitzung wird ein Session-Umschlag-Knoten geprägt, discussed_in-Kanten von jedem Dokument emittiert, das der Agent geöffnet hat, und das vorhandene decisions-Feld in SessionDecision-Knoten umgewandelt.
2. LLM (opt-in, läuft wenn ANTHROPIC_API_KEY konfiguriert ist). Sendet die normalisierten Gesprächs-Turns (das metadata["turns"]-Feld — nicht die rohe Transkriptdatei) an Claude mit einem JSON-only Findings-Schema. Gibt sechs Arten von Findings zurück, jedes zitiert zurück zu bestimmten Turns und bestimmten Dok-Knoten-IDs im aktuellen Graphen. Zwischengespeichert nach content_hash + project_root_hash, sodass unveränderte Sitzungen den Aufruf bei der nächsten Kompilierung überspringen.

Zwei Wege, Sessions einzuspeisen: Batch vs. Live

Die obige Pipeline ist dieselbe, egal wie die Sessions ankommen. Was sich unterscheidet, ist wann sie entdeckt und kompiliert werden:

• Batch (manuell). Führe tesserae sessions discover --import und danach tesserae compile selbst aus. Am besten für einmalige Nachträge oder CI. Der Rest dieser Seite geht diesen Weg.
• Live (kontinuierlich). Lass die Engine das Projekt beobachten und neu kompilieren, während die Arbeit geschieht, damit der Graph frisch bleibt, ohne dass du daran denken musst, etwas auszuführen:
• Supervisor-Daemon — tesserae engine führt eine Single-Owner-asyncio-Schleife aus, die die konfigurierten Quellen beobachtet, einen Schwung von Edits zu genau einem Pipeline.run() zusammenfasst und automatisch neu kompiliert. Übergib --once für einen deterministischen Einzeldurchlauf oder --interval / --debounce, um das Zusammenfassen zu justieren. tesserae refresh führt dieselbe import → compile → vault-sync-Kette einmal in-process aus.
• Claude-Code-Plugin-Hooks — mit installiertem Plugin führt der SessionEnd-Hook beim Ende eines Gesprächs im Hintergrund import + compile aus, sodass die Erkenntnisse dieser Session zu Graph-Knoten für die nächste werden. Der SessionStart-Hook druckt beim Einstieg die aktuelle Graph-Zusammenfassung. Das kommt dem Erfassen von Sessions „während sie geschehen" am nächsten — ganz ohne manuellen discover/compile-Schritt.

Einrichtung

# Importiere die Sitzungen dieses Projekts in `.tesserae/harness_sessions/`. Filtert nach cwd, sodass nur Sitzungen, die innerhalb dieses Projekts liefen, importiert werden.
tesserae sessions discover --import

# Kompiliere. Der strukturelle Durchgang läuft kostenlos; der LLM-Durchgang läuft automatisch, wenn die `claude` CLI angemeldet ist — kein API-Schlüssel nötig.
tesserae compile

Um ohne Sitzungen zu kompilieren (z.B. auf einem Server ohne Harness-Historie):

tesserae compile --no-sessions

Um strukturell-only zu erzwingen (LLM-Aufruf überspringen, auch wenn ein Schlüssel gesetzt ist):

# Set compile_options.sessions_llm = false in .tesserae/config.json, then:
tesserae compile

Konfiguration

.tesserae/config.json akzeptiert einen sessions-Block:

{
  "sessions": {
    "enabled": true,
    "llm_enabled": "auto",
    "max_turns_per_chunk": 30,
    "model": "claude-sonnet-4-7-20251201",
    "include_doc_id_context": 200
  }
}

CLI-Flags überschreiben die Konfiguration. llm_enabled = "auto" (Standard) führt den LLM-Durchgang aus, wenn die claude CLI angemeldet ist oder ANTHROPIC_API_KEY gesetzt ist; ohne beides läuft nur der strukturelle Durchgang (kein Fehler, keine ausgehenden Aufrufe).

Abfrage

Zwei MCP-Tools werden zu den bestehenden Such-/Wiki-Tools hinzugefügt:

• list_sessions(since?, limit?) — Session-Umschläge für das aktive Projekt (id, started_at, title, Finding-Anzahl).
• find_session_findings(node_id, kinds?) — jeder von einer Sitzung abgeleitete Finding, der über discussed_in oder references mit node_id verknüpft ist, optional gefiltert auf insight / decision / question / todo / hypothesis / takeaway.

Aus der CLI:

tesserae sessions list
tesserae ask "what did we decide about extractor dedup?"

Datenschutz

• Ohne angemeldete claude CLI UND ohne ANTHROPIC_API_KEY (oder mit --sessions-llm=false) gibt es null ausgehende Netzwerkaufrufe. Nur der strukturelle Durchgang läuft.
• Wenn der LLM-Durchgang läuft, werden die vollständigen normalisierten Gesprächs-Turns für noch nicht zwischengespeicherte Sitzungen gesendet. Die Transkriptdatei selbst bleibt auf der Festplatte; nur die JSON-Ausgabe des LLM wird im Graphen und im Pro-Sitzung-Cache persistiert.
• Cache-Dateien leben in .tesserae/session_findings/<session_id>.findings.json mit sowohl einem content_hash als auch einem project_root_hash. Eine zwischen Projekten kopierte Cache-Datei wird beim Lesen abgelehnt — keine projektübergreifende Wiederholung.
• Sitzungen werden nach dem Laden durch session_matches_project gefiltert, sodass ein Transkript, dessen cwd ein Schwesterprojekt war, niemals Knoten im Graphen dieses Projekts produziert.

Vault-Layout

Findings werden unter dem Obsidian-Vault als eine Seite pro Finding gerendert, gruppiert nach Sitzung:

<vault>/
  sessions/
    <session-id-slug>/
      cache-findings-by-content-hash.md
      path-index-needs-basename-suppression.md
      ...

Benutzernotizen innerhalb des <!-- user-notes:start --> … <!-- user-notes:end -->-Blocks auf jeder Finding-Seite überleben eine Neukompilierung — derselbe Vertrag wie für jede andere Vault-Seite.

Fehlerbehebung

• Nach der Kompilierung erscheinen keine Session-Knoten. Hast du zuerst tesserae sessions discover --import ausgeführt? Der Kompilierungspfad konsumiert nur .tesserae/harness_sessions/; er scannt ~/.claude/projects/ NICHT automatisch (dieser Scan kann auf Maschinen mit Tausenden historischer Sitzungen Minuten dauern).
• LLM-Kostenbedenken. Der Cache bedeutet, dass jede Sitzung höchstens einmal pro content-hash an das LLM gesendet wird. Lange Sitzungen werden bei max_turns_per_chunk (Standard 30) mit 5-Turn-Überlappung in Chunks aufgeteilt. Um die Gesamtkosten zu begrenzen, senke max_turns_per_chunk, senke include_doc_id_context, oder setze --sessions-llm=false.
• Ein Finding zitiert eine nicht existierende Knoten-ID. Der Orchestrator validiert jede zitierte Referenz gegen den lebenden Dok-Graphen und verwirft unbekannte still. Wenn du die Warnung in den Logs siehst, hat das LLM eine Zitation halluziniert — die überlebenden Referenzen sind immer noch vertrauenswürdig.

Spezifikation

Das vollständige Design lebt in docs/superpowers/specs/2026-05-19-session-graph-extractor-design.md. Der Implementierungsplan ist docs/superpowers/plans/2026-05-19-session-graph-extractor-plan.md.