Taller Graphify
Indexa un repo o /raw, navega el grafo, decide con criterio
Knowledge graph + skill en tu agente + cuadrante de decisión honesto.
90-120 min para salir con un veredicto razonado: adoptas Graphify o no — con datos.
Lo que vamos a recorrer en 90 minutos
6 capítulos. La mitad del tiempo en hands-on real. El output del taller no es la herramienta funcionando — es tu veredicto razonado.
El context budget se rompe antes de empezar
Cuatro síntomas reconocibles. Si te pasan los cuatro, este taller es para ti — y probablemente Graphify (o una alternativa) compensa.
Releer 40 ficheros por sesión
Cada vez que preguntas "qué depende de X", tu agente lee el corpus desde cero. ~20k tokens consumidos antes de empezar a responder.
Instruction budget reventado
Modelos frontier siguen ~150-200 instrucciones por context. Sumas prompt + AGENTS.md + tools + skills y ya estás en 300+. El modelo atiende a medias.
Conocimiento que no acumula
Cada sesión empieza de cero. Lo que descubriste ayer no llega a hoy. RAG sin estado no aprende.
RAG vectorial falla en cross-doc
Vector mete chunks aleatorios. Si la respuesta vive *entre* dos documentos (X depende de Y), no la encuentra.
Datos del experimento real sobre el wiki de Código Sin Siesta: pasar de ~76k tokens por consulta a ~3,5k. 22-30× reducción (los 71× del marketing son para corpus mucho más grandes).
Solo tres primitivas. El grafo emerge si tomas notas con cuidado.
Wikipedia, Google Knowledge Graph y este wiki personal son lo mismo en el fondo: nodos + aristas + triples.
Node
Una entidad nombrada. Una página, una función, una clase, un concepto, una persona.
`tool-registry.ts`, `Anthropic`, `MCP`Edge
Relación tipada entre dos nodos. Citation, import, depends_on, conceptually_related_to.
chat.ts —imports→ tool-registry.tsTriple
Sujeto-predicado-objeto. Una afirmación contextualizada. La forma básica de codificar conocimiento.
"Graphify usa Tree-sitter para AST""I don't want a chatbot. I want a librarian."
— Andrej Karpathy, 2026
Un chatbot es un oráculo (preguntas, contesta, olvida). Un bibliotecario conoce sus libros: sabe cuál cita a cuál, cuáles tratan el mismo tema con posturas distintas, cuáles son fundacionales. Eso es un knowledge graph aplicado a un agente.
Cuatro capas. Solo una cuesta tokens.
Conocer qué pagas y por qué te hace usuario crítico, no promotor entusiasta.
AST determinístico
GratisTree-sitter (12+ lenguajes)
Parsea código y extrae funciones, clases, métodos, imports. Sin LLM. Para repos puros, suficiente.
Extracción semántica
~$0.30-0.80Subagentes Claude paralelos
Procesa docs/PDFs/imágenes. Devuelve nodos+aristas con EXTRACTED/INFERRED/AMBIGUOUS y confidence_score. La capa cara y la única donde tu API key entra.
Clustering Leiden
GratisNetworkX + Leiden
Detecta comunidades temáticas. Identifica god nodes (más conectados) y surprising connections (alta similitud cross-community).
Outputs persistentes
0 LLM (regeneración)JSON + HTML + Obsidian + MCP
graph.json (consumible), GRAPH_REPORT.md (legible), graph.html (Pyvis interactivo), vault Obsidian opcional, servidor MCP. Vive entre sesiones.
Lección clave: en el experimento real sobre el wiki de Código Sin Siesta, las capas 1+3+4 son regenerables casi gratis. La capa 2 cuesta ~$0.50 por pase completo y es el único cuello de botella económico para iterar.
Cinco outputs. Cada uno tiene un consumidor distinto.
La trampa frecuente: generar todo y solo mirar el HTML.
El output que más rentabiliza el coste del primer pase es graph.json consumido vía skill.
| Output | Tamaño típico | Consumidor | Cuándo |
|---|---|---|---|
graph.json | 50-500 KB | Tu agente vía skill | Siempre. Es el activo persistente. Versionable, re-consultable indefinidamente. |
GRAPH_REPORT.md | 10-30 KB | Tú, lectura humana | Justo después del primer pase. God nodes + surprising connections + suggested questions. |
graph.html | 200-500 KB | Tú, exploración visual | Cuando el reporte te llama la atención sobre algo concreto. Pyvis sobre WebGL, sin servidor. |
obsidian/ | Vault entero | Tu vault si lo tienes | Opt-in con --obsidian. Cuidado: si apuntas a vault humano, mete cientos de notas. |
MCP server | 0 KB (proceso) | Otros agentes | graphify --mcp. Stdio. Claude Desktop, Cursor, agentes custom lo consumen. |
Graphify es una de cuatro herramientas. Conoce las otras tres antes de adoptarla.
| Herramienta | Scope | Determinismo | Coste | Privacidad | MCP |
|---|---|---|---|---|---|
| GitNexus | Solo código | 100% AST | Gratis | Local | ✓ |
| Graphify | Código + docs + papers + imágenes + vídeo | AST + LLM | ~$0.30-0.80 | LLM ve docs | ✓ |
| Vector RAG | Texto plano | Embeddings | Embeddings + storage | API ve chunks | Wrapper |
| Agentic search | Filesystem | Heurístico | Tokens del agente | Local | n/a |
Reglas prácticas
- ¿Cabe tu corpus en <30k tokens? → Agentic search puro. No indexes nada.
- ¿Solo código y privacidad alta? → GitNexus.
- ¿Heterogéneo y queries cross-document? → Graphify.
- ¿Corpus enorme y "encuéntrame parecido"? → Vector RAG.
- ¿Combinaciones? → Sí. Vector para "narrow", grafo para "navegar".
Caso real: Graphify sobre este propio wiki dijo NO.
85 docs markdown · 79.224 palabras · MOC manual + lint determinístico ya en su sitio.
201
Nodos extraídos
333
Aristas
16
Comunidades
29,9×
Reducción tokens
~$0,50
Coste real
0,05-0,07
Cohesion grandes
SÍ compensa
- Codebase desconocido y volátil (>5 cambios/día)
- Corpus heterogéneo grande (papers + tweets + screenshots)
- Necesitas exponer estructura vía MCP a varios agentes
- Quieres detectar patrones cross-proyecto
NO compensa
- Wiki ya curado con MOC manual (este caso)
- Corpus pequeño donde
rg+ lectura cubre - Repos puros de código → mejor GitNexus
- Preguntas únicas que no se repiten
Decisión razonada: NO adoptar como pipeline regular. Mantener para auditoría puntual cada >3× crecimiento (umbral: >200 ficheros / >150k palabras). El lint determinístico (gratis, segundos) detectó 130 asimetrías que Graphify no detecta. Para "encontrar enlaces faltantes", lint > Graphify.
Setup + primera ejecución sobre el starter
Output del hands-on: graph.json real, reporte leído, y ojo entrenado para distinguir lo que descubrió Graphify vs lo que esperabas.
uv. Si te falta uv, curl -LsSf https://astral.sh/uv/install.sh | sh.graphifyy con doble y; el binario es graphify.GRAPH_REPORT.md → graph.html → contrasta con tu predicción. Esa lectura es el output real.Skill en Claude Code + queries reales
Pasar de "tengo un graph.json precioso" a "el agente lo consulta de forma natural mientras trabajo".
Paso 1 · Instala la skill (3 min)
graphify claude install # CLAUDE.md + PreToolUse hook
graphify codex install # AGENTS.md
graphify cursor install # .cursor/rules/graphify.mdc
graphify opencode install # AGENTS.md + plugin
graphify aider install # AGENTS.mdPaso 2 · Tres queries dirigidas (10 min)
/graphify query "qué conecta tool registry con la decisión del LLM" Esperado: Camino chat → tool-registry → tool-grep, cruzado con docs cross-modal
/graphify path "auth" "chat" Esperado: 2-3 hops vía server.ts. Si "no path", el AST no enlazó middleware — lección práctica
/graphify explain "tool-registry" Esperado: Resumen + vecinos + dónde se cita en docs. Útil para onboarding rápido
Paso 3 · Contraste con rg puro (5 min)
Misma pregunta, dos vías. Anota: tiempo · tokens consumidos por el agente · calidad · ruido. Esa tabla es lo que te llevas — no Graphify funcionando, sino opinión razonada sobre cuándo el grafo gana.
Save-result loop: graphify save-result --question "..." --answer "..." --nodes A B guarda Q&As cerradas como nodos del grafo. Eso es lo que diferencia un grafo persistente de un RAG sin estado.
Tu grafo se vuelve infraestructura compartida
graphify --mcp levanta un servidor stdio. Cualquier agente compatible (Claude Desktop, Cursor, agentes custom) consume tu grafo sin tener Graphify instalado.
Tools expuestas vía MCP
query_graphget_nodeget_neighborsget_communitygod_nodesgraph_statsshortest_path
Read-only. Para modificar el grafo: --update manual desde el host.
Config en Claude Desktop
{
"mcpServers": {
"graphify": {
"command": "python3",
"args": [
"-m", "graphify.serve",
"/abs/path/to/graphify-out/graph.json"
]
}
}
}Caso real
Un equipo indexa su monorepo con Graphify, levanta el MCP server en CI, y todos los devs apuntan sus IDEs al mismo grafo. Cero indexación local. Coste: un re-pase nocturno (graphify --update) en CI ≈ $0,20/día.
⚠️ Trade-off de saturación: si conectas 10 MCP servers a la vez, las descripciones de tools llenan el context window. El instruction budget se revienta de otra forma. Activa solo los relevantes por sesión.
Cuatro palancas por ratio impacto/coste
El primer pase es caro. Los siguientes son baratos. Si solo haces el primer pase y nunca más, has tirado dinero.
Incremental con --update
graphify --update <path> Solo re-procesa ficheros modificados via cache SHA256. Code-only changes no llaman al LLM. Coste: fracción del primer pase.
Hooks git para rebuild automático
graphify hook install Tras cada commit, AST + rebuild de graph.json. Doc/image changes no trigger (requieren --update manual).
Vault Obsidian con namespace
graphify --obsidian-dir ~/vault/graphify/<proyecto> Mal patrón: apuntar a vault humano sin namespace. Buen patrón: subcarpeta dedicada para no enturbiar el grafo manual.
Save-result = memoria del agente
graphify save-result --question --answer --nodes Cada Q&A cerrada se guarda. La próxima --update la incorpora como nodo nuevo. El grafo aprende.
El save-result loop es lo que diferencia un grafo de un RAG. Tu RAG no aprende. El grafo persistente con save-result sí. Es acumulación, no consumo.
Cinco takeaways. Un siguiente paso esta semana.
Graphify resuelve un problema específico: context budget reventado por re-leer ficheros sobre corpus heterogéneos.
El cuadrante manda. Verifica que ninguna de las 3 alternativas (GitNexus, vector RAG, agentic search) cubre tu caso mejor.
AST gratis, semántica cuesta. Las 4 capas tienen rentabilidad distinta. Conoce qué pagas.
El grafo es activo persistente, no decorativo. Si solo abres el HTML al primer pase, has tirado dinero.
Honestidad: cada arista EXTRACTED/INFERRED/AMBIGUOUS. Cohesion en números. Diferencia con un RAG ingenuo.
El veredicto razonado del Ejercicio 3 es el output real del taller. La herramienta es útil solo si entra a tu workflow con criterio. Gracias por venir.