Graphify: dale a tu agente de IA un mapa de tu proyecto en vez de un buscador

Cada vez que le preguntas algo a tu agente de IA sobre tu proyecto, repite el mismo ritual: grep por aquí, abrir un archivo por allá, leer 200 líneas para quedarse con 5. Y en la siguiente pregunta, vuelta a empezar. Todo ese trabajo de exploración se paga en tokens y en tiempo, y se tira a la basura cuando termina la sesión.

Graphify ataca ese problema con una idea simple: escanea tu proyecto una vez, construye un grafo de conocimiento con sus conceptos y relaciones, y a partir de ahí el agente consulta el grafo en lugar de redescubrir el código en cada pregunta.

La idea no es nueva. Andrej Karpathy popularizó el concepto de alimentar una wiki personal donde documentos, código e ideas quedan conectados como nodos de un grafo que luego puedes consultar. Es una alternativa ligera a montar un RAG completo: sin embeddings, sin base de datos vectorial, solo archivos conectados entre sí. Graphify es una de las implementaciones más sencillas de usar de ese concepto, y no está atada a ningún agente concreto: funciona con Claude Code, Cursor, Copilot y una larga lista de asistentes.

Qué hace exactamente Graphify

El flujo tiene tres piezas:

1. Escaneo único: el agente analiza tu proyecto y extrae entidades y relaciones. El código se procesa con tree-sitter (AST real, 36 lenguajes, coste cero en tokens). Los documentos, PDFs e imágenes pasan por el modelo, que es donde se gastan los tokens.
2. El grafo: los nodos no son archivos, son conceptos (una clase, un patrón, una idea de un documento). Graphify detecta comunidades (grupos de nodos muy conectados) y god nodes (los nodos más conectados, tus abstracciones centrales).
3. Consultas: en lugar de buscar a ciegas, el agente pregunta al grafo con graphify query, graphify path o graphify explain.

Un detalle que me gusta: cada arista lleva una etiqueta de honestidad. EXTRACTED si la relación es explícita en el código (un import, una llamada), INFERRED si el modelo la dedujo, y AMBIGUOUS si no está seguro. Sabes en todo momento qué parte del grafo es hecho y qué parte es interpretación.

El resultado son tres archivos en graphify-out/:

Todo funciona en local. No necesitas cuenta, ni API key propia de Graphify: usa el agente que ya tienes.

Ejemplo práctico: grafo de un proyecto real

Para no quedarme en la teoría, construí un proyecto de ejemplo público en GitHub — graphify-demo-biblioteca, una API de gestión de biblioteca en TypeScript con arquitectura por capas (HTTP → servicios → dominio → repositorios) y comunicación por eventos: cuando se crea o devuelve un préstamo, el LoanService publica un evento en un EventBus en memoria y el NotificationService reacciona notificando al socio. Lo suficientemente real como para tener relaciones interesantes que descubrir, lo suficientemente pequeño como para poder revisar el grafo entero.

Ejecuté Graphify sobre ese repo y medí cada paso. Estas son las cifras reales de ese escaneo; en tu proyecto variarán con el tamaño y la forma del código.

Paso 1: instala los requisitos

Necesitas Python 3.10+ y uv (el gestor de entornos de Python):

python3 --version   # 3.10 o superior
curl -LsSf https://astral.sh/uv/install.sh | sh

Paso 2: instala Graphify

uv tool install graphifyy   # ojo: doble "y" en el nombre del paquete
graphify install            # registra el skill en tus agentes de IA

El segundo comando deja Graphify disponible como comando slash en tus asistentes. Si quieres instalarlo solo para uno concreto, la documentación tiene el comando específico para cada agente.

Paso 3: construye el grafo

Abre tu agente (en mi caso Claude Code) dentro del proyecto y lanza:

/graphify .

El agente detecta el corpus, extrae el código por AST y despacha subagentes en paralelo para los documentos. En graphify-demo-biblioteca:

• Corpus detectado: 22 archivos, ~2.360 palabras (17 de código, 5 documentos: README, ARCHITECTURE.md y dos ADRs).
• Extracción del código: 123 nodos por AST, 0 tokens gastados.
• Extracción semántica (los 5 documentos, un único subagente): 52.620 tokens.
• Grafo final: 139 nodos, 300 aristas, 9 comunidades.

Un proyecto de este tamaño cabe entero en el contexto de un agente, así que el escaneo aquí es barato. La proporción cambia con el tamaño: en el blog sobre el que escribo estos artículos (Astro + TypeScript + Markdown, ~89.000 palabras) el mismo proceso generó un grafo de 419 nodos y consumió 204.000 tokens en la extracción semántica. Se paga una vez, queda cacheado, y /graphify . --update solo reprocesa lo que cambió.

Paso 4: explora lo que ha encontrado

Al abrir graph.html ves las comunidades que ha detectado: agrupó el código por concepto, no por carpeta — “Domain Events”, “Event Bus & Repository Pattern (ADRs)”, “HTTP Layer”, “Domain Models & Policy”… El informe (GRAPH_REPORT.md) lista los god nodes, los nodos con más conexiones: MemberRepository, LoanService y BookRepository salieron arriba del todo, justo donde está la lógica de negocio real del proyecto. Y detectó automáticamente que las dos ADRs (0001-event-bus-en-memoria.md y 0002-repositorios-en-memoria.md) documentan el mismo patrón arquitectónico — algo que el propio repo no dice en ningún sitio de forma explícita.

Este es el grafo real, interactivo — puedes arrastrar los nodos y hacer zoom sobre las comunidades que ha detectado:

