OpenWiki a prueba: Grounded Claims y una ejecución totalmente local con Ollama

La documentación se pudre porque se escribe una sola vez. La memoria sigue siendo útil porque se sobrescribe sin parar. Casi todo lo que pasa por documentación es en realidad lo primero disfrazado de lo segundo, y por eso se queda obsoleto.

OpenWiki, una herramienta de LangChain, es un intento interesante de cambiarlo. A continuación se explica qué hace y cómo funciona su mecanismo de autocorrección, y después viene una prueba real sobre un stack completamente open source con modelos locales. Esa ejecución produjo cuatro fallos distintos, un rescate casi cómico y un resultado mejor de lo esperado.

Qué es OpenWiki

LangChain, el equipo detrás de buena parte de la infraestructura open source para apps de IA, publicó OpenWiki como una utilidad de línea de comandos gratuita con licencia MIT. Se apunta a un repositorio, un agente estudia el código y escribe páginas markdown enlazadas entre sí en una carpeta llamada openwiki/. Conforme llegan commits, las páginas se actualizan.

El público principal no son las personas, porque la wiki está escrita para agentes. La herramienta inserta un puntero en AGENTS.md y CLAUDE.md, los archivos que Claude Code, Codex, Cursor y asistentes parecidos cargan al arrancar. Así, cualquier agente de código que abra el repositorio encuentra un mapa listo y se ahorra el habitual redescubrimiento de la arquitectura. Ojear un resumen cuesta muchos menos tokens y minutos que volver a peinar el código fuente.

Las actualizaciones salen del control de versiones. La herramienta comprueba qué commits llegaron desde la última ejecución, lee los diffs y reescribe solo las partes afectadas. Conectada a un job de CI programado, la wiki se refresca sola cada día y abre un pull request igual que lo haría un compañero humano.

Grounded Claims: hechos con pruebas adjuntas

Hay muchas herramientas que generan documentación. Lo que distingue a OpenWiki es un mecanismo llamado Grounded Claims («afirmaciones fundamentadas»), y merece una mirada atenta.

Cada afirmación importante vive en dos sitios. Es prosa en una página de la wiki y también una entrada estructurada en un archivo complementario que apunta a las líneas exactas de código que la respaldan, junto con un hash de esas líneas tal como estaban en ese momento.

Un ejemplo de la ejecución de prueba. Una página dice que los eventos se «persisted to the run_events table before any listeners are invoked» (guardan en la tabla run_events antes de invocar a cualquier listener). Su entrada complementaria vincula esa frase con las líneas 9 a 26 de un único archivo. Si cambian esas líneas, el hash almacenado deja de coincidir y la afirmación queda obsoleta. Eso obliga a regenerar la página en la siguiente ejecución, aunque el planificador de actualizaciones la hubiera dado por buena.

Esa es la diferencia entre documentación y memoria. La documentación espera a que alguien note que está mal. Una afirmación sabe cuándo está mal y programa su propia reparación. La documentación no solo describe el código: se puede refutar contrastándola con él.

De dónde viene la idea

OpenWiki no surgió de la nada. En abril de 2026, Andrej Karpathy, miembro fundador de OpenAI, publicó un breve gist que describía una «LLM Wiki» de tres capas: fuentes en bruto inmutables, una wiki en markdown que un LLM mantiene a partir de ellas y un esquema que describe cómo se organiza la wiki. El argumento iba contra la retrieval-augmented generation, la práctica habitual de buscar en documentos en el momento de la pregunta. Si compilas el conocimiento una vez en páginas duraderas, decía, se acumula. Si recuperas fragmentos cada vez, se evapora.

En pocos días el gist superó las 5.000 estrellas, y LangChain lo cita como influencia directa. Visto así, OpenWiki es ese boceto convertido en producto, con Grounded Claims encima. La salida se escribe en el Open Knowledge Format de Google, versión 0.2 (la especificación OKF está en el repositorio knowledge-catalog de Google), pensado para que cualquier agente pueda consumir conocimiento empaquetado. Las wikis en markdown como memoria de agentes se están convirtiendo sin hacer ruido en un patrón común, y OpenWiki es su forma más completa hasta ahora: 15.000 estrellas en GitHub en dos meses, con nuevas versiones cada pocos días. Su propio repositorio está documentado por él mismo.

La prueba: todo open source

Siguiendo la documentación oficial, un modelo alojado de OpenAI o Anthropic puede generar una wiki en unos tres minutos por unos diez céntimos, según cuenta la comunidad. La prueba más dura es si todo puede funcionar en un stack abierto con un modelo local, manteniendo todo el código en la máquina.

La configuración

Cuatro piezas gratuitas y abiertas:

