Flaiwheel

Capa de memoria y gobernanza autohospedada para agentes de codificación de IA. Convierte cada corrección de errores en conocimiento permanente. Cero nube. Cero dependencia de proveedores (lock-in).

🚀 Por qué existe Flaiwheel

Los agentes de codificación de IA olvidan todo entre sesiones. Eso conduce a errores repetidos, decisiones arquitectónicas perdidas y degradación del conocimiento.

Flaiwheel asegura que:

• Los agentes busquen antes de programar

• Los agentes documenten después de corregir

• Los commits capturen conocimiento automáticamente

• La memoria se componga con el tiempo

Cada error corregido hace que el siguiente error sea más barato.

Related MCP server: MCP VectorStore Server

🧠 En qué se diferencia Flaiwheel

• Memoria de IA persistente que se compone — el conocimiento no se restablece entre sesiones.

• Automatización nativa de Git — los commits se convierten automáticamente en conocimiento estructurado.

• Gobernanza, no solo almacenamiento — puertas de calidad + documentación forzada.

• Búsqueda híbrida + Reclasificación (Reranking) — contexto de alta precisión para bases de código reales.

• Totalmente autohospedado — contenedor Docker único, sin infraestructura externa.

• Cero dependencia de proveedores — todo el conocimiento se almacena como archivos planos estructurados en Git.

✅ Para quién es Flaiwheel

• Equipos de ingeniería que utilizan asistentes de codificación de IA en proyectos reales

• Bases de código donde los errores repetidos son costosos

• Equipos que requieren control total de datos

• Entornos de desarrollo nativos de IA

❌ No es para

• Pequeños proyectos de hobby de menos de unos pocos miles de líneas

• Desarrolladores que solo quieren un mejor autocompletado

• Flujos de trabajo SaaS puros sin interés en el autohospedaje

🆚 Dónde encaja Flaiwheel

• Las herramientas de codificación de IA generan código.

• Las herramientas RAG recuperan documentos.

• Flaiwheel gobierna y compone conocimiento de ingeniería estructurado dentro de tu propia infraestructura.

No reemplaza a tu asistente de IA. Lo hace confiable a escala.

📄 Libro blanco (PDF) — Visión, arquitectura y diseño en profundidad.

⚙️ Características técnicas clave

Flaiwheel es un servicio Docker autónomo que opera en tres niveles: Pull — los agentes buscan antes de programar (search_docs, get_file_context) Push — los agentes documentan mientras trabajan (write_bugfix_summary, write_architecture_doc, …) Capture — los commits de git capturan automáticamente el conocimiento mediante un hook post-commit, incluso sin un agente de IA

• Indexa la documentación de tu proyecto (.md, .pdf, .html, .docx, .rst, .txt, .json, .yaml, .csv) en una base de datos vectorial

• Proporciona un servidor MCP al que se conectan los agentes de IA (Cursor, Claude Code, VS Code Copilot)

• Búsqueda híbrida — combina búsqueda vectorial semántica con búsqueda por palabras clave BM25 mediante Reciprocal Rank Fusion (RRF) para obtener lo mejor de ambos mundos en la recuperación

• Reclasificador cross-encoder — paso de reclasificación opcional que vuelve a puntuar a los candidatos con un modelo cross-encoder para una precisión significativamente mayor en consultas con desajuste de vocabulario

• Directivas conductuales — los agentes de IA buscan silenciosamente en Flaiwheel antes de cada respuesta, se autodocumentan después de cada tarea y reutilizan antes de recrear, todo sin que se les pida

• get_file_context(filename) — precarga conocimiento espacial para cualquier archivo que el agente esté a punto de editar (complementa get_recent_sessions para un contexto temporal + espacial completo)

• Hook de git post-commit — captura cada commit fix:, feat:, refactor:, perf:, docs: como un documento de conocimiento estructurado automáticamente

• Arquitectura viva — se instruye a los agentes de IA para que mantengan diagramas de Mermaid.js autoactualizables para los componentes y flujos del sistema

• Flujos de prueba ejecutables — los escenarios de prueba se documentan en formato BDD/Gherkin legible por máquina (Given, When, Then) para la automatización de QA

• Aprende de las correcciones de errores — los agentes escriben resúmenes de corrección de errores que se indexan instantáneamente

• Herramientas de escritura estructurada — 7 herramientas específicas por categoría (corrección de errores, arquitectura, API, mejores prácticas, configuración, registro de cambios, caso de prueba) que garantizan la calidad en la fuente

• Validación pre-commit — validate_doc() verifica el markdown de forma libre antes de que entre en la base de conocimiento

• Puerta de calidad de ingesta — los archivos con problemas críticos se omiten automáticamente durante la indexación (nunca se eliminan; tú eres dueño de tus archivos)

• Sincronización automática vía Git — extrae (pull) Y envía (push) a un repositorio de conocimiento dedicado

