Tesserae v0.3.0 — Prosa-zu-Code-Verknüpfungen, polyglotter Code-Graph, Live-Sync

<!-- translations:start -->

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

<!-- translations:end -->

Veröffentlicht am 2026-05-24 · PyPI · GitHub-Release · pip install --upgrade tesserae==0.3.0

Tesserae 0.3.0 schließt den Kreis zwischen prosaischen Entscheidungen und den Code-Symbolen, die sie implementieren — und zwar über 21 Sprachen hinweg statt der nur Python umfassenden Grundlage aus v0.2.0. Das Release liefert drei additive Features ohne Breaking Changes: einen discusses-Edge-Pass, der typisierte Verknüpfungen von Session-Findings (SessionInsight, Decision, Hypothesis, Todo, Question, Takeaway) zu den passenden Code-Knoten erzeugt; einen tesserae project sync-code-Subbefehl, der den tree-sitter-basierten SQLite-Index von colbymchenry/codegraph in Tesseraes typisierten ResearchGraph importiert; sowie einen standardmäßig aktivierten Live-sync-code-SessionStart-Hook, der diesen Import frisch hält, während Sie Code bearbeiten. Zusammen machen sie Tesserae zum einzigen PKM-AI-Memory-Tool der Landschaft von 2026, bei dem „Was haben wir zu X entschieden?" sowohl die Entscheidungen als auch die Sessions, in denen sie getroffen wurden, und die genauen Funktionen / Klassen / Routes liefert, die sie umsetzen — über den polyglotten Stack hinweg, den ein echtes Forschungs-Repository tatsächlich nutzt.

Inhaltsverzeichnis:

1. MD0-Edges — Prosa mit Code-Symbolen verknüpfen (Feature H)
2. MD0 — CodeGraph-Adapter, 21 Sprachen
3. Live-sync-code-SessionStart-Hook (post-v0.3.0 auf MD0)
4. Upgrade von v0.2.0
5. Strategischer Kontext

1. discusses-Edges — Prosa mit Code-Symbolen verknüpfen (Feature H)

Was es ist

Ein opt-in Post-Compile-Pass, der jeden Session-Finding-Text nach Erwähnungen von Code-Symbolen durchsucht, die im Graph existieren, und einen typisierten discusses-Edge vom Finding zu jedem passenden Code-Knoten erzeugt. Die Quell-Kinds sind die sechs Session-Finding-Typen, die der Agent-Harness ausgibt — SessionInsight, Decision, Hypothesis, Todo, Question, Takeaway — und die Ziel-Kinds sind jede Code-Knoten-Variante, die Tesserae jetzt kennt: CodeFunction, CodeClass, CodeMethod, plus die in v0.3.0 neuen CodeInterface, CodeTrait, CodeStruct, CodeEnum, CodeEnumMember, CodeTypeAlias, CodeVariable, CodeConstant, CodeRoute, CodeComponent, CodeField, CodeNamespace und das CodeSymbol-Fallback.

Der Extractor ist hinsichtlich Präzision dreistufig, sodass der Agent-Harness Bezeichner wiederherstellen kann, die Nutzer tatsächlich geschrieben haben, ohne den Graph mit False Positives zu fluten:

Symbole, die in mehreren Dateien definiert sind, erhalten einen Same-Name-Fanout: Eine bloße Erwähnung von User in einem Session-Finding erzeugt einen discusses-Edge pro passender CodeClass (pro Datei), sodass ein nachgelagerter graph_ppr, der beim Finding aufsetzt, zu jeder plausiblen Implementierung verzweigt, statt willkürlich eine auszuwählen.

Ein neues MCP-Tool — find_code_symbol_mentions(node_id) — stellt denselben Extractor dem Agenten zur Query-Zeit zur Verfügung. Es nimmt einen beliebigen Knoten (typischerweise ein Session-Finding) und gibt jedes Code-Symbol zurück, das im Text erwähnt wird, samt der gematchten Stufe. Das ist nützlich, wenn Sie fragen wollen „Welche Symbole berührt diese Entscheidung tatsächlich?", ohne den Compile-Pass neu auszuführen.

Verwendung

