FAVA Trails: memoria compartida nativa de Git para agentes de IA (MCP)

Para quién es

FAVA Trails (Federated Agents Versioned Audit Trail) es un sistema de memoria nativo de Git expuesto a los agentes de IA mediante MCP: las ideas, decisiones y observaciones que producen los agentes se escriben como archivos Markdown con frontmatter YAML en un repositorio Git de datos que controlas tú, y no en una caja negra alojada en servidores ajenos. Separa los «borradores» de las «observaciones visibles para todos los agentes» en dos niveles, con una puerta de promoción en medio; los agentes normalmente solo ven las herramientas de memoria y no tocan comandos de control de versiones — el motor se ocupa del versionado dentro del repositorio y todo el historial queda consultable en los commits.

• Encaja bien: equipos o personas que quieren que varios agentes compartan y acumulen memoria de trabajo — por ejemplo guardar las conclusiones de una investigación técnica o el contexto de decisiones entre sesiones como observaciones reutilizables; usuarios que quieren una memoria versionada, rastreable y consultable directamente como archivos; quienes ya gestionan activos con Git y no les importa mantener un repositorio de datos adicional.
• Requisitos previos: que pip pueda instalar en tu equipo; indicar en la configuración la ruta del repositorio de datos FAVA_TRAILS_DATA_REPO; para promover un borrador a observación visible para todos los agentes hay que configurar una clave API de OpenRouter.
• Sopesar: si no quieres mantener un repositorio de datos ni solicitar una clave de OpenRouter, piénsalo bien — la ruta central de memoria compartida entre agentes depende de ambas cosas a la vez.
• Desconocido: la evidencia no indica qué clientes MCP concretos se admiten, qué requisitos de sistema operativo y versión de Python hay, ni si el motor de almacenamiento Jujutsu (JJ) requiere instalación aparte.

Primera prueba en 3 minutos

Solo hay una ruta principal recomendada: instalar el motor desde PyPI y registrarlo en la configuración de servidores del cliente MCP. Dos condiciones previas: decidir primero la ubicación del repositorio de datos, porque FAVA_TRAILS_DATA_REPO en la configuración apunta a él; y para llegar al paso de promoción hace falta una clave API de OpenRouter.

Primer paso, instalar este servidor MCP sin estado con licencia Apache-2.0:

pip install fava-trails

Segundo paso, añadir el fragmento de registro oficial a la configuración del cliente y sustituir la ruta del repositorio por tu ubicación real:

"fava-trails": {
  "command": "fava-trails-server",
  "env": {
    "FAVA_TRAILS_DATA_REPO": "/path/to/fava-trails-data",
    "OPENROUTER_API_KEY": "sk-or-v1-..."
  }
}

Tercer paso, hacer que el agente llame una vez a la escritura de menor alcance: guardar una observación como borrador con save_thought.

save_thought(trail_name="myorg/eng/my-project", content="My finding about X", source_type="observation")

Señal de éxito: el borrador aparece en el directorio drafts/ del repositorio de datos. Ten clara la naturaleza de la operación: este paso es una escritura local, el archivo cae en tu propio repositorio, no es una consulta de solo lectura; no existe documentación oficial para borrar o deshacer un borrador, así que en la primera prueba escribe contenido inofensivo. En el lado del motor, Jujutsu (JJ) actúa como motor de almacenamiento junto a Git en modo colocate; el repositorio sigue siendo un repositorio Git estándar y en este paso no necesitas tocar ningún comando de control de versiones. Fíjate también en el alcance de la clave API de OpenRouter: ya aparece en esta plantilla oficial de configuración, y la tabla oficial añade que es obligatoria para propose_truth, al alimentar las revisiones LLM del Trust Gate vía OpenRouter; una primera prueba puede quedarse en el paso del borrador, sin necesidad de promover de paso.

Casos de uso

Caso uno: conservar la conclusión de una investigación como memoria de proyecto. Escenario: un agente acaba de terminar una investigación y la conclusión merece reutilizarse en sesiones posteriores. Cómo hacerlo: llamar a save_thought con trail_name, content y source_type; la llamada de ejemplo oficial de arriba sirve tal cual. Resultado esperado: se genera un archivo de borrador en drafts/, el contenido queda solo en tu repositorio, los demás agentes todavía no lo ven y no afecta a nadie; el borrador es un archivo normal que puedes abrir directamente en el repositorio.

Caso dos: promover un borrador verificado a observación compartida y comprobarlo con una búsqueda. Escenario: una observación ya está verificada y quieres que todos los agentes posteriores puedan encontrarla. Cómo hacerlo: confirmar primero que la clave API de OpenRouter es válida, llamar a propose_truth(trail_name="myorg/eng/my-project", thought_id=thought_id) para promover el borrador a observations/ y luego recuperar con recall(trail_name="myorg/eng/my-project", query="X"). Resultado esperado: recall encuentra la idea promovida, y los demás agentes conectados al mismo repositorio de datos también la encuentran con la misma consulta. Punto de control: el resultado de la promoción es visible para todos los agentes y no hay documentación oficial de deshacer, así que confirma que el contenido es apto para compartir antes de ejecutar; empujar el cambio a un remoto es otra acción independiente que requiere llamar aparte a la herramienta sync o a jj git push.

Límites de uso

• Naturaleza de lectura/escritura: save_thought crea un borrador en el repositorio de datos y propose_truth promueve el borrador a observations/ visible para todos los agentes — ambas son escrituras; recall busca las ideas promovidas. Las escrituras ocurren dentro de tu propio repositorio y la promoción primero queda en local; empujar a un remoto debe hacerse aparte mediante la herramienta MCP sync o jj git push, y sincronizar o no es decisión tuya. No hay ruta oficial de deshacer ni borrar — no trates una escritura como una operación siempre reversible.
• Credenciales y configuración: FAVA_TRAILS_DATA_REPO indica la ubicación del repositorio de datos y OPENROUTER_API_KEY sirve para la revisión LLM en la promoción; ambas van en la sección env de la plantilla oficial de configuración, y la documentación oficial afirma expresamente que la segunda es obligatoria para propose_truth. Si esas dos herramientas funcionan sin la clave, la evidencia no lo dice.
• Entorno de ejecución y datos: el motor de almacenamiento es Jujutsu (JJ), junto a Git en modo colocate; el repositorio sigue siendo un repositorio Git estándar y GitHub y el CI/CD ven commits normales. Todo el contenido se guarda como archivos Markdown con frontmatter YAML en el repositorio que controlas.
• Puntos sin confirmar: cuotas de capacidad, límites de escala multi-repositorio y detalles de privacidad y residencia de datos no aparecen en la evidencia; los criterios de evaluación del Trust Gate y el tratamiento de fallos tampoco se documentan, y no se indica si hay que instalar jj aparte ni qué clientes y versiones de Python se admiten. No interpretes «no vi documentación» como «no hay riesgo»: evalúa lo que escribas asumiendo que se quedará a largo plazo en tu repositorio.