funes: memória persistente para agentes de código que roda local e você é dono

Todo agente de código encontra os projetos como um estranho. A conversa da terça passada some quando a sessão fecha, e o próximo agente, em outra máquina, começa do zero. Essa é a dor que o funes, anunciado pela Hugging Face no blog oficial, tenta resolver: uma camada de memória durável para agentes que roda localmente e transforma as sessões que já existem na sua máquina em algo que o próximo agente consegue consultar.

O artigo, assinado por David Corvoysier, parte de uma premissa que interessa a quem constrói: os traces das sessões (as buscas no codebase, as tentativas, os erros, as mudanças de rumo) já são um registro denso não só do que mudou, mas do porquê. O problema é que esse registro fica preso em logs. Como diz o texto, "você não consegue chegar via grep até 'por que abandonamos o parser de streaming?' ao longo de dez mil turnos". Para virar memória de fato, os traces precisam de indexação, recuperação, ranqueamento e proveniência exata. É esse pipeline que o funes entrega.

O que muda para quem constrói

A proposta central, e o motivo de o editor ter puxado essa pauta, é a posse do dado. O funes não é um serviço de memória que você aluga de volta por uma API. A memória local é um dataset Lance na sua máquina; a memória compartilhada é um dataset do Hugging Face Hub, privado por padrão, que pertence a você. Nas palavras do post: "sua memória não vira uma conta em um serviço de memória separado, e você não a aluga de volta por uma API".

Na prática isso significa que embedding e reranking rodam localmente. O binário padrão não tem dependência de runtime de ML↳Machine learning39 conteúdosClassificador de Sentimentos – Azure MLData · abr 2019Inteligência Artificial e Machine Learning: O que você precisa saberAI · fev 2024Inteligência Artificial: seminário online da USP debate o futuro do aprendizado de máquinaGestão Dev & TI · jun 2021Ver tudo em AI →, e nenhum modelo hospedado processa suas sessões para indexar. Quem faz o raciocínio continua sendo o seu agente de código. Para o dev brasileiro, isso tem dois efeitos concretos: contexto sensível (credenciais, lógica proprietária) não precisa sair da máquina para ser indexado, e o custo recorrente de um serviço externo some.

Como funciona por baixo

A instalação é um binário único:

curl -fsSL https://huggingface.co/buckets/huggingface/funes/resolve/install.sh | sh

Depois, adiciona-se a um agente:

funes add claude # ou: codex, pi, hermes

Esse único comando constrói o primeiro índice, dá ao agente as ferramentas recall e get, e instala a automação que indexa cada turno concluído. A indexação é incremental: novas execuções adicionam turnos novos em vez de reprocessar todo o histórico, e o conteúdo mais antigo é preenchido em passos limitados.

O pipeline é determinístico e único para todos os agentes suportados. Ele faz o parsing de cada trace no mesmo formato de turno-e-bloco, chunka, gera embeddings com um modelo local fixado (pinned) e grava no dataset Lance local. Uma consulta combina busca vetorial com BM25, funde os dois rankings, reranqueia os candidatos com um cross-encoder, reponera por recência e anexa os chunks vizinhos.

Desse desenho saem três propriedades que valem destacar:

Um detalhe importante para segurança: o recall retorna o texto original, não um resumo, e mostra exatamente de onde veio (agente, timestamp, sessão e turno). Cada resultado inclui um comando get que abre o turno completo com o contexto ao redor.

Quando a memória viaja

Para fazer a memória seguir o trabalho entre máquinas ou entre pessoas, basta vincular um dataset ao adicionar o agente:

funes add codex acme/funes-memory

O vínculo publica a memória atual naquele dataset e a mantém atualizada, indexando cada turno localmente e publicando nas fronteiras de sessão. Rodar o mesmo comando em outra máquina traz a memória junto. Quando um agente lê uma memória remota, o funes faz cache dos arquivos localmente, então consultas quentes voltam à velocidade local.

Aqui entra um cuidado que o dev precisa avaliar: publicar sessões no Hub significa expor o raciocínio bruto. O funes redige credenciais durante a indexação e, antes de qualquer coisa subir, escaneia cada chunk de novo retendo o que ainda parecer segredo. O escopo do scanner (o que ele cobre e o que não cobre) está documentado no SECURITY.md. Vale ler antes de tornar uma memória pública, porque "parece segredo" é uma heurística, não uma garantia.

O caso de uso que costuma passar batido: custo de sessão longa

Uma investigação longa incha a sessão até que carregar o contexto de cada turno custe mais do que fazer o trabalho. As saídas usuais são deixar o agente compactar e seguir, ou escrever um handoff e recomeçar do zero. O funes propõe uma terceira: recuperar sob demanda.

A Hugging Face mediu as três no handoff-vs-recall benchmark, com duas tarefas cuja resposta não pode ser reconstruída sem o conhecimento prévio da sessão. Os números reportados:

• Compaction foi a única cujo resultado se dividiu: chegou à resposta em uma tarefa e não chegou na outra, porque o resumo achatou os achados que importavam.
• Recall foi a mais barata das três nas duas tarefas: 8x mais barata que um handoff escrito em uma, e 4x na outra.

A vantagem estrutural do recall é que ele devolve as passagens em si, então um achado não precisa sobreviver à sumarização para continuar disponível. Vale a ressalva: esses números vêm do benchmark da própria Hugging Face, com apenas duas tarefas. É evidência a favor, não prova definitiva, e o comportamento em codebases grandes e ruidosos ainda é uma pergunta aberta.

Onde não vale a pena

O funes não é bala de prata. Se o trabalho acontece só em uma máquina e sessões curtas, o ganho sobre a compaction padrão do próprio agente é marginal. Publicar memória para um time ou projeto open source↳Open source71 conteúdosComo o Open Source Está Liberando o Poder da Automação para TodosDev (Back & Front) · out 2025Código aberto: programadores criam software da NASA sem saberDev (Back & Front) · abr 2021N8N: O que é a ferramenta open source que está revolucionando a automação em TI?Dev (Back & Front) · dez 2025Ver tudo em Dev (Back & Front) → é onde a coisa brilha ("um CLAUDE.md pesquisável que guarda o histórico de por que o projeto é como é", diz o post), mas isso exige governança de segurança séria sobre o que sobe ao Hub. E há a dependência de qualidade dos embeddings locais: um retrieval miss não é disfarçado, o agente diz que as passagens não sustentam a resposta, o que é honesto, mas ainda deixa você sem a informação.

"Pensar é esquecer diferenças, generalizar, abstrair."

Jorge Luis Borges, Funes, o Memorioso

O funes é open source e se apoia em peças abertas: modelos de embedding bons o suficiente para rodar local, os datasets append-only do Lance com escrita incremental barata, e o cache e content-dedup do Hub. O trabalho, como admite o próprio anúncio, foi encaixar essas peças em algo que um agente consiga de fato usar. Para quem constrói com agentes no Brasil, é a primeira proposta séria de memória persistente que não pede para você entregar suas sessões a um terceiro.

Fonte: Hugging Face Blog