• Telemetría de herramientas (persistente) — rastrea cada llamada MCP por proyecto (búsquedas, escrituras, fallos, patrones), detecta brechas de conocimiento y empuja a los agentes a documentar; persiste tras reinicios y es visible en la interfaz web

• API de métricas de impacto — /api/impact-metrics calcula el tiempo estimado ahorrado + regresiones evitadas; las tuberías de CI pueden publicar resultados de barandillas en /api/telemetry/ci-guardrail-report

• Verificaciones de calidad proactivas — valida automáticamente la base de conocimiento después de cada reindexación

• Bootstrap de conocimiento — "This is the Way": analiza repositorios desordenados, clasifica archivos, detecta duplicados, propone un plan de limpieza, ejecuta con la aprobación del usuario (nunca elimina archivos)

• Analizador de base de código de arranque en frío — analyze_codebase(path) escanea un directorio de código fuente completamente en el lado del servidor (cero tokens, cero nube). Utiliza el módulo ast integrado de Python para Python, regex para TypeScript/JavaScript, el modelo de incrustación MiniLM existente para clasificación y detección de duplicados. Devuelve un único bootstrap_report.md con distribución de lenguaje, mapa de categorías, los 20 archivos principales para documentar primero clasificados por puntuación de documentabilidad, pares duplicados y brechas de cobertura. Reduce el costo de tokens de arranque en frío en un ~90% en bases de código heredadas.

• Soporte para múltiples proyectos — un contenedor gestiona múltiples repositorios de conocimiento con aislamiento por proyecto

• Incluye una interfaz web para configuración, monitoreo y pruebas

Qué hay de nuevo en v3.9.29

• Corrección de detección de herramientas Glama — AuthManager fallaba en /data de solo lectura antes de que el servidor MCP pudiera iniciarse (la razón real por la que Glama veía 0 herramientas). Omitido en modo de arranque en frío stdio.

• Cero print() en stdout — 36 print() restantes en watcher, indexer, readers, bootstrap reemplazados por diag() (stderr). Verificado: el handshake completo de MCP devuelve las 28 herramientas sobre stdio.

• config.save() resistente — el sistema de archivos de solo lectura registra una advertencia en lugar de fallar.

Anterior: v3.9.28

• Corrección de Glama / MCP stdio — toda la salida de diagnóstico se movió a stderr; stdout ahora es solo JSON-RPC. Glama Inspector ahora detecta las 28 herramientas correctamente.

• Detección de arranque en frío mejorada — la lógica de arranque en frío stdio maneja los volúmenes de Docker vacíos correctamente (sin bootstrap / descarga de modelo durante la inspección de Glama).

Anterior: v3.9.27

• Limpieza de licencia — un archivo LICENSE (BSL 1.1) para la detección correcta de GitHub/Glama; todos los documentos y encabezados apuntan a LICENSE (no LICENSE.md).

• Inspección Glama / stdio — dependencias opcionales [inspect] y ruta stdio de arranque en frío para compilaciones de directorio MCP ligeras.

Anterior: v3.9.26

• Habilidad Claude Cowork — el flujo de trabajo de Flaiwheel ahora se distribuye como una habilidad nativa de Claude. El instalador escribe .skills/skills/flaiwheel/SKILL.md en tu proyecto. Cuando abres el proyecto en Claude (Cowork), la habilidad está disponible automáticamente; no se necesita configuración adicional. La habilidad impulsa la restauración del contexto de inicio de sesión, la búsqueda de conocimiento previa a la codificación, la documentación obligatoria posterior a la corrección de errores y el resumen de fin de sesión.

• La fuente de la habilidad también se confirma en skills/flaiwheel/SKILL.md en este repositorio para referencia e instalación manual.

Anterior: v3.9.25

• Configuración automática previa al vuelo de WSL2 — WSL2 ahora se detecta automáticamente y se ejecuta un bloque de pre-vuelo dedicado antes del flujo principal del instalador. No se requieren pasos manuales:

  1. Cambia iptables al backend heredado (corrige errores de red de Docker / DNAT)

  2. Agrega el usuario actual al grupo docker (no más permission denied)

  3. Inicia el demonio de Docker mediante service (sin systemd en WSL2)

  4. Agrega un fragmento de inicio automático de Docker a ~/.bashrc (idempotente, se ejecuta en cada inicio de sesión de WSL2)

• Las comprobaciones de WSL2 dispersas a lo largo del script se consolidaron en el único bloque de pre-vuelo.

Anterior: v3.9.24

• Corrección: instalar automáticamente python3 si falta — el instalador utiliza python3 extensivamente para la manipulación de JSON. En sistemas Linux/WSL2 mínimos sin python3, las escrituras de archivos de configuración fallaban silenciosamente (/dev/fd/63: line N: python3: command not found). python3 ahora se verifica como requisito previo #0 y se instala automáticamente mediante apt/dnf/yum/pacman/brew si falta.