El código y el grafo completo (graph.html, GRAPH_REPORT.md, graph.json) están en github.com/jalucenyo/graphify-demo-biblioteca, dentro de graphify-out/. Puedes clonarlo y regenerarlo tú mismo con /graphify ..

Paso 5: consulta el grafo

graphify query "How does the loan creation flow work and which components does it touch?"
graphify path "LoanService" "NotificationService"
graphify explain "EventBus"

query hace un recorrido BFS desde los nodos que casan con tu pregunta y devuelve el subgrafo relevante con archivos y líneas. path te da la ruta más corta entre dos conceptos (perfecto para “¿cómo llega esto hasta aquello?”). explain resume un nodo en lenguaje natural.

Tip: formula las consultas con el vocabulario del grafo (los nombres que ves en graph.html). El matching es léxico y una consulta con términos genéricos arrastra nodos irrelevantes.

Las métricas: A/B real con la misma pregunta

Para medir la mejora hice el experimento completo sobre graphify-demo-biblioteca: la misma pregunta (“¿cómo funciona el flujo de creación y devolución de un préstamo, qué componentes toca y cómo se notifica al socio?”) respondida por dos agentes limpios e independientes, sin memoria compartida entre ellos. Uno solo podía usar graphify query; el otro, exploración clásica con grep y lectura de archivos.

Aquí sí, con este proyecto, Graphify gana en operaciones y en tokens: 3 llamadas contra 10, y un 16% menos de tokens. Cada respuesta del grafo llega ya conectada — el agente no necesita abrir loan-service.ts, event-bus.ts y notification-service.ts por separado para deducir que uno llama al otro; el grafo ya tiene esa arista.

El tiempo quedó prácticamente empatado, dentro del margen de ruido de una sola ejecución. No le daría demasiado peso a esa cifra sin repetir el experimento varias veces.

Hay un matiz que la tabla no captura: la respuesta con grafo fue honesta sobre sus límites. Como no encontró una arista explícita de llamada entre LoanService y EventBus.publish(), lo dijo claramente en vez de inventarla — dedujo la relación por la agrupación en comunidades, no por una arista directa. La respuesta tradicional, en cambio, sí pudo dar la línea exacta (loan-service.ts:43) porque leyó el archivo entero. Es el trade-off real: el grafo solo sabe lo que se extrajo en el escaneo, y para relaciones muy finas (una línea concreta dentro de un método) todavía gana leer el código fuente directamente.

Comparado con el experimento que hice antes sobre el blog de más de cien archivos de código y Markdown, ahí Graphify ganaba en operaciones y tiempo pero perdía en tokens (+17%): un grep bien dirigido en un proyecto grande, pero con la respuesta concentrada en pocos archivos, puede seguir siendo más barato en tokens que pagar la carga del grafo completo. La lección de los dos experimentos juntos: el ahorro de Graphify no es un número fijo, depende de cuántos archivos tendría que abrir el agente tradicional para conectar las piezas — a más saltos entre archivos, más renta el grafo.

Cuándo usarlo (y cuándo no)

Mi lectura después de probarlo:

• ✅ Proyectos con lógica repartida en varias capas: aunque graphify-demo-biblioteca es pequeño, ganó en operaciones y tokens porque la respuesta requería conectar servicio, política, repositorio y bus de eventos — justo el patrón de “varios archivos que se relacionan entre sí” que el grafo ya tiene resuelto.
• ✅ Proyectos grandes o monorepos: aquí el ahorro en operaciones se nota todavía más. Planificar cambios que cruzan módulos con query y path ahorra exploración de verdad.
• ✅ Corpus de investigación: papers, notas, transcripciones. Aquí brilla incluso más que en código, porque no hay AST que te salve: el grafo es la estructura.
• ✅ Segundo cerebro: con la exportación a Obsidian o Neo4j, el grafo crece con cada documento que añades (graphify add <url>).
• ❌ Preguntas que se responden con un archivo suelto: si la respuesta vive entera en un único fichero, abrirlo directamente sigue siendo más simple que consultar el grafo.

Para mí, lo más potente no es el ahorro puntual de una consulta, sino el cambio de modelo: el conocimiento del proyecto deja de ser algo que el agente reconstruye en cada sesión y pasa a ser un artefacto persistente que mantienes, versionas y consultas. El siguiente paso concreto: instálalo, lánzalo sobre tu proyecto más grande y abre el graph.html — las comunidades que detecta te van a contar cosas de tu arquitectura que no tenías escritas en ningún sitio.

Preguntas frecuentes

¿Necesito una API key para usar Graphify?

No. Graphify usa el agente de IA que ya tienes (Claude Code, Cursor, etc.) como modelo de extracción y consulta. Opcionalmente puede usar Gemini para la extracción semántica si defines GEMINI_API_KEY.

¿Cuánto cuesta el escaneo inicial?

Depende del volumen de documentación: el código se extrae por AST gratis; los documentos pasan por el modelo. En graphify-demo-biblioteca (~2.400 palabras) fueron ~53.000 tokens; en un proyecto bastante más grande como este blog (~89.000 palabras) fueron ~204.000. En monorepos grandes puede superar el millón. Es un coste único: --update solo reprocesa cambios.

¿En qué se diferencia de un RAG?

Un RAG recupera fragmentos por similitud semántica con embeddings; Graphify modela relaciones explícitas entre conceptos y las recorre como grafo. Es más simple de mantener (archivos conectados, sin infraestructura vectorial) y las respuestas llegan con la cadena de relaciones, no como trozos sueltos.

¿Funciona solo con código?

No. Acepta código, Markdown, PDFs, imágenes e incluso vídeo (lo transcribe). Para corpus de investigación o documentación es donde más aporta frente a las herramientas de búsqueda clásicas de los agentes.