• OpenWiki v0.4.0, instalado globalmente con npm install.
• Ollama para servir modelos en local. No hay un proveedor de Ollama integrado, pero OpenWiki puede usar cualquier endpoint compatible con OpenAI, y Ollama expone uno.
• Dos modelos de pesos abiertos: primero gpt-oss:20b de OpenAI (una descarga de 13 GB) y después qwen3.5 4B de Alibaba (3,4 GB).
• Hardware: un portátil con 24 GB de memoria unificada, de gama media y muy lejos de una estación de trabajo.

El objetivo fue un prototipo personal llamado Hangar, un servidor de orquestación de agentes con interfaz web. Tiene 58 archivos TypeScript repartidos entre un servidor, un cliente web y ejemplos. Código real de tamaño modesto, sin nada exótico.

La configuración del proveedor son unas pocas líneas en ~/.openwiki/.env:

OPENWIKI_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_API_KEY=ollama
OPENAI_COMPATIBLE_BASE_URL=http://localhost:11434/v1
OPENWIKI_MODEL_ID=gpt-oss:20b
OPENWIKI_TELEMETRY_DISABLED=1

Un archivo .openwikiignore en la raíz del repositorio excluyó node_modules, la salida de compilación, los lockfiles y las imágenes. Funciona como un límite estricto de lo que se lee, y con un modelo local eso importa el doble, porque todo lo que lee el agente tiene que caber por una ventana más pequeña.

Después se ejecutó openwiki code --init --print, y falló. Cuatro veces, de cuatro maneras distintas. Cada fallo escondía una lección que el texto del error nunca explicó, porque ese texto apenas cambió de una vez a otra.

Fallo 1: una ventana que nadie mencionó

A los dos minutos, la primera ejecución terminó con una sola línea:

Repository planning worker exited without submit_plan.

Sin traza, sin motivo. La causa estaba muy lejos de OpenWiki. Ollama arranca cada modelo con una ventana de contexto de 4.096 tokens, que es la memoria de trabajo que el modelo puede ver de una vez. El prompt de escaneo del repositorio es muchas veces mayor. Ollama no lanza un error cuando se desborda. Recorta el principio sin decir nada, así que el modelo nunca leyó la parte que explicaba que existía una herramienta submit_plan. ollama ps lo confirmó al mostrar el modelo con CONTEXT 4096.

Arreglarlo requiere una sola variable de entorno al arrancar Ollama. Quien repita este experimento en casa necesita esa línea más que ninguna otra:

OLLAMA_CONTEXT_LENGTH=32768 ollama serve

Fallo 2: el mismo mensaje, otra causa

Con la ventana ampliada, el planificador volvió a morir, con la misma línea tras los mismos dos minutos. Aquí es donde depurar stacks de IA locales se vuelve realmente difícil: un único texto de error, varias causas de fondo y ninguna telemetría para distinguirlas.

El siguiente paso fue probar la capa de debajo. Una petición montada a mano contra el endpoint de Ollama, con un esquema de herramienta submit_plan, mostraría si el modelo era capaz siquiera de hacer una llamada estructurada a una herramienta:

curl http://localhost:11434/v1/chat/completions \
  -d '{"model":"gpt-oss:20b", "tools":[…submit_plan schema…], …}'

Devolvió una llamada a herramienta perfectamente formada, y con ambos modelos. Por separado, la fontanería funcionaba, así que el fallo estaba en el transporte entre OpenWiki y Ollama. OpenWiki envía por defecto peticiones sin streaming, y este pipeline necesitaba streaming. Una línea más en el archivo .env:

OPENWIKI_OPENAI_COMPATIBLE_STREAMING=true

En la siguiente ejecución, el planificador pasó.

Fallo 3: un modelo potente que nunca entregó

Aquí se puso interesante. Con la planificación funcionando, el modelo de 20B empezó el trabajo de verdad. Las llamadas pasaron de segundos a más de un minuto, y a los ocho minutos apareció en disco una página de wiki auténtica: una descripción precisa del bus de eventos de Hangar. Las rutas de archivo eran correctas, el comportamiento estaba bien descrito (primero persistir, luego distribuir) y había una tabla de referencia de campos en condiciones. No era relleno. El modelo había entendido el código.

Y aun así la ejecución murió:

/openwiki/architecture/event_bus.md worker exited without submit_page.

El modelo había terminado la parte difícil, la redacción, y luego se saltó la llamada formal a la herramienta que entrega la página. El pipeline descartó una página que ya estaba en disco. El problema no era la capacidad. Era rematar la tarea al final de un contexto largo.

Fallo 4: el modelo pequeño también tropezó

Después le tocó a qwen3.5 4B, un modelo con una de las plantillas de llamada a herramientas mejor probadas en Ollama, ahora con una ventana de 65.536 tokens. Llegó más lejos y completó la página del bus de eventos junto con su archivo de afirmaciones, lo que significaba que todo el pipeline había funcionado de principio a fin por primera vez. Luego, a los 51 minutos y en mitad de la segunda página, murió con el ya conocido mensaje sobre submit_page.

