Tesserae v0.3.0 — Enlaces prosa-a-código, grafo de código políglota, sincronización en vivo

<!-- translations:start -->

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

<!-- translations:end -->

Publicado el 24-05-2026 · PyPI · Lanzamiento en GitHub · pip install --upgrade tesserae==0.3.0

Tesserae 0.3.0 cierra el ciclo entre las decisiones en prosa y los símbolos de código que las implementan, y lo hace a través de 21 lenguajes en lugar de la base exclusiva en Python de la v0.2.0. La versión incorpora tres funcionalidades aditivas sin cambios disruptivos: una pasada de aristas discusses que acuña enlaces tipados desde los hallazgos de sesión (SessionInsight, Decision, Hypothesis, Todo, Question, Takeaway) a los nodos de código correspondientes; un subcomando tesserae project sync-code que importa el índice SQLite basado en tree-sitter de colbymchenry/codegraph al ResearchGraph tipado de Tesserae; y un hook SessionStart de sync-code en vivo activado por defecto que mantiene esa importación fresca conforme el usuario edita código. En conjunto, hacen de Tesserae la única herramienta de memoria PKM-AI en el panorama de 2026 donde "¿qué decidimos sobre X?" devuelve las decisiones, las sesiones en las que se tomaron, y las funciones / clases / rutas exactas que las implementan — a través del stack políglota que un codebase de investigación real utiliza realmente.

Tabla de contenidos:

1. Aristas MD0 — enlazar prosa con símbolos de código (funcionalidad H)
2. MD0 — adaptador de CodeGraph, 21 lenguajes
3. Hook SessionStart de sync-code en vivo (post-v0.3.0 en MD0)
4. Actualización desde v0.2.0
5. Contexto estratégico

1. Aristas discusses — enlazar prosa con símbolos de código (funcionalidad H)

Qué es

Una pasada post-compilación opcional que escanea el cuerpo de cada hallazgo de sesión en busca de menciones a símbolos de código presentes en el grafo, y acuña una arista tipada discusses desde el hallazgo a cada nodo de código coincidente. Los tipos de origen son los seis tipos de hallazgo de sesión que emite el harness del agente — SessionInsight, Decision, Hypothesis, Todo, Question, Takeaway — y los tipos de destino son todas las variantes de nodo de código que Tesserae conoce ahora: CodeFunction, CodeClass, CodeMethod, además de los nuevos en v0.3.0 CodeInterface, CodeTrait, CodeStruct, CodeEnum, CodeEnumMember, CodeTypeAlias, CodeVariable, CodeConstant, CodeRoute, CodeComponent, CodeField, CodeNamespace, y el respaldo CodeSymbol.

El extractor es de tres niveles por precisión, de modo que el harness del agente pueda recuperar los identificadores que los usuarios realmente escribieron sin inundar el grafo con falsos positivos:

Los símbolos definidos en múltiples archivos obtienen fanout por mismo nombre: una mención de identificador desnudo a User en un hallazgo de sesión produce una arista discusses por cada CodeClass coincidente (por archivo), de manera que un graph_ppr aguas abajo sembrado en el hallazgo se abre en abanico hacia toda implementación plausible en lugar de elegir una arbitrariamente.

Una nueva herramienta MCP — find_code_symbol_mentions(node_id) — expone el mismo extractor al agente en tiempo de consulta. Toma cualquier nodo (típicamente un hallazgo de sesión) y devuelve cada símbolo de código que el cuerpo menciona, con el nivel que coincidió. Esto resulta útil cuando se desea preguntar "¿qué símbolos toca realmente esta decisión?" sin volver a ejecutar la pasada de compilación.

Cómo usarlo

Actívelo mediante una variable de entorno y luego compile:

export TESSERAE_INSIGHT_SYMBOL_LINK=true
tesserae project compile

Una vez activado, cada hallazgo de sesión que mencione un símbolo conocido gana una o más aristas salientes discusses. Desde un cliente MCP:

// Mostrar los símbolos que una decisión específica toca
{
  "tool": "find_code_symbol_mentions",
  "arguments": { "node_id": "decision-2026-05-22-switch-to-rrf-fusion" }
}

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

