Bitácora
El patrón que podrías estar pasando por alto
Cualquiera que haya trabajado con agentes de AI en desarrollo de software lo ha sufrido: los agentes son stateless entre sesiones..En cada sesión hay que poner en contexto, indicar la metodología de trabajo, etc. Es una movida... ¡y es muy fácil que algo se te olvide!
Dada la situación, comencé a usar un fichero maestro para almacenar esa información: la típica del AGENTS.md. Pero esto no era suficiente. Los agentes se vuelven menos efectivos según vas iterando.
Decidí pedirle a un agente que guardara su "configuración" en una carpeta, que el agente llamó "conductor". Más tarde descubriría que mi agente se había basado en una skill de CDD (context driven developemnt).
Esa skill de CDD especificaba el uso de un "conductor" para documentar lo que el agente iba haciendo. Con la iteración y el uso, lo fui perfeccionando. Le di forma hasta crear Bitácora: un sistema de memoria determinista para agentes de desarrollo que vive dentro del repositorio y permite reconstruir el estado del proyecto entre sesiones.
Y funciona sorprendentemente bien.
Obviamente, mi solución no es la única. Existen múltiples soluciones pululando por ahí. Todas estas soluciones intentan resolver el mismo problema: dar memoria a sistemas que no la tienen.
Long Context: Consiste en tener un contexto más grande (1M de tokens en ventana). Esto tiene el problema de que cuanto más tiene que procesar más degrada la calidad del resultado, sobre todo en contextos largos.
RAG: Esto es una búsqueda vectorizada con resultados. Esto es tremendamente costoso y depende de la calidad de embeddings.
Fine-tunning: Reentrenamiento contínuo del modelo. Lento, muy costoso y frágil.
Memory Layers: Persistencia experimental. Se hacen capas de memoria, donde esa memoria se va encapsulando.
En la práctica, trabajar con agentes significa convivir con esto:
- Pierden contexto
- Cambian de modelo
- Cambian de sesión
- Compactan memoria
Bitácora existe para sobrevivir a eso.
Bitácora solventa la problemática... al menos hasta encontrar una solución más sofisticada. Bitácora es una memoria persistente, basada en archivos, legible por agentes y humanos, reconstruible, determinista.
Esto no es memoria del modelo, es memoria del proyecto.
Memoria Estructural
- Index: es el mapa de memoria y el orden de lectura por cada sesión.
- Product: contiene los objetivos del proyecto, el scope, los "non-goals" y las restricciones.
- Tech-stack: runtime/tooling/dependencias y reglas técnicas. Por defecto, aplica TDD a todo.
- Workflow: controla el método de desarrollo, control de calidad y las verificaciones de entrega, entre otros.
- UX & styles: visual tokens y reglas de interacción de la UX.
Memoria Operativa
- Track: incluye un fichero canónico de registro de decisiones y logs temporales. Básicamente, es un tracking resumen de las tareas del proyecto.
- Track-XXX: Track-plan independiente para cada tarea. Contiene las decisiones tomadas, logs temporales, lo que aún falta por implementar, etc. Es como un tracking específico por tarea.
Aquí es donde podemos hablar de decisiones persistentes, reasoning trazable y reconstrucción de estado.
Comportamiento del agente
- Skill: es el Skill específico de Bitácora. Instrucciones que los agentes siguen para mantener el sistema de memoria actualizado.
Con su CLI puedes generar una estructura base sobre la que trabajar. El CLI también inyectará una SKILL en tu repo para que tus agentes sepan cómo se usa Bitácora.
El CLI genera una "Bitácora" con lo necesario para que tus agentes funcionen: un índice, documentos sobre producto, workflow, tech stack, ux y guía de estilos. También prepara una plantilla para llevar tracks de las tareas abiertas.
Bitácora no es solo memoria. Es estado reconstruible del proyecto para agentes. Eso es lo realmente interesante.
Actualmente utilizo el sistema en todos mis proyectos nuevos. Aún tengo que ver que tal se integra en proyectos a medias o proyectos legacy. Mientras los agentes sigan siendo stateless, necesitaremos sistemas así.
No me voy sin dejar por aquí los links para que podáis revisar el código e integrarlo si os interesa. Si alguien tiene propuestas para mejorarlo, que me lo haga saber via email.