Tu README explica la arquitectura. La carpeta de documentación explica las decisiones. Y, hasta hoy, nada de eso existía en el grafo de conocimiento de Octocode.

0.20.0 cierra esa brecha: los archivos Markdown ahora son nodos del grafo de conocimiento de GraphRAG, y los enlaces entre documentos se convierten en relaciones tipadas references que un asistente de IA puede recorrer de verdad.

Era una carencia que me molestaba desde hacía tiempo. Octocode siempre pudo encontrar tu documentación — la búsqueda semántica indexaba Markdown desde el principio —, pero encontrar un documento por una palabra clave y descubrirlo siguiendo la estructura del proyecto son dos cosas distintas. Un asistente que preguntara «¿qué depende del módulo de pagos?» podía recorrer el grafo de código sin problemas y, aun así, pasar por alto la nota de arquitectura situada tres directorios más allá que explica por qué el módulo es como es.

El código contaba la mitad de la historia. Ahora el grafo conoce la otra mitad.

Qué cambió de verdad

En pocas palabras: durante la indexación, los documentos Markdown ahora pasan por el mismo flujo de GraphRAG que el código fuente. Las consultas al grafo, la expansión de relaciones y la herramienta MCP graphrag pueden mostrar la documentación junto al código, no como una búsqueda independiente, sino como parte del mismo recorrido.

Estos son los mecanismos que lo hacen útil sin añadir ruido:

Los enlaces entre documentos se convierten en relaciones references. Cuando un archivo Markdown enlaza a otro — [see the guide](guide.md) —, Octocode registra una arista tipada entre ambos. Los enlaces relativos se resuelven respecto a la ubicación del archivo de origen, los fragmentos de ancla (#section) se eliminan y las URL externas http:///https:// se ignoran. La estructura de enlaces de tu documentación siempre fue un mapa. Ahora el grafo sabe leerlo.

El peso está elegido a propósito. Al recorrer el grafo, references tiene un peso de importancia de 0.6: queda por debajo de relaciones estructurales del código como imports y calls (0.7), pero por encima de relaciones organizativas como pertenecer al mismo directorio (0.3). Así, los enlaces entre documentos orientan la expansión sin eclipsar la estructura del código. Un enlace entre dos documentos equivale a una persona diciendo «estos dos van juntos». Es una señal real, pero no es lo mismo que una arista de llamada, y los pesos reflejan esa diferencia.

Los archivos .markdown funcionan en todos los lugares donde funciona .md. Tanto en la búsqueda semántica como en la nueva integración con el grafo. Es un detalle pequeño, pero esa incoherencia causaba problemas en repositorios antiguos.

Y esta es la parte de la actualización que más me gusta: no hace falta volver a indexar desde cero. El contenido Markdown ya está guardado en los bloques de documentos del índice, así que al reconstruir el grafo se recupera de la base de datos existente. Ejecuta octocode index o reconstruye el grafo y aparecerá tu documentación.

El error que ocultaba relaciones sin avisar

Para algunos, esta corrección importa más que la propia función.

Al recuperar las relaciones de LanceDB, solo se devolvía una parte del conjunto de resultados almacenado: los lotes posteriores se descartaban en lugar de concatenarse. En proyectos pequeños era imperceptible. En los grandes, las consultas al grafo podían omitir sin aviso conexiones que deberían existir.

«Sin aviso» es la clave. No había error ni advertencia: solo un grafo incompleto que parecía estar entero. Si alguna vez consultaste el grafo de un repositorio grande y pensaste «aquí debería haber más aristas», esta era probablemente la causa. Ahora, al reconstruir o recargar el grafo, se recupera el conjunto completo de relaciones.

Junto con esta corrección llegaron otras dos relacionadas:

  • Los encabezados de Markdown ya no contaminan el índice de símbolos del código. Los encabezados de los documentos se indexaban como «símbolos» y la resolución de imports encontraba coincidencias con ellos, lo que generaba falsos candidatos a relaciones. Ahora los nodos Markdown se excluyen del índice de símbolos, aunque siguen participando en el grafo mediante enlaces basados en rutas.
  • Los nodos Markdown se resuelven por ruta, no por símbolo. En el recorrido optimizado que descubre relaciones, los documentos pasan por la resolución basada en rutas — que es como funcionan realmente sus enlaces — en lugar de usar la coincidencia por símbolos propia del código. Ahora las aristas entre documentos son precisas, no fruto de una coincidencia.

La mitad de memoria al cargar relaciones

Los volcados de la indexación incremental podían escribir la misma relación más de una vez en distintos lotes. En un proyecto grande real, el cargador acababa leyendo 575 000 filas para representar 288 000 relaciones únicas: casi la mitad del conjunto eran duplicados.

Ahora las relaciones se deduplican por la terna (source, target, type) al cargar el grafo. Esto reduce aproximadamente a la mitad el uso de memoria y acelera todas las operaciones del grafo que recorren el conjunto completo. Cuando elimina duplicados, el cargador informa de cuántos ha descartado para que puedas comprobar el resultado.

No hay que cambiar la configuración. La carga, sencillamente, consume menos.

Todo lo demás

El servidor MCP se ha actualizado a rmcp 3.0.0. El SDK de Model Context Protocol subyacente pasó a una nueva versión mayor, lo que mantiene Octocode al día con el ecosistema MCP y su transporte HTTP con streaming. Los modos de servidor por stdin y HTTP funcionan como antes; no hace falta cambiar la configuración.

La gestión de la configuración se ha trasladado a octolib. La lógica genérica para gestionar archivos de configuración y migrarlos entre versiones — recorrido de versiones, comprobaciones y combinación de tablas — ahora vive en la biblioteca compartida octolib. Octocode conserva únicamente sus pasos de migración de v1 a v2. Para ti, el cambio es transparente: las configuraciones existentes se migran exactamente igual que antes. La ventaja es que las correcciones de esta lógica se aplican una sola vez a todas las herramientas basadas en octolib, en vez de trasladarlas repositorio por repositorio.

La documentación también ha recibido atención. El README ahora cubre todo el conjunto de herramientas MCP, incluidas las basadas en LSP (lsp_goto_definition, lsp_find_references, lsp_hover, lsp_document_symbols, lsp_workspace_symbols, lsp_completion), y explica cómo activarlas con --with-lsp. También hay nuevas guías independientes del proveedor para conectar Octocode a cualquier LLM o endpoint de embeddings compatible con OpenAI, ya sea un servidor de modelos local o un proveedor alternativo en la nube.

Actualizar

# Homebrew
brew upgrade muvon/tap/octocode

# Instalador universal
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh

# Cargo
cargo install octocode --version 0.20.0

Es una actualización directa: no requiere cambios de configuración y los archivos existentes se migran automáticamente. Solo hay que hacer una cosa después:

Reconstruye el grafo (o simplemente ejecuta octocode index) en un proyecto con documentación real. Después, hazle al asistente una pregunta que antes exigía que una persona conectara el código con la documentación — «¿dónde se gestiona la autenticación y qué dice al respecto la guía de seguridad?» — y observa cómo recorre ambos.

Octocode es software de código abierto (Apache 2.0) disponible en github.com/Muvon/octocode, y es el motor de búsqueda de código que impulsa Octomind. El grafo ya sabía cómo encajaba tu código. Ahora también sabe lo que has escrito sobre él.