O siga las nuevas aristas con graph_ppr para extraer el vecindario de símbolos de código que toca un grupo de decisiones:

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

Cuándo activarlo

• Cuenta con historial de sesión con discusión real de código — un proyecto de varias semanas donde las sesiones de Claude Code realmente referencian funciones/clases/rutas por su nombre, no solo describen comportamiento en prosa.
• Desea que las respuestas de ask citen el símbolo que implementa en lugar de únicamente el README que lo menciona.
• Está consumiendo el grafo desde otra herramienta (estilo LSP "ir a la implementación" desde un nodo de decisión) y necesita una arista consultable, no una estimación reextraída en tiempo de consulta.

Si su proyecto es mayormente documentos en prosa y PDF con poco historial de Claude Code, la pasada añade tiempo de compilación y muy pocas aristas útiles — déjela desactivada.

Dónde reside

Implementación principal: MD0. Registro de la herramienta: tesserae/mcp_server.py.

Advertencias

• El nivel de identificador desnudo es deliberadamente conservador — requiere un acierto en el índice y una no-stopword. Los identificadores demasiado comunes (run, get, set) aún pasan el filtro de stopwords pero quedan ahogados por el fanout hacia muchos archivos; esto es un compromiso conocido, no un bug.
• El fanout por mismo nombre es por tipo: una mención de User que coincide con un CodeClass y un CodeRoute produce aristas a ambos. Si solo quiere la clase, filtre en tiempo de consulta por target.kind == "CodeClass".
• La pasada se ejecuta después de sync-code (o ingest-code) — si activa la funcionalidad H sin un grafo de código poblado, no tiene nada con qué enlazar y produce cero aristas. El orden de compilación se gestiona automáticamente; no se requiere secuenciación manual.
• La lista de stopwords es global, no por lenguaje; un proyecto Rust que legítimamente quiera Vec como identificador ya funciona (Vec no está en el conjunto de stopwords), pero las anulaciones locales al proyecto son un seguimiento planificado para v0.4.

2. tesserae project sync-code — adaptador de CodeGraph, 21 lenguajes

Qué es

Un nuevo subcomando de la CLI que importa un índice SQLite externo de colbymchenry/codegraph al ResearchGraph tipado de Tesserae. CodeGraph es un extractor políglota de grafos de código basado en tree-sitter con su propio servidor MCP; el adaptador lee su .codegraph/codegraph.db, traduce cada fila a un ResearchNode de Tesserae, y escribe .tesserae/code-graph.json para que el siguiente tesserae project compile lo recoja — exactamente como la salida de ingest-code de la v0.2.0, pero poblado desde una base de lenguajes mucho más amplia.

La cobertura de lenguajes salta de 1 a 21: TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Scala, Dart, Svelte, Vue, Liquid, Pascal/Delphi, Lua, y Luau. (El extractor de ast de la librería estándar de tesserae project ingest-code de la v0.2.0 sigue funcionando sin cambios para usuarios que quieren una ruta exclusiva para Python sin dependencia de runtime Node.)

Para representar lo que tree-sitter realmente expone a través de esos lenguajes, v0.3.0 añade 14 nuevas variantes de ResearchNodeType:

…y 8 nuevos tipos de arista: implements, exports, references, instantiates, overrides, decorates, type_of, y returns. Estas aristas se mapean directamente sobre lo que el resolver de CodeGraph computa por lenguaje; las aristas existentes de Tesserae calls, imports, inherits_from, contains, y declared_in permanecen sin cambios y continúan poblándose.

La decisión de diseño más importante en el adaptador es la estrategia id_seed. El identificador de fila propio de CodeGraph incrusta start_line, de modo que el mismo símbolo obtiene un nuevo id cada vez que se añade una línea en blanco encima — fatal para las aristas aguas abajo que almacenan el id. El adaptador descarta el id de CodeGraph y resiembra el id de Tesserae como f"{file_path}:{kind}:{qualified_name}". Resultado: el id de Tesserae de un símbolo sobrevive sin cambios a las ediciones que desplazan líneas, y las coincidencias por identificador desnudo de la funcionalidad H en los hallazgos de sesión siguen resolviendo al mismo nodo a través de muchas compilaciones.

Cómo usarlo