Über eine Umgebungsvariable aktivieren, dann kompilieren:

export TESSERAE_INSIGHT_SYMBOL_LINK=true
tesserae project compile

Sobald aktiviert, erhält jedes Session-Finding, das ein bekanntes Symbol erwähnt, einen oder mehrere ausgehende discusses-Edges. Von einem MCP-Client aus:

// Symbole anzeigen, die eine bestimmte Entscheidung berührt
{
  "tool": "find_code_symbol_mentions",
  "arguments": { "node_id": "decision-2026-05-22-switch-to-rrf-fusion" }
}

// → liefert
// [
//   {"node_id": "code-function-tesserae.retrieval.hybrid.reciprocal_rank_fusion",
//    "tier": "backticked", "kind": "CodeFunction"},
//   {"node_id": "code-class-tesserae.retrieval.hybrid.HybridRetriever",
//    "tier": "dotted",     "kind": "CodeClass"}
// ]

Oder folgen Sie den neuen Edges mit graph_ppr, um die Nachbarschaft an Code-Symbolen zu ziehen, die ein Cluster von Entscheidungen berührt:

{
  "tool": "graph_ppr",
  "arguments": {
    "seed_node_ids": [
      "decision-2026-05-22-switch-to-rrf-fusion",
      "hypothesis-2026-05-23-embedding-helps-paraphrases"
    ],
    "top_k": 20,
    "edge_type_weights": { "discusses": 3.0, "references": 1.5 }
  }
}

Wann aktivieren

