FAVA Trails: memória compartilhada nativa do Git para agentes de IA (MCP)

Para quem é

FAVA Trails (Federated Agents Versioned Audit Trail) é um sistema de memória nativo do Git exposto a agentes de IA via MCP: as ideias, decisões e observações produzidas pelos agentes são gravadas como arquivos Markdown com frontmatter YAML em um repositório Git de dados que você controla, e não em uma caixa-preta hospedada nos servidores de terceiros. Ele separa "rascunhos" e "observações visíveis para todos os agentes" em dois níveis, com um portão de promoção entre eles; os agentes normalmente veem apenas as ferramentas de memória e não tocam em comandos de controle de versão — o versionamento é tratado pelo motor dentro do repositório, e todo o histórico fica consultável nos commits.

• Serve bem: equipes ou pessoas que querem que vários agentes compartilhem e acumulem memória de trabalho — por exemplo, guardar conclusões de uma investigação técnica ou o contexto de decisões entre sessões como observações reutilizáveis; usuários que querem uma memória versionada, rastreável e abrível diretamente como arquivos; quem já gerencia ativos com Git e não se importa de manter mais um repositório de dados.
• Pré-requisitos: pip precisa funcionar na sua máquina; a configuração exige o caminho do repositório de dados FAVA_TRAILS_DATA_REPO; para promover um rascunho a observação visível para todos os agentes, é obrigatório configurar uma chave de API da OpenRouter.
• A ponderar: quem não quer manter um repositório de dados nem pedir uma chave da OpenRouter deve pensar duas vezes — o caminho central da memória compartilhada entre agentes depende dos dois ao mesmo tempo.
• Desconhecido: as evidências não dizem quais clientes MCP específicos são suportados, quais exigências de sistema operacional e versão do Python existem, nem se o motor de armazenamento Jujutsu (JJ) precisa ser instalado à parte.

Primeira tentativa em 3 minutos

Só há um caminho principal recomendado: instalar o motor do PyPI e registrá-lo na configuração de servidores do cliente MCP. Duas condições: defina antes onde ficará o repositório de dados, pois o FAVA_TRAILS_DATA_REPO da configuração aponta para lá; e para chegar à etapa de promoção é preciso uma chave de API da OpenRouter.

Primeiro passo, instalar este servidor MCP sem estado licenciado sob Apache-2.0:

pip install fava-trails

Segundo passo, adicionar o trecho de registro oficial à configuração do cliente e trocar o caminho do repositório pelo seu local real:

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

Terceiro passo, deixar o agente chamar uma vez a escrita de menor escopo: gravar uma observação como rascunho com save_thought.

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

Sinal de sucesso: o rascunho aparece no diretório drafts/ do repositório de dados. Entenda a natureza da operação: esta etapa é uma escrita local, o arquivo cai no seu próprio repositório, não é uma consulta somente leitura; não há documentação oficial para excluir ou desfazer um rascunho, então escreva algo inofensivo na primeira tentativa. No lado do motor, o Jujutsu (JJ) funciona como motor de armazenamento junto ao Git em modo colocate; o repositório continua sendo um repositório Git padrão, e nesta etapa você não precisa tocar em nenhum comando de controle de versão. Note também a fronteira da chave de API da OpenRouter: ela já aparece neste modelo oficial de configuração, e a tabela oficial acrescenta que ela é obrigatória para o propose_truth, alimentando as revisões LLM do Trust Gate via OpenRouter; uma primeira tentativa pode parar na etapa do rascunho, sem necessidade de promover de caminho.

Casos de uso

Caso um: transformar a conclusão de uma investigação em memória de projeto. Cenário: o agente acabou de concluir uma investigação e a conclusão vale para sessões futuras. Como fazer: chamar save_thought com trail_name, content e source_type — a chamada de exemplo oficial acima serve como está. Resultado esperado: um arquivo de rascunho surge em drafts/, o conteúdo fica apenas no seu repositório, os demais agentes ainda não o veem e ninguém é afetado; o rascunho é um arquivo comum, que dá para abrir direto no repositório.

Caso dois: promover um rascunho verificado a observação compartilhada e validar com uma busca. Cenário: uma observação foi verificada e você quer que todos os agentes seguintes a encontrem. Como fazer: confirmar primeiro que a chave de API da OpenRouter é válida, chamar propose_truth(trail_name="myorg/eng/my-project", thought_id=thought_id) para promover o rascunho a observations/ e depois recuperar com recall(trail_name="myorg/eng/my-project", query="X"). Resultado esperado: o recall encontra o pensamento promovido, e os outros agentes ligados ao mesmo repositório de dados também o encontram com a mesma consulta. Ponto de checagem: o resultado da promoção fica visível para todos os agentes e não há documentação oficial de desfazer — confirme que o conteúdo é adequado para compartilhar antes de executar; enviar a alteração para um remoto é outra ação independente, que exige chamar à parte a ferramenta sync ou jj git push.

Limites de uso

• Natureza de leitura/escrita: save_thought cria um rascunho no repositório de dados e propose_truth promove o rascunho a observations/ visível para todos os agentes — as duas são escritas; recall encontra os pensamentos promovidos. As escritas acontecem dentro do seu próprio repositório, e a promoção primeiro fica local; enviar para um remoto deve ser feito à parte pela ferramenta MCP sync ou jj git push, e sincronizar ou não é decisão sua. Não existe caminho oficial de desfazer nem excluir — não trate uma escrita como operação sempre reversível.
• Credenciais e configuração: FAVA_TRAILS_DATA_REPO indica o local do repositório de dados e OPENROUTER_API_KEY serve para a revisão LLM na promoção; as duas entram na seção env do modelo oficial de configuração, e a documentação oficial afirma expressamente que a segunda é obrigatória para o propose_truth. Se essas duas ferramentas funcionam sem a chave, as evidências não dizem.
• Ambiente de execução e dados: o motor de armazenamento é o Jujutsu (JJ), junto ao Git em modo colocate; o repositório continua um repositório Git padrão, e o GitHub e o CI/CD veem commits normais. Todo o conteúdo fica como arquivos Markdown com frontmatter YAML no repositório que você controla.
• Pontos não confirmados: cotas de capacidade, limites de escala entre repositórios e detalhes de privacidade e residência de dados não aparecem nas evidências; os critérios de avaliação do Trust Gate e o tratamento de falhas também não são descritos, e não se diz se o jj precisa ser instalado à parte nem quais clientes e versões do Python são suportados. Não leia "não vi documentação" como "não há risco" — avalie o que escreve assumindo que vai ficar por longo prazo no seu repositório.