# Una pasada: lee .codegraph/codegraph.db, escribe .tesserae/code-graph.json,
# luego la siguiente compilación lo recoge.
tesserae project sync-code

# Raíz de proyecto explícita + rutas personalizadas de DB / salida
tesserae project sync-code \
  --project /path/to/repo \
  --db /path/to/.codegraph/codegraph.db \
  --output /path/to/.tesserae/code-graph.json

# Bucle de vigilancia — re-ejecuta sync-code cada vez que cambia la DB.
# Útil si no quiere el hook SessionStart de la funcionalidad 3 pero aún
# quiere que el grafo de código se mantenga fresco mientras edita.
tesserae project sync-code --auto-sync

Un flujo típico de extremo a extremo en un proyecto nuevo:

# 1. Que CodeGraph indexe el repo (su propia CLI; configuración única)
npx codegraph index .

# 2. Llevar eso al grafo tipado de Tesserae
tesserae project sync-code

# 3. La compilación normal recoge code-graph.json y (si está activada) ejecuta la funcionalidad H
export TESSERAE_INSIGHT_SYMBOL_LINK=true
tesserae project compile

# 4. Ahora haga preguntas que abarquen prosa y código
tesserae project ask "Which functions implement the RRF fusion decision?"

Cuándo activarlo

• Su proyecto es cualquier cosa distinta a Python puro, o Python puro más un frontend en Node.
• Ya utiliza CodeGraph por su servidor MCP de "find references" / "find implementations" — el adaptador permite que el mismo índice alimente el grafo tipado de Tesserae sin coste adicional de extracción.
• Quiere granularidad a nivel de ruta o componente (CodeRoute, CodeComponent) además de funciones y clases, algo que la ingest-code de v0.2.0 no produce.

Si solo trabaja con Python y no quiere un runtime de Node en su cadena de herramientas, tesserae project ingest-code (v0.2.0) sigue funcionando y produce un code-graph.json compatible.

Dónde reside

Implementación principal: MD0. Cableado de la CLI: tesserae/cli.py (el subparser sync-code, alrededor de la línea 897). El subcomando ingest-code de v0.2.0 en tesserae/code_graph_extractor.py está sin cambios.

Advertencias

• Requiere un .codegraph/codegraph.db poblado (el paso único propio de CodeGraph npx codegraph index .). El adaptador falla rápido con un mensaje de error accionable si la DB no existe.
• El resolver de CodeGraph es de mejor esfuerzo a través de 21 lenguajes; espere referencias ocasionalmente sin resolver en genéricos patológicos o en código con muchas macros. El adaptador registra lo que CodeGraph emite y no intenta volver a resolver.
• Algunos tipos de nodo (CodeParameter, CodeField) solo se emiten cuando el extractor por lenguaje de CodeGraph los expone — la cobertura varía por lenguaje. El tipo de respaldo CodeSymbol captura cualquier cosa que tree-sitter vea y que aún no hayamos tipado, de modo que nada se descarta silenciosamente.
• Las escrituras atómicas usan PID + sufijo aleatorio para el archivo temporal (no un .tmp compartido) para que dos invocaciones concurrentes de sync-code no colisionen — esto coincide con el mismo arreglo que recientemente aterrizó en el escritor del manifiesto por lotes.

3. Hook SessionStart de sync-code en vivo (post-v0.3.0 en main)

Qué es

Un pequeño hook SessionStart en el plugin de Tesserae que cierra el ciclo del "grafo de código que se mantiene actualizado". El servidor MCP de CodeGraph ya auto-vigila el sistema de archivos y mantiene .codegraph/codegraph.db fresco mientras edita — pero el .tesserae/code-graph.json de Tesserae solo se refrescaba cuando ejecutaba sync-code a mano. Este hook ejecuta en segundo plano tesserae project sync-code --project <root> cada vez que Claude Code abre una sesión, pero solo si la DB SQLite es más nueva que el JSON derivado.

Activado por defecto; opt-out por proyecto vía frontmatter en .claude/tesserae.local.md:

---
hooks:
  sync_code_on_start: false
---

El hook se omite silenciosamente cuando se cumple cualquiera de lo siguiente, de modo que nunca añade ruido a proyectos que no usan CodeGraph:

