Tesserae v0.3.0 — Liens prose-vers-code, graphe de code polyglotte, synchronisation en direct

<!-- translations:start -->

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

<!-- translations:end -->

Publié le 2026-05-24 · PyPI · GitHub release · pip install --upgrade tesserae==0.3.0

Tesserae 0.3.0 boucle la boucle entre les décisions exprimées en prose et les symboles de code qui les implémentent, et le fait à travers 21 langages au lieu de la fondation Python-uniquement de la v0.2.0. La version livre trois fonctionnalités additives sans aucun changement cassant : une passe d'arêtes discusses qui frappe des liens typés depuis les session findings (SessionInsight, Decision, Hypothesis, Todo, Question, Takeaway) vers les nœuds de code correspondants ; une sous-commande tesserae project sync-code qui importe l'index SQLite tree-sitter de colbymchenry/codegraph dans le ResearchGraph typé de Tesserae ; et un hook SessionStart de live sync-code (synchronisation en direct du code) activé par défaut qui maintient cet import à jour pendant que l'utilisateur édite son code. Ensemble, ils font de Tesserae le seul outil de mémoire PKM-AI dans le paysage de 2026 où « qu'avons-nous décidé à propos de X ? » retourne les décisions, les sessions où elles ont été prises, et les fonctions / classes / routes exactes qui les implémentent — à travers la pile polyglotte qu'utilise réellement une vraie base de code de recherche.

Table des matières :

1. Arêtes MD0 — relier la prose aux symboles de code (fonctionnalité H)
2. MD0 — adaptateur CodeGraph, 21 langages
3. Hook SessionStart de live sync-code (post-v0.3.0 sur MD0)
4. Migration depuis la v0.2.0
5. Contexte stratégique

1. Arêtes discusses — relier la prose aux symboles de code (fonctionnalité H)

Ce que c'est

Une passe post-compilation optionnelle qui scanne le corps de chaque session finding à la recherche de mentions de symboles de code présents dans le graphe, et frappe une arête typée discusses depuis le finding vers chaque nœud de code correspondant. Les types sources sont les six types de session-finding émis par l'agent harness — SessionInsight, Decision, Hypothesis, Todo, Question, Takeaway — et les types cibles sont toutes les variantes de nœud de code que Tesserae connaît désormais : CodeFunction, CodeClass, CodeMethod, plus les nouveautés de la v0.3.0 CodeInterface, CodeTrait, CodeStruct, CodeEnum, CodeEnumMember, CodeTypeAlias, CodeVariable, CodeConstant, CodeRoute, CodeComponent, CodeField, CodeNamespace, et le repli CodeSymbol.

L'extracteur est organisé en trois niveaux de précision, afin que l'agent harness puisse récupérer les identifiants que les utilisateurs ont réellement écrits sans inonder le graphe de faux positifs :

Les symboles définis dans plusieurs fichiers bénéficient d'un fanout par même nom : une mention en identifiant nu de User dans un session finding produit une arête discusses par CodeClass correspondant (par fichier), de sorte qu'un graph_ppr en aval amorcé sur le finding se déploie vers chaque implémentation plausible plutôt que d'en choisir une arbitrairement.

Un nouvel outil MCP — find_code_symbol_mentions(node_id) — expose le même extracteur à l'agent au moment de la requête. Il prend n'importe quel nœud (typiquement un session finding) et retourne chaque symbole de code mentionné dans le corps, avec le niveau qui a matché. Utile quand on veut demander « quels symboles cette décision touche-t-elle réellement ? » sans relancer la passe de compilation.

Comment l'utiliser

Activez via une variable d'environnement, puis compilez :

export TESSERAE_INSIGHT_SYMBOL_LINK=true
tesserae project compile

Une fois activée, chaque session finding qui mentionne un symbole connu gagne une ou plusieurs arêtes sortantes discusses. Depuis un client MCP :

// Faire remonter les symboles qu'une décision particulière touche
{
  "tool": "find_code_symbol_mentions",
  "arguments": { "node_id": "decision-2026-05-22-switch-to-rrf-fusion" }
}

// → retourne
// [
//   {"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"}
// ]

Ou suivez les nouvelles arêtes avec graph_ppr pour récupérer le voisinage de symboles de code qu'un cluster de décisions touche :

{
  "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 }
  }
}

Quand l'activer