• Sie haben Session-Historie mit echter Code-Diskussion — ein mehrwöchiges Projekt, in dem Claude-Code-Sessions Funktionen/Klassen/Routes tatsächlich namentlich referenzieren, statt nur das Verhalten in Prosa zu beschreiben.
• Sie möchten, dass ask-Antworten das implementierende Symbol zitieren, nicht nur die README, die es erwähnt.
• Sie konsumieren den Graph aus einem anderen Tool (LSP-artiges „Go to Implementation" von einem Decision-Knoten) und brauchen einen abfragbaren Edge, keinen Treffer aus einer Re-Extraktion zur Query-Zeit.

Wenn Ihr Projekt überwiegend aus Prosa-Dokumenten und PDFs mit wenig Claude-Code-Historie besteht, verlängert der Pass nur die Compile-Zeit und liefert kaum nützliche Edges — lassen Sie ihn aus.

Wo es liegt

Kernimplementierung: MD0. Tool-Registrierung: tesserae/mcp_server.py.

Einschränkungen

• Die Stufe für bloße Bezeichner ist bewusst konservativ — sie verlangt einen Index-Treffer und ein Nicht-Stoppwort. Bezeichner, die zu häufig sind (run, get, set), passieren zwar den Stoppwort-Filter, gehen aber im Fanout über viele Dateien unter; das ist ein bekannter Trade-off, kein Bug.
• Der Same-Name-Fanout ist pro Kind: Eine User-Erwähnung, die sowohl auf eine CodeClass als auch eine CodeRoute passt, erzeugt Edges zu beiden. Wenn Sie nur die Klasse wollen, filtern Sie zur Query-Zeit auf target.kind == "CodeClass".
• Der Pass läuft nach sync-code (oder ingest-code) — wenn Sie Feature H ohne befüllten Code-Graph aktivieren, hat er nichts zum Verknüpfen und erzeugt null Edges. Die Compile-Reihenfolge wird automatisch gehandhabt; manuelle Sequenzierung ist nicht erforderlich.
• Die Stoppwort-Liste ist global, nicht pro Sprache; ein Rust-Projekt, das Vec legitim als Bezeichner verwenden möchte, funktioniert bereits (Vec steht nicht im Stoppwort-Set), aber projektlokale Überschreibungen sind ein geplanter v0.4-Follow-up.

2. tesserae project sync-code — CodeGraph-Adapter, 21 Sprachen

Was es ist

Ein neuer CLI-Subbefehl, der einen externen SQLite-Index von colbymchenry/codegraph in Tesseraes typisierten ResearchGraph importiert. CodeGraph ist ein tree-sitter-basierter polyglotter Code-Graph-Extractor mit eigenem MCP-Server; der Adapter liest dessen .codegraph/codegraph.db, übersetzt jede Zeile in einen Tesserae-ResearchNode und schreibt .tesserae/code-graph.json, sodass der nächste tesserae project compile ihn aufnimmt — genau wie die Ausgabe von ingest-code in v0.2.0, nur aus einer deutlich breiteren Sprachbasis befüllt.

Die Sprachabdeckung springt von 1 auf 21: TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Scala, Dart, Svelte, Vue, Liquid, Pascal/Delphi, Lua und Luau. (Der Stdlib-ast-Extractor aus v0.2.0 tesserae project ingest-code funktioniert für Nutzer, die einen reinen Python-Pfad ohne Node-Runtime-Abhängigkeit wollen, unverändert weiter.)

Um darzustellen, was tree-sitter über diese Sprachen hinweg tatsächlich liefert, fügt v0.3.0 14 neue ResearchNodeType-Varianten hinzu:

…und 8 neue Edge-Typen: implements, exports, references, instantiates, overrides, decorates, type_of und returns. Diese Edges entsprechen direkt dem, was der Resolver von CodeGraph pro Sprache berechnet; Tesseraes bestehende Edges calls, imports, inherits_from, contains und declared_in bleiben unverändert und werden weiter befüllt.

Die wichtigste Design-Entscheidung im Adapter ist die id_seed-Strategie. Die eigene Row-ID von CodeGraph enthält start_line, sodass dasselbe Symbol jedes Mal eine neue ID bekommt, sobald Sie eine Leerzeile darüber einfügen — fatal für nachgelagerte Edges, die die ID speichern. Der Adapter verwirft die CodeGraph-ID und sät Tesseraes ID als f"{file_path}:{kind}:{qualified_name}" neu. Resultat: Die Tesserae-ID eines Symbols überlebt zeilenverschiebende Edits unverändert, und Feature H's Treffer auf bloße Bezeichner in Session-Findings lösen über viele Compiles hinweg weiterhin auf denselben Knoten auf.

Verwendung

# Einmalig: .codegraph/codegraph.db lesen, .tesserae/code-graph.json schreiben,
# beim nächsten Compile wird es aufgenommen.
tesserae project sync-code

# Expliziter Projekt-Root + eigene DB-/Ausgabe-Pfade
tesserae project sync-code \
  --project /path/to/repo \
  --db /path/to/.codegraph/codegraph.db \
  --output /path/to/.tesserae/code-graph.json

# Watch-Loop — sync-code erneut ausführen, sobald sich die DB ändert.
# Nützlich, wenn Sie den SessionStart-Hook aus Feature 3 nicht wollen,
# aber den Code-Graph trotzdem während der Bearbeitung frisch halten möchten.
tesserae project sync-code --auto-sync

Ein typischer End-to-End-Flow auf einem neuen Projekt:

# 1. CodeGraph das Repo indexieren lassen (eigene CLI; Einmal-Setup)
npx codegraph index .

# 2. Das in Tesseraes typisierten Graph ziehen
tesserae project sync-code

# 3. Normaler Compile nimmt code-graph.json auf und führt (falls aktiviert) Feature H aus
export TESSERAE_INSIGHT_SYMBOL_LINK=true
tesserae project compile

# 4. Jetzt Fragen stellen, die Prosa und Code überspannen
tesserae project ask "Welche Funktionen implementieren die RRF-Fusion-Entscheidung?"

Wann aktivieren

• Ihr Projekt ist alles andere als reines Python, oder reines Python plus ein Node-Frontend.
• Sie verwenden CodeGraph bereits wegen dessen MCP-Server-Funktionen „find references" / „find implementations" — der Adapter lässt denselben Index Tesseraes typisierten Graph ohne zusätzliche Extraktionskosten antreiben.
• Sie wollen Route- oder Komponenten-Granularität (CodeRoute, CodeComponent) zusätzlich zu Funktionen und Klassen, die der v0.2.0 ingest-code nicht produziert.

Wenn Sie reines Python verwenden und keine Node-Runtime in Ihrer Toolchain möchten, funktioniert tesserae project ingest-code (v0.2.0) weiter und erzeugt eine kompatible code-graph.json.

Wo es liegt

Kernimplementierung: MD0. CLI-Verdrahtung: tesserae/cli.py (der sync-code-Subparser, etwa bei Zeile 897). Der v0.2.0 ingest-code-Subbefehl in tesserae/code_graph_extractor.py ist unverändert.

Einschränkungen

• Erfordert eine befüllte .codegraph/codegraph.db (CodeGraphs eigener Einmal-Schritt npx codegraph index .). Der Adapter schlägt bei fehlender DB schnell und mit einer handlungsorientierten Fehlermeldung fehl.
• Der Resolver von CodeGraph ist über 21 Sprachen hinweg Best-Effort; gelegentliche ungelöste Referenzen in pathologischen Generics oder Macro-lastigem Code sind zu erwarten. Der Adapter erfasst, was CodeGraph ausgibt, und versucht nicht, neu aufzulösen.
• Einige Node-Kinds (CodeParameter, CodeField) werden nur ausgegeben, wenn der per-language Extractor von CodeGraph sie liefert — die Abdeckung variiert je Sprache. Das Fallback CodeSymbol fängt alles ab, was tree-sitter sieht und wir noch nicht typisiert haben, sodass nichts stillschweigend verloren geht.
• Atomic Writes verwenden PID + Zufalls-Suffix für die Temp-Datei (nicht ein gemeinsames .tmp), damit zwei gleichzeitige sync-code-Aufrufe nicht kollidieren — das entspricht demselben Fix, der kürzlich im Batch-Manifest-Writer gelandet ist.

3. Live-sync-code-SessionStart-Hook (post-v0.3.0 auf main)

Was es ist

Ein kleiner SessionStart-Hook im Tesserae-Plugin, der die Schleife „Code-Graph, der sich laufend aktualisiert" schließt. Der MCP-Server von CodeGraph beobachtet das Dateisystem bereits automatisch und hält .codegraph/codegraph.db frisch, während Sie editieren — aber Tesseraes .tesserae/code-graph.json wurde nur dann aktualisiert, wenn Sie sync-code von Hand ausführten. Dieser Hook startet tesserae project sync-code --project <root> jedes Mal im Hintergrund, wenn Claude Code eine Session öffnet, aber nur, wenn die SQLite-DB neuer als das abgeleitete JSON ist.

Standardmäßig aktiv; Opt-out pro Projekt über .claude/tesserae.local.md-Frontmatter:

---
hooks:
  sync_code_on_start: false
---

Der Hook überspringt stillschweigend, wenn eine der folgenden Bedingungen zutrifft, damit er Projekten, die CodeGraph nicht nutzen, keinen Lärm hinzufügt:

• Das Projekt nutzt CodeGraph nicht (kein .codegraph/codegraph.db).
• .tesserae/code-graph.json ist bereits gleich alt oder neuer als die DB.
• Die tesserae-Binary ist nicht im PATH.
• Ein anderer sync-code läuft bereits für denselben Projekt-Root (eine pgrep-basierte Re-Entry-Sperre nach Vorbild der SessionEnd-Compile-Sperre, die in 0a3d35f landete).
• Der Nutzer hat sich via sync_code_on_start: false abgemeldet.

Wenn er feuert, sehen Sie eine Zeile im Session-Header:

  ⟳ syncing code-graph from CodeGraph (background)

…und der eigentliche sync-code-Aufruf läuft losgelöst (setsid → nohup → blankes & als Fallback), wobei die Ausgabe in .tesserae/.session-start-hook.log erfasst wird, damit Sie nachsehen können, was passiert ist, ohne dass es in das Claude-Session-Transkript leakt.

Dieser Hook ist post-v0.3.0 auf main gelandet (PR #11, Commit 395e9fb) und wird im nächsten Compile-/Plugin-Marketplace-Release ausgeliefert; das v0.3.0-PyPI selbst bündelt ihn nicht, weil der Hook im Plugin lebt, nicht im tesserae-Python-Paket.

Verwendung

Wenn Sie das Tesserae-Plugin über den Claude-Code-Marketplace installiert haben, haben Sie ihn bereits — der Hook ist standardmäßig an. Zur Verifikation, ob er gelaufen ist:

tail -n 20 .tesserae/.session-start-hook.log

Um ihn für ein einzelnes Projekt abzuschalten (z. B. ein reines Python-Repo, in dem ingest-code bevorzugt wird):

mkdir -p .claude
cat > .claude/tesserae.local.md <<'EOF'
---
hooks:
  sync_code_on_start: false
---

Dieses Projekt verwendet `tesserae project ingest-code` (Python-AST) statt
des CodeGraph-Adapters, daher ist der Live-sync-code-Hook deaktiviert.
EOF

Um einen einmaligen Sync zu erzwingen, ohne auf eine neue Session zu warten, führen Sie einfach direkt tesserae project sync-code aus — der Hook und der manuelle Befehl teilen sich dieselbe pgrep-Sperre, sodass sie nicht doppelt laufen.

Wann aktivieren

• Sie wollen die „hält sich aktuell"-Eigenschaft, ohne sich merken zu müssen, sync-code nach jedem Edit-Batch erneut auszuführen.
• Ihre Editor-Sessions sind kurz und häufig (Session öffnen, eine Frage stellen, schließen) — der Hook stellt sicher, dass jede neue Session einen aktuellen Code-Graph sieht.
• Sie betreiben bereits den MCP-Server von CodeGraph mit File-Watching — der Hook propagiert diese Frische einfach in Tesserae.

Lassen Sie ihn aus, wenn Sie in einem engen Inner Loop sind und keinerlei Hintergrund-Arbeit pro Session gespawnt werden soll, oder wenn das Projekt CodeGraph gar nicht nutzt (der Hook ist in diesem Fall ein stilles No-op, aber ein explizites Opt-out ist sauberer).

Wo es liegt

• Hook-Einstiegspunkt: MD0
• Settings-Parser: MD0 — die read_plugin_setting-Tabelle hat einen sync_code_on_start=true-Default bekommen.
• Re-Entry-Sperre: dasselbe Muster pgrep -f "tesserae project sync-code.*${project_root}" wie die SessionEnd-Compile-Sperre (hooks/session-end.sh).

Einschränkungen

• Der Hook feuert nur bei SessionStart, nicht bei jedem File-Save. Wenn Sie wollen, dass sync-code kontinuierlich läuft, während Sie editieren (ohne eine neue Claude-Session zu öffnen), verwenden Sie tesserae project sync-code --auto-sync aus Feature 2 in einem separaten Terminal.
• Der mtime-Vergleich nutzt BSD stat -f %m (macOS) → GNU stat -c %Y (Linux) → [[ A -nt B ]]-Fallback. Auf exotischen Dateisystemen mit niedrig aufgelösten mtimes überspringen Sie gelegentlich einen Sync, der weniger als eine Sekunde nach einem CodeGraph-Index lief — die nächste Session fängt ihn ein.
• Das Hintergrund-Spawnen verwendet setsid, wenn verfügbar, danach nohup, danach ein blankes &. Auf extrem eingeschränkten Shells, in denen keine dieser Optionen den Prozess löst, läuft der Sync zwar trotzdem, kann aber den Session-Start um einige Sekunden blockieren. Öffnen Sie eine terminalfreundliche Shell oder setzen Sie in diesem Fall sync_code_on_start: false.

Upgrade von v0.2.0

pip install --upgrade tesserae==0.3.0

Das ist das gesamte Upgrade — v0.3.0 ist additiv ohne Breaking Changes. Das Standardverhalten von tesserae project compile ist unverändert; die neuen Teile sind opt-in und entdeckbar.

Umgebungsvariable für den neuen opt-in-Pass (Feature 1):

# Den Post-Compile-Pass „Prosa-zu-Code-discusses-Edge" aktivieren (Feature H)
export TESSERAE_INSIGHT_SYMBOL_LINK=true

Neuer CLI-Subbefehl für Ihr Muskelgedächtnis (Feature 2):

tesserae project sync-code             # einmaliger CodeGraph-→-Tesserae-Import
tesserae project sync-code --auto-sync # Watch-Loop

Der v0.2.0-Subbefehl tesserae project ingest-code funktioniert weiter unverändert — wählen Sie sync-code, wenn Ihr Projekt etwas über Python hinaus verwendet, und ingest-code, wenn Sie keine Node-Runtime-Abhängigkeit wollen.

Neues MCP-Tool, das der Agent jetzt zur Verfügung hat (Feature 1):

• find_code_symbol_mentions(node_id) — Symbol-Extraktion zur Query-Zeit über einen beliebigen Knoten-Text.

Neue Plugin-Einstellung (Feature 3, post-v0.3.0 auf main):

# .claude/tesserae.local.md
---
hooks:
  sync_code_on_start: true   # Default; auf false setzen, um den Live-Sync-Hook zu deaktivieren
---

Alles andere — graph_ppr, hybrider search_nodes, embedding_status, list_communities, fresh_insights, Community-Zusammenfassungen, Decay-Scoring, supersedes, Schema-Drift, Slash-Commands, die Wiki-/Obsidian-Projektion — ist unverändert gegenüber v0.2.0.

Strategischer Kontext

Tesserae v0.2.0 legte typisierte Code-Graph-Knoten und die prosaseitigen Primitiven (Decay, supersedes, Community-Zusammenfassungen) fest. v0.3.0 ist das Release, in dem die beiden Hälften zusammengeführt werden: Feature H erzeugt typisierte discusses-Edges von Entscheidungen und Hypothesen zu den Symbolen, die sie berühren, und der CodeGraph-Adapter sorgt dafür, dass diese Symbole den polyglotten Stack abdecken, den ein echtes Forschungs-Repository tatsächlich nutzt — TypeScript, Rust, Go, Swift und 17 weitere — statt nur Python.

Die Wave-1-PKM-AI-Landschaft, die wir vor diesem Milestone untersucht haben, hat kein anderes Tool, das dies leistet. Cursor Memories ist ein Textbeutel pro Projekt — kein Graph, keine typisierten Edges. Claude CLAUDE.md ist eine einzige flache Markdown-Datei. Cline memory-bank ist ein Verzeichnis aus Markdown-Dateien, ohne typisierte Extraktion. Aider CONVENTIONS.md ist eine einzelne Prompt-Prefix-Datei. Keines von ihnen verknüpft eine prosaische Entscheidung mit der Funktion oder Klasse, die sie umsetzt; keines von ihnen weiß, dass ein Decision und ein CodeRoute unterschiedliche Arten von Dingen sind. Der discusses-Edge in v0.3.0 über 21 Sprachen typisierter Code-Knoten ist der Keil — und der Live-SessionStart-Hook ist es, der diesen Keil wie eine Eigenschaft der Umgebung wirken lässt, statt wie einen Workflow, den der Nutzer sich merken muss.

Der nächste Peer im breiteren GraphRAG-Raum — Microsoft GraphRAG — hat typisierte Entitäten und Community-Zusammenfassungen (die Tesserae v0.2.0 spiegelt), aber gar keine Code-Graph-Schicht; es ist ein Corpus-RAG-System, kein Projekt-Memory-Compiler. HippoRAGs 2 PPR-Primitive (Tesserae v0.2.0) und Mem0s Memory Operations (Tesserae v0.2.0 supersedes) runden den prosaseitigen State of the Art ab. v0.3.0 fügt die Dimension hinzu, die keines davon berührt: typisierte Edges von den eigenen Findings des Agenten in typisierte Knoten, die den Code repräsentieren, um den es in diesen Findings geht — in den Sprachen, in denen echte Codebasen tatsächlich geschrieben sind.

Siehe auch:

• v0.2.0-Release-Notes — typisiertes Retrieval, Code-Graph (Python), Ontologie-Evolution
• Architektur-Überblick — Modul-Karte und Pipeline
• Feature-Map — vollständige Feature-Status-Tabelle mit Quell-Links
• Sessions-Integration — die Session-Finding-Quellknoten, von denen Feature H verknüpft
• MCP-Integration — vollständige MCP-Tool-Liste (das neue find_code_symbol_mentions-Tool kommt im nächsten Docs-Pass hier hinzu)