• El proyecto no usa CodeGraph (no hay .codegraph/codegraph.db).
• .tesserae/code-graph.json ya está al mismo nivel o más nuevo que la DB.
• El binario tesserae no está en el PATH.
• Otro sync-code ya está corriendo para la misma raíz de proyecto (una guarda de reentrada basada en pgrep que refleja la guarda de compile de SessionEnd que aterrizó en 0a3d35f).
• El usuario optó por no usarlo mediante sync_code_on_start: false.

Cuando sí se activa, se ve una línea en la cabecera de la sesión:

  ⟳ syncing code-graph from CodeGraph (background)

…y la invocación real de sync-code corre desacoplada (setsid → nohup → fallback & desnudo), con la salida capturada en .tesserae/.session-start-hook.log para que pueda inspeccionar qué ocurrió sin que se filtre a la transcripción de la sesión de Claude.

Este hook aterrizó post-v0.3.0 en main (PR #11, commit 395e9fb) y se enviará en la próxima publicación de compile / marketplace de plugins; el propio PyPI de v0.3.0 no lo empaqueta porque el hook vive en el plugin, no en el paquete Python tesserae.

Cómo usarlo

Si instaló el plugin de Tesserae a través del marketplace de Claude Code, ya lo tiene — el hook está activado por defecto. Para verificar que se ejecutó:

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

Para desactivarlo en un solo proyecto (por ejemplo, un repositorio exclusivamente en Python donde se prefiere ingest-code):

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

This project uses `tesserae project ingest-code` (Python AST) instead of
the CodeGraph adapter, so the live sync-code hook is disabled.
EOF

Para forzar una sincronización puntual sin esperar a una nueva sesión, simplemente ejecute tesserae project sync-code directamente — el hook y el comando manual comparten la misma guarda pgrep, por lo que no se ejecutarán por duplicado.

Cuándo activarlo

• Quiere la propiedad de "se mantiene actualizado" sin tener que acordarse de re-ejecutar sync-code después de cada tanda de ediciones.
• Sus sesiones de editor son cortas y frecuentes (abrir una sesión, hacer una pregunta, cerrar) — el hook asegura que cada nueva sesión vea un grafo de código actual.
• Ya está ejecutando el servidor MCP de CodeGraph con vigilancia de archivos — el hook simplemente propaga esa frescura a Tesserae.

Déjelo desactivado cuando esté en un bucle interno apretado y no quiera que se genere trabajo en segundo plano por sesión, o cuando el proyecto no use CodeGraph en absoluto (el hook se vuelve un no-op silencioso en ese caso, pero el opt-out explícito es más limpio).

Dónde reside

• Punto de entrada del hook: MD0
• Parseador de configuración: MD0 — la tabla read_plugin_setting ganó un valor por defecto sync_code_on_start=true.
• Guarda de reentrada: el mismo patrón pgrep -f "tesserae project sync-code.*${project_root}" que la guarda de compile de SessionEnd (hooks/session-end.sh).

Advertencias

• El hook solo se dispara en SessionStart, no en cada guardado de archivo. Si quiere que sync-code se ejecute continuamente mientras edita (sin abrir una nueva sesión de Claude), use tesserae project sync-code --auto-sync de la funcionalidad 2 en una terminal aparte.
• La comparación de mtime usa stat -f %m de BSD (macOS) → stat -c %Y de GNU (Linux) → fallback [[ A -nt B ]]. En sistemas de archivos exóticos con mtimes de baja resolución, ocasionalmente puede omitir una sincronización que se ejecutó menos de un segundo después de un índice de CodeGraph — la siguiente sesión lo recogerá.
• El spawn en segundo plano usa setsid cuando está disponible, nohup a continuación, y luego un & desnudo. En shells extremadamente restringidos donde ninguno de estos desacopla el proceso, la sincronización aún se ejecutará pero puede bloquear el inicio de sesión durante unos segundos. Abra un shell amigable con la terminal o establezca sync_code_on_start: false en ese caso.

Actualización desde v0.2.0

pip install --upgrade tesserae==0.3.0

Esa es toda la actualización — v0.3.0 es aditiva sin cambios disruptivos. El comportamiento por defecto de tesserae project compile no cambia; las piezas nuevas son opcionales y se descubren con facilidad.

Variable de entorno para la nueva pasada opcional (funcionalidad 1):

# Activa la pasada post-compilación de aristas discusses prosa-a-código (funcionalidad H)
export TESSERAE_INSIGHT_SYMBOL_LINK=true

Nuevo subcomando de CLI para añadir a su memoria muscular (funcionalidad 2):

tesserae project sync-code             # importación puntual CodeGraph → Tesserae
tesserae project sync-code --auto-sync # bucle de vigilancia

El subcomando tesserae project ingest-code de v0.2.0 sigue funcionando sin cambios — elija sync-code si su proyecto usa algo más allá de Python, elija ingest-code si no quiere una dependencia de runtime Node.

Nueva herramienta MCP que el agente ahora tiene disponible (funcionalidad 1):

• find_code_symbol_mentions(node_id) — extracción de símbolos en tiempo de consulta sobre el cuerpo de cualquier nodo.

Nueva configuración del plugin (funcionalidad 3, post-v0.3.0 en main):

# .claude/tesserae.local.md
---
hooks:
  sync_code_on_start: true   # default; set to false to disable the live sync hook
---

Todo lo demás — graph_ppr, search_nodes híbrido, embedding_status, list_communities, fresh_insights, resúmenes de comunidad, scoring por decay, supersedes, schema-drift, slash commands, la proyección wiki / Obsidian — está sin cambios respecto a v0.2.0.

Contexto estratégico

Tesserae v0.2.0 sentó las bases con nodos tipados de grafo de código y las primitivas del lado de la prosa (decay, supersedes, resúmenes de comunidad). v0.3.0 es la versión donde las dos mitades se conectan: la funcionalidad H acuña aristas tipadas discusses desde decisiones e hipótesis hacia los símbolos que tocan, y el adaptador de CodeGraph hace que esos símbolos cubran el stack políglota que un codebase de investigación real utiliza realmente — TypeScript, Rust, Go, Swift, y 17 más — en lugar de solo Python.

El panorama de PKM-AI de la ola 1 que estudiamos antes de este hito no tiene otra herramienta que haga esto. Cursor Memories es una bolsa de texto por proyecto — sin grafo, sin aristas tipadas. CLAUDE.md de Claude es un único archivo markdown plano. Cline memory-bank es un directorio de archivos markdown, sin extracción tipada. CONVENTIONS.md de Aider es un único archivo de prefijo de prompt. Ninguno de ellos enlaza una decisión en prosa con la función o clase que la implementa; ninguno de ellos sabe que un Decision y una CodeRoute son tipos diferentes de cosa. La arista discusses de v0.3.0 a través de 21 lenguajes de nodos de código tipados es la cuña — y el hook SessionStart en vivo es lo que hace que esa cuña se sienta como una propiedad del entorno en lugar de un flujo de trabajo que el usuario deba recordar.

El competidor más cercano en el espacio más amplio de GraphRAG — Microsoft GraphRAG — tiene entidades tipadas y resúmenes de comunidad (que Tesserae v0.2.0 refleja) pero ninguna capa de grafo de código en absoluto; es un sistema corpus-RAG, no un compilador de memoria de proyecto. La primitiva PPR de HippoRAG 2 (Tesserae v0.2.0) y las operaciones de memoria de Mem0 (Tesserae v0.2.0 supersedes) completan el estado del arte del lado de la prosa. v0.3.0 añade la dimensión que ninguno de ellos toca: aristas tipadas desde los propios hallazgos del agente hacia nodos tipados que representan el código del que tratan esos hallazgos, en los lenguajes en los que están realmente escritos los codebases reales.

Véase también:

• Notas de la versión v0.2.0 — recuperación tipada, grafo de código (Python), evolución de ontología
• Visión general de la arquitectura — mapa de módulos y pipeline
• Mapa de funcionalidades — tabla completa de estado de funcionalidades con enlaces al código fuente
• Integración de sesiones — los nodos de origen de hallazgos de sesión desde los que enlaza la funcionalidad H
• Integración MCP — lista completa de herramientas MCP (la nueva herramienta find_code_symbol_mentions aterrizará aquí en el próximo pase de documentación)