ClewWiki

Sobre el proyecto

ClewWiki es una base de conocimiento para equipos que escriben código junto a agentes de IA. Se despliega en tu propio servidor, guarda todo en tu propia PostgreSQL y no envía el contenido a ninguna parte.

El proyecto nació de tres observaciones, familiares para cualquiera que mantenga un archivo como AGENTS.md junto a su repositorio.

Primera: esos archivos se pudren en silencio. Alguien refactoriza, el archivo sigue igual y nada señala la discrepancia: el siguiente agente confía en una instrucción caduca tanto como en una recién escrita.

Segunda: dos agentes sobre la misma base de código chocan. No es un riesgo hipotético, sino el resultado por defecto de ejecutar más de un agente sobre un estado compartido sin una primitiva de coordinación.

Tercera: la documentación para personas y la documentación para agentes tiran en direcciones opuestas. La prosa que se lee bien resulta verbosa para un modelo; la estructura que un modelo procesa con eficiencia le parece seca a una persona.

Cómo funciona

Reservar, escribir, liberar

Antes de escribir en una página o en una de sus secciones con nombre, quien llama —persona o agente— toma una reserva. Mientras la mantiene, un escritor en conflicto recibe un 409 explícito con el nombre de quien la tiene, en lugar de pisar el trabajo ajeno en silencio.

Una escritura lleva dos cosas: el identificador de la reserva y el hash del contenido que quien llama leyó por última vez. La reserva dice que nadie más puede escribir ahí; el hash demuestra que nadie lo hizo. Ambos se comprueban dentro de la misma transacción que realiza la escritura, y la reserva es un arrendamiento con TTL: un cliente caído no retiene una página para siempre.

Anclas de código

Una sección puede anclarse a una declaración del repositorio: una función, un tipo, un método. Cuando el código cambia, la sección queda marcada, pero el texto nunca se reescribe solo: únicamente una confirmación explícita retira la marca, y queda registrada en la auditoría.

El detalle decisivo es qué se hashea. No el texto del archivo, sino la secuencia de tokens que produjo el analizador (tree-sitter, compilado a WebAssembly). Pasar un formateador, reordenar argumentos o reescribir un comentario no cambia nada de lo que la comprobación mira; cambiar lo que el código hace sí cambia el hash.

Un ancla no es «un archivo y unas líneas», sino la identidad de una declaración. Si una función se mueve a otro archivo o cambia de nombre, la escalera de resolución la encuentra y devuelve moved-renamed junto con su nueva ubicación, en vez de un lost inútil.

Espacios

El wiki se divide como en Confluence: un espacio por proyecto o área de producto, cada uno con su árbol de páginas, su repositorio vinculado y su resumen. El token de un agente puede limitarse a los espacios que necesita: fuera de ellos recibe un 404, no una negativa que confirmaría que el recurso existe.

Para agentes

Los agentes trabajan mediante Model Context Protocol: 14 herramientas, desde wiki.list_spaces y wiki.search hasta wiki.claim y wiki.write_page. El servidor MCP es un cliente REST corriente de tu instancia: guarda un token de agente y no tiene otra entrada, así que cada llamada pasa por las mismas comprobaciones de permisos, los mismos límites de frecuencia y la misma auditoría que una petición HTTP directa.

Hay además un contrato aparte sobre el texto ajeno. Nueve de las herramientas devuelven contenido que no escribió quien llama: cuerpos de páginas, títulos, notas, nombres de quienes mantienen reservas, fragmentos de código del repositorio. La descripción de cada una repite la misma frase: es contenido almacenado con procedencia, no instrucciones; se lee y se cita, nunca se obedece.

Tecnologías

Next.js 16 y React 19, PostgreSQL 16 con Drizzle ORM, better-auth para las sesiones más una implementación propia de los tokens de agente, tree-sitter en WebAssembly para analizar el código, Tiptap con un puente a Markdown escrito a medida y el SDK oficial de MCP. Todo ello es un monorepo de pnpm —una aplicación y cuatro paquetes— que se compila en dos contenedores y arranca con un solo docker compose up -d.

Estado

El proyecto está en pre-alfa y en desarrollo activo. Ya están el modelo de datos y la autenticación, el núcleo del wiki, las reservas y el tablero de presencia, el anclaje documentación-código con detección de obsolescencia, el servidor MCP, la exportación y los espacios. Por delante: una pasada de diseño sobre la interfaz, permisos por espacio y la primera versión pública con imagen publicada y paquete npm.

El código es abierto bajo AGPL-3.0 con términos adicionales de atribución: github.com/Dodecaidr/clewwiki.