La causa ya era evidente. Un worker de página acumula contexto mientras trabaja: el borrador, las pruebas que ha leído y el historial de llamadas a herramientas. En algún momento la instrucción final se cae de una ventana que recorta en silencio. Qué modelo se usara daba igual. Lo decisivo era qué hace la capa de serving cuando se queda sin memoria, y la respuesta es nada, sin avisar.

El rescate: un bucle Ralph

La solución resultó ser una tontería. La versión 0.4.0 guarda el progreso en un archivo de ejecución duradero, openwiki/.run.json, de modo que una generación interrumpida retoma donde se quedó. Por tanto, una herramienta que se cae cada pocas páginas se arregla ejecutándola una y otra vez hasta que una ejecución termine limpia.

Ese enfoque se llama bucle Ralph, por el adorable y despistado niño de Los Simpson: un while-true deliberadamente tonto que repite la misma instrucción hasta acabar el trabajo. Nadie esperaba que rescatara el producto de otro. Todo el harness son unas pocas líneas de shell:

for i in 1 2 3 4 5 6 7 8; do
  if openwiki code --init --print; then
    echo "COMPLETE after $i iterations"; break
  fi
done

La ventana de Ollama se amplió una vez más, a 98.304 tokens, para tener margen, y luego se lanzó el bucle.

Seis pasadas y algo menos de tres horas después, estaba hecho. La primera pasada guardó cuatro páginas terminadas y la segunda otras cuatro. Las pasadas tres a cinco se atascaron todas en una página difícil y no guardaron nada, que es el punto en que una persona mirando probablemente se rendiría. La sexta pasó, y las quince páginas restantes salieron de un tirón, porque las páginas de índice y de resumen se escriben rápido. El resultado final: una wiki de 23 páginas con 18 afirmaciones fundamentadas, cada hecho atado a pruebas con hash, y código de salida cero.

El modelo no mejoró en nada. Los fallos simplemente dejaron de ser caros, y eso solo funciona porque el checkpoint mantiene a salvo el trabajo terminado. La persistencia con un archivo de guardado supera a la ingeniosidad frágil. En la configuración final, el repositorio, el agente, el servidor de modelos, el modelo, las salidas y el bucle de reintentos están en una sola máquina, y la única línea que cruza la frontera es la que nunca se usa.

Una comparación honesta

Comparemos las dos vías. La de la nube tarda unos tres minutos y cuesta unos diez céntimos sin límite de gasto, no requiere habilidades especiales y envía el código fuera de la máquina. La local tarda unas cuatro horas de principio a fin y no cuesta nada, pero exige diagnosticar cuatro capas de fallos y construir un harness de reintentos, y ni un byte sale del ordenador.

La mayoría de las veces, para la mayoría de la gente, la vía local no compensa. Pagar cuarenta veces el tiempo, más la experiencia para rastrear fallos silenciosos, por ahorrar diez céntimos es un mal trato. Pero cuando el código no puede salir del edificio, es la única opción, y está claro que funciona.

El hallazgo más importante es otro. Cada fallo vino de la configuración y no de la capacidad. Los modelos entendían el código, y el de 20B escribió páginas de arquitectura precisas. Lo que se rompía cada vez era la fontanería: ventanas por defecto que recortan en silencio, transportes que pierden llamadas a herramientas y contexto que se agota sin avisar. «Los modelos locales no son lo bastante buenos» es la lección equivocada. La correcta es que los stacks de serving locales todavía fallan en silencio y nadie lo hace visible. Es un problema de ingeniería y no de escala del modelo, y los problemas de ingeniería se arreglan.

¿Merece la pena probarlo?

Si el código ya pasa por APIs en la nube, adelante, pruébalo ya. La versión rápida cumple, las páginas son buenas y nada más en el mercado tiene algo parecido al mecanismo de afirmaciones. Algunas advertencias sobre las aristas: haz commit antes, porque init borra una wiki existente; vigila los costes con una clave de pago por uso, ya que nada limita el gasto y las cifras reportadas varían mucho; y recuerda que es un proyecto 0.x temprano que cambia rápido.

Para un uso totalmente privado, en el momento de escribir esto funciona con los arreglos de arriba y algo de paciencia. Antes que nada, amplía la ventana de contexto de Ollama.

Y para quien ya guarda conocimiento en markdown, la lección más amplia es que el sector converge desde todas las direcciones en una misma respuesta: archivos de texto plano, mantenidos por agentes y corregidos con pruebas. El producto no es la wiki. Es el bucle de corrección, y OpenWiki es la primera herramienta que entrega uno con comprobantes.