Anterior: v3.9.23

• Corrección: inicio del demonio de Docker en WSL2 con iptables-legacy — Docker en WSL2 a menudo no se inicia silenciosamente porque el backend predeterminado iptables-nft no es compatible. El instalador ahora cambia a iptables-legacy mediante update-alternatives antes de iniciar Docker. También agrega automáticamente el usuario actual al grupo docker.

• Todos los comandos de instalación actualizados a bash <(curl ...) — cada comando de instalación/re-ejecución mostrado a lo largo del script (mensajes de error, AGENTS.md, reglas de Cursor, etc.) ahora utiliza sustitución de procesos para evitar problemas de tubería de WSL2.

Anterior: v3.9.22

• Corrección: fallos de escritura de tubería curl | bash en WSL2 — curl | bash puede fallar con curl: (23) Failure writing output en WSL2 debido a problemas de permisos de tubería/tmp. El comando de instalación principal en README ahora es bash <(curl ...) (sustitución de procesos), lo que evita la tubería por completo. El bloque de re-ejecución también intenta $HOME como directorio temporal de respaldo cuando fallan las escrituras en /tmp. El mensaje de error recomienda explícitamente la forma bash <(curl ...).

Anterior: v3.9.21

• Corrección: guardia sudo movida antes del bloque de re-ejecución — cuando se usaba sudo curl | bash, el error de tubería curl: (23) truncaba el script antes de que se alcanzara la guardia sudo anterior (que estaba después de colores/funciones). La guardia ahora es la primera línea ejecutable (aparte de set -euo pipefail), por lo que se dispara incluso en una descarga truncada. Se eliminó la guardia duplicada después de los colores.

Anterior: v3.9.20

• Corrección: sondeo de inicio del demonio de Docker en WSL2 — en lugar de una pausa fija de 5 segundos, el instalador ahora sondea docker info cada 2 segundos hasta por 30 segundos después de service docker start. También muestra la salida real de service docker start para que los errores de inicio sean visibles en lugar de ser tragados silenciosamente.

Anterior: v3.9.19

• Corrección: inicio del demonio de Docker en WSL2 — WSL2 normalmente no tiene systemd, por lo que systemctl start docker fallaba silenciosamente. El instalador ahora detecta WSL2 mediante /proc/version y usa sudo service docker start en su lugar. Si Docker aún no se está ejecutando después de la instalación, se muestra un error claro específico de WSL2 con el comando de corrección exacto y un consejo para agregarlo a ~/.bashrc para el inicio automático al iniciar sesión.

Anterior: v3.9.18

• Corrección: bloquear sudo curl | bash y sudo bash install.sh — ejecutar el instalador como root mediante sudo rompe la autenticación de la CLI de GitHub: gh auth almacena las credenciales en /root/.config/gh/ en lugar del directorio personal del usuario real, haciendo que cada llamada posterior a gh falle. También causaba errores de tubería curl: (23) Failure writing output en WSL. El instalador ahora detecta SUDO_USER al inicio y sale inmediatamente con un mensaje claro indicando al usuario que vuelva a ejecutar sin sudo. La escalada de privilegios para instalaciones de paquetes se maneja internamente.

Anterior: v3.9.17

• Corrección: gh auth login no debe ejecutarse con sudo — después de instalar automáticamente gh en Linux/WSL, el instalador ahora le dice explícitamente al usuario que ejecute gh auth login sin sudo. Si la autenticación se realizó previamente con sudo, las credenciales terminaban en /root/.config/gh/ y eran invisibles para el usuario actual, lo que provocaba que la verificación de autenticación fallara. Los mensajes de error tanto en la etapa posterior a la instalación como en la etapa de verificación de autenticación ahora advierten claramente: no use sudo para gh auth.

Anterior: v3.9.16

• Corrección: el instalador funciona en WSL y Linux no root — todos los comandos del gestor de paquetes de Linux (apt-get, dnf, yum, zypper, pacman), el script de conveniencia de Docker y las llamadas a systemctl ahora usan automáticamente sudo cuando el instalador no se ejecuta como root. Las instalaciones root no se ven afectadas. Corrige errores de Permission denied / archivo de bloqueo en WSL y usuarios de escritorio Linux estándar.

Anterior: v3.9.15

• Informe de arranque en frío almacenado en caché en /data/ — analyze_codebase() guarda el informe en /data/coldstart-<project>.md después de la primera ejecución. Las llamadas posteriores devuelven el informe almacenado en caché instantáneamente (<1s). El instalador también escribe la caché durante la instalación para que la primera llamada MCP de cualquier agente sea instantánea. Llame con force=True para regenerar después de cambios importantes en la base de código.

• **`analyze_code