• Vous avez un historique de sessions avec une vraie discussion de code — un projet pluri-hebdomadaire où les sessions Claude Code référencent réellement des fonctions/classes/routes par leur nom, et ne se contentent pas d'en décrire le comportement en prose.
• Vous voulez que les réponses de ask citent le symbole d'implémentation plutôt que le seul README qui le mentionne.
• Vous consommez le graphe depuis un autre outil (un « aller à l'implémentation » à la LSP depuis un nœud de décision) et avez besoin d'une arête interrogeable, et non d'une devinette ré-extraite au moment de la requête.

Si votre projet est principalement composé de prose, de documents et de PDF avec peu d'historique Claude Code, la passe rallonge le temps de compilation et produit très peu d'arêtes utiles — laissez-la désactivée.

Où elle se trouve

Implémentation centrale : MD0. Enregistrement de l'outil : tesserae/mcp_server.py.

Mises en garde

• Le niveau identifiant nu est délibérément conservateur — il exige un hit dans l'index et un non-stopword. Les identifiants trop courants (run, get, set) passeront tout de même le filtre stopword mais seront noyés par le fanout vers de nombreux fichiers ; c'est un compromis connu, pas un bug.
• Le fanout par même nom est par type : une mention de User qui correspond à la fois à une CodeClass et à une CodeRoute produit des arêtes vers les deux. Si vous ne voulez que la classe, filtrez au moment de la requête sur target.kind == "CodeClass".
• La passe s'exécute après sync-code (ou ingest-code) — si vous activez la fonctionnalité H sans graphe de code peuplé, elle n'a rien à relier et produit zéro arête. L'ordre de compilation est géré automatiquement ; aucun séquencement manuel requis.
• La liste de stopwords est globale, pas par langage ; un projet Rust qui veut légitimement Vec comme identifiant fonctionne déjà (Vec n'est pas dans l'ensemble des stopwords), mais des surcharges spécifiques au projet sont prévues comme suivi en v0.4.

2. tesserae project sync-code — adaptateur CodeGraph, 21 langages

Ce que c'est

Une nouvelle sous-commande CLI qui importe un index SQLite externe colbymchenry/codegraph dans le ResearchGraph typé de Tesserae. CodeGraph est un extracteur de graphe de code polyglotte basé sur tree-sitter, avec son propre serveur MCP ; l'adaptateur lit son .codegraph/codegraph.db, traduit chaque ligne en ResearchNode Tesserae, et écrit .tesserae/code-graph.json afin que le prochain tesserae project compile le prenne en compte — exactement comme la sortie ingest-code de la v0.2.0, mais peuplé à partir d'une base linguistique bien plus large.

La couverture linguistique passe de 1 à 21 : TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Scala, Dart, Svelte, Vue, Liquid, Pascal/Delphi, Lua, et Luau. (L'extracteur stdlib-ast tesserae project ingest-code de la v0.2.0 continue de fonctionner sans changement pour les utilisateurs qui veulent un chemin Python-uniquement sans dépendance à un runtime Node.)

Pour représenter ce que tree-sitter fait réellement remonter dans ces langages, la v0.3.0 ajoute 14 nouvelles variantes de ResearchNodeType :

…et 8 nouveaux types d'arêtes : implements, exports, references, instantiates, overrides, decorates, type_of, et returns. Ces arêtes se mappent directement sur ce que le résolveur de CodeGraph calcule par langage ; les arêtes existantes de Tesserae calls, imports, inherits_from, contains, et declared_in restent inchangées et continuent d'être peuplées.

Le choix de conception le plus important de l'adaptateur est la stratégie id_seed. L'id de ligne propre à CodeGraph embarque start_line, donc le même symbole obtient un nouvel id chaque fois que vous ajoutez une ligne blanche au-dessus de lui — fatal pour les arêtes en aval qui stockent l'id. L'adaptateur écarte l'id de CodeGraph et regermine l'id Tesserae sous la forme f"{file_path}:{kind}:{qualified_name}". Résultat : l'id Tesserae d'un symbole survit inchangé aux édits qui décalent les lignes, et les correspondances en identifiant nu de la fonctionnalité H dans les session findings continuent de se résoudre vers le même nœud à travers de nombreuses compilations.

Comment l'utiliser

# Coup unique : lit .codegraph/codegraph.db, écrit .tesserae/code-graph.json,
# puis la prochaine compilation le prend en compte.
tesserae project sync-code

# Racine de projet explicite + chemins DB / sortie personnalisés
tesserae project sync-code \
  --project /path/to/repo \
  --db /path/to/.codegraph/codegraph.db \
  --output /path/to/.tesserae/code-graph.json

# Boucle de surveillance — relance sync-code à chaque modification de la DB.
# Utile si vous ne voulez pas le hook SessionStart de la fonctionnalité 3
# mais voulez quand même garder le graphe de code à jour pendant vos édits.
tesserae project sync-code --auto-sync

Un flux de bout en bout typique sur un nouveau projet :

# 1. Demander à CodeGraph d'indexer le dépôt (sa propre CLI ; configuration ponctuelle)
npx codegraph index .

# 2. Tirer cela dans le graphe typé de Tesserae
tesserae project sync-code

# 3. La compilation normale prend code-graph.json et (si activée) lance la fonctionnalité H
export TESSERAE_INSIGHT_SYMBOL_LINK=true
tesserae project compile

# 4. Maintenant, posez des questions qui couvrent prose et code
tesserae project ask "Quelles fonctions implémentent la décision de fusion RRF ?"

Quand l'activer

• Votre projet est n'importe quoi d'autre que du Python pur, ou du Python pur plus un frontend Node.
• Vous utilisez déjà CodeGraph pour son serveur MCP « find references » / « find implementations » — l'adaptateur permet au même index d'alimenter le graphe typé de Tesserae sans coût d'extraction supplémentaire.
• Vous voulez une granularité au niveau route ou composant (CodeRoute, CodeComponent) en plus des fonctions et classes, ce que l'ingest-code de la v0.2.0 ne produit pas.

Si vous êtes Python-uniquement et ne voulez pas de runtime Node dans votre chaîne d'outils, tesserae project ingest-code (v0.2.0) fonctionne toujours et produit un code-graph.json compatible.

Où il se trouve

Implémentation centrale : MD0. Câblage CLI : tesserae/cli.py (le sous-parseur sync-code, autour de la ligne 897). La sous-commande ingest-code de la v0.2.0 dans tesserae/code_graph_extractor.py est inchangée.

Mises en garde

• Requiert un .codegraph/codegraph.db peuplé (l'étape ponctuelle npx codegraph index . propre à CodeGraph). L'adaptateur échoue rapidement avec un message d'erreur actionnable si la DB est manquante.
• Le résolveur de CodeGraph fait au mieux à travers 21 langages ; attendez-vous à des références non résolues occasionnelles dans des génériques pathologiques ou du code chargé de macros. L'adaptateur enregistre ce que CodeGraph émet et ne tente pas de re-résoudre.
• Certains types de nœuds (CodeParameter, CodeField) ne sont émis que lorsque l'extracteur par langage de CodeGraph les fait remonter — la couverture varie selon le langage. Le type de repli CodeSymbol capture tout ce que tree-sitter voit et que nous n'avons pas encore typé, donc rien n'est silencieusement perdu.
• Les écritures atomiques utilisent un suffixe PID + aléatoire pour le fichier temporaire (pas un .tmp partagé) afin que deux invocations concurrentes de sync-code n'entrent pas en collision — cela correspond au même correctif récemment intégré dans l'écrivain de manifeste batch.

3. Hook SessionStart de live sync-code (post-v0.3.0 sur main)

Ce que c'est

Un petit hook SessionStart dans le plugin Tesserae qui boucle la boucle du « graphe de code qui se met à jour en continu ». Le serveur MCP de CodeGraph surveille déjà automatiquement le système de fichiers et garde .codegraph/codegraph.db à jour pendant vos édits — mais le .tesserae/code-graph.json de Tesserae ne se rafraîchissait que lorsque vous lanciez sync-code à la main. Ce hook lance tesserae project sync-code --project <root> en arrière-plan chaque fois que Claude Code ouvre une session, mais uniquement si la DB SQLite est plus récente que le JSON dérivé.

Activé par défaut ; opt-out par projet via le frontmatter de .claude/tesserae.local.md :

---
hooks:
  sync_code_on_start: false
---

Le hook passe silencieusement quand l'une des conditions suivantes est vérifiée, afin de ne jamais ajouter de bruit aux projets qui n'utilisent pas CodeGraph :

• Le projet n'utilise pas CodeGraph (pas de .codegraph/codegraph.db).
• .tesserae/code-graph.json est déjà à la même date ou plus récent que la DB.
• Le binaire tesserae n'est pas dans le PATH.
• Un autre sync-code est déjà en cours d'exécution pour la même racine de projet (un garde-fou anti-réentrée basé sur pgrep, miroir du garde-fou de compilation SessionEnd intégré dans 0a3d35f).
• L'utilisateur s'est désinscrit via sync_code_on_start: false.

Lorsqu'il se déclenche, vous voyez une ligne dans l'en-tête de session :

  ⟳ syncing code-graph from CodeGraph (background)

…et l'invocation sync-code réelle tourne en mode détaché (setsid → nohup → repli sur le simple &), avec la sortie capturée dans .tesserae/.session-start-hook.log afin que vous puissiez inspecter ce qui s'est passé sans que cela fuite dans le transcript de la session Claude.

Ce hook a été intégré post-v0.3.0 sur main (PR #11, commit 395e9fb) et sera livré dans la prochaine publication de plugin / marketplace ; la v0.3.0 sur PyPI elle-même ne l'embarque pas car le hook vit dans le plugin, pas dans le package Python tesserae.

Comment l'utiliser

Si vous avez installé le plugin Tesserae via le marketplace Claude Code, vous l'avez déjà — le hook est activé par défaut. Pour vérifier qu'il s'est exécuté :

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

Pour le désactiver sur un seul projet (par exemple un dépôt Python-uniquement où ingest-code est préféré) :

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

Ce projet utilise `tesserae project ingest-code` (Python AST) au lieu de
l'adaptateur CodeGraph, donc le hook de live sync-code est désactivé.
EOF

Pour forcer une synchronisation ponctuelle sans attendre une nouvelle session, exécutez simplement tesserae project sync-code directement — le hook et la commande manuelle partagent le même garde-fou pgrep, donc ils ne s'exécuteront pas en double.

Quand l'activer

• Vous voulez la propriété « se met à jour en continu » sans avoir à penser à relancer sync-code après chaque vague d'édits.
• Vos sessions d'édition sont courtes et fréquentes (ouvrir une session, poser une question, fermer) — le hook s'assure que chaque nouvelle session voit un graphe de code à jour.
• Vous exécutez déjà le serveur MCP de CodeGraph avec surveillance des fichiers — le hook ne fait que propager cette fraîcheur dans Tesserae.

Laissez-le désactivé quand vous êtes dans une boucle interne serrée et ne voulez aucun travail d'arrière-plan engendré par session, ou quand le projet n'utilise pas du tout CodeGraph (le hook devient silencieusement un no-op dans ce cas, mais un opt-out explicite est plus propre).

Où il se trouve

• Point d'entrée du hook : MD0
• Parseur de réglages : MD0 — la table read_plugin_setting a gagné une valeur par défaut sync_code_on_start=true.
• Garde-fou anti-réentrée : même motif pgrep -f "tesserae project sync-code.*${project_root}" que le garde-fou de compilation SessionEnd (hooks/session-end.sh).

Mises en garde

• Le hook ne se déclenche que sur SessionStart, pas à chaque sauvegarde de fichier. Si vous voulez que sync-code tourne en continu pendant vos édits (sans ouvrir une nouvelle session Claude), utilisez tesserae project sync-code --auto-sync de la fonctionnalité 2 dans un terminal séparé.
• La comparaison de mtime utilise BSD stat -f %m (macOS) → GNU stat -c %Y (Linux) → repli sur [[ A -nt B ]]. Sur des systèmes de fichiers exotiques aux mtimes basse résolution, vous pouvez occasionnellement sauter une synchronisation qui a tourné moins d'une seconde après un index CodeGraph — la session suivante la rattrapera.
• Le spawn d'arrière-plan utilise setsid quand disponible, puis nohup, puis le simple &. Sur des shells extrêmement verrouillés où aucun de ces mécanismes ne détache le processus, la synchronisation tournera tout de même mais peut bloquer le démarrage de session de quelques secondes. Ouvrez un shell convivial pour terminal ou définissez sync_code_on_start: false dans ce cas.

Migration depuis la v0.2.0

pip install --upgrade tesserae==0.3.0

C'est toute la mise à niveau — la v0.3.0 est additive sans changement cassant. Le comportement par défaut de tesserae project compile est inchangé ; les nouveaux éléments sont optionnels et découvrables.

Variable d'environnement pour la nouvelle passe optionnelle (fonctionnalité 1) :

# Active la passe post-compilation d'arêtes discusses prose-vers-code (fonctionnalité H)
export TESSERAE_INSIGHT_SYMBOL_LINK=true

Nouvelle sous-commande CLI à ajouter à votre mémoire musculaire (fonctionnalité 2) :

tesserae project sync-code             # import unique CodeGraph → Tesserae
tesserae project sync-code --auto-sync # boucle de surveillance

La sous-commande tesserae project ingest-code de la v0.2.0 fonctionne toujours sans changement — choisissez sync-code si votre projet utilise autre chose que Python, choisissez ingest-code si vous ne voulez pas de dépendance à un runtime Node.

Nouvel outil MCP désormais disponible pour l'agent (fonctionnalité 1) :

• find_code_symbol_mentions(node_id) — extraction de symboles au moment de la requête sur n'importe quel corps de nœud.

Nouveau réglage de plugin (fonctionnalité 3, post-v0.3.0 sur main) :

# .claude/tesserae.local.md
---
hooks:
  sync_code_on_start: true   # défaut ; mettre à false pour désactiver le hook de live sync
---

Tout le reste — graph_ppr, le search_nodes hybride, embedding_status, list_communities, fresh_insights, les résumés de communautés, le scoring par décroissance, supersedes, la dérive de schéma, les slash commands, la projection wiki / Obsidian — est inchangé depuis la v0.2.0.

Contexte stratégique

La v0.2.0 de Tesserae a posé les nœuds typés du graphe de code et les primitives côté prose (décroissance, supersedes, résumés de communautés). La v0.3.0 est la version où les deux moitiés se connectent : la fonctionnalité H frappe des arêtes typées discusses depuis les décisions et hypothèses vers les symboles qu'elles touchent, et l'adaptateur CodeGraph fait en sorte que ces symboles couvrent la pile polyglotte qu'utilise réellement une vraie base de code de recherche — TypeScript, Rust, Go, Swift, et 17 autres — au lieu du seul Python.

Le paysage PKM-AI de la première vague que nous avons étudié avant ce jalon ne compte aucun autre outil qui fasse cela. Cursor Memories est un sac de texte par projet — pas de graphe, pas d'arêtes typées. Claude CLAUDE.md est un seul fichier markdown plat. Cline memory-bank est un répertoire de fichiers markdown, sans extraction typée. Aider CONVENTIONS.md est un unique fichier de préfixe de prompt. Aucun d'eux ne relie une décision en prose à la fonction ou à la classe qui l'implémente ; aucun d'eux ne sait qu'une Decision et une CodeRoute sont des choses de natures différentes. L'arête discusses de la v0.3.0 à travers 21 langages de nœuds de code typés est le coin — et le hook SessionStart en direct est ce qui fait que ce coin se ressent comme une propriété de l'environnement plutôt que comme un workflow dont l'utilisateur doit se souvenir.

Le pair le plus proche dans l'espace plus large de GraphRAG — Microsoft GraphRAG — a des entités typées et des résumés de communautés (que la v0.2.0 de Tesserae reflète) mais pas du tout de couche de graphe de code ; c'est un système RAG sur corpus, pas un compilateur de mémoire de projet. La primitive PPR de HippoRAG 2 (Tesserae v0.2.0) et les opérations mémoire de Mem0 (le supersedes de Tesserae v0.2.0) complètent l'état de l'art côté prose. La v0.3.0 ajoute la dimension qu'aucun d'eux ne touche : des arêtes typées depuis les propres findings de l'agent vers des nœuds typés représentant le code dont ces findings parlent, dans les langages où sont effectivement écrites les vraies bases de code.

Voir aussi :

• Notes de version v0.2.0 — récupération typée, graphe de code (Python), évolution de l'ontologie
• Vue d'ensemble de l'architecture — carte des modules et pipeline
• Carte des fonctionnalités — table de statut complète des fonctionnalités avec liens sources
• Intégration des sessions — les nœuds sources de session-finding depuis lesquels la fonctionnalité H crée des liens
• Intégration MCP — liste complète des outils MCP (le nouvel outil find_code_symbol_mentions y apparaîtra à la prochaine passe de documentation)