Memória para agentes de código com Funes: configuração do Claude Code + Codex

Um desenvolvedor pode passar uma hora explicando por que um parser foi alterado e perder todo esse raciocínio quando a próxima tarefa começa em outro agente. O Funes indexa as sessões localmente, recupera as evidências originais com proveniência e permite compartilhar uma única memória entre Claude Code, Codex, pi e Hermes. Há uma limitação importante: o Funes recupera o histórico; quem ainda precisa decidir se uma decisão antiga continua válida é o agente.

Este guia mostra uma configuração prática de Claude Code → Codex, memória somente local, sincronização opcional com o Hugging Face, clientes MCP genéricos e as verificações que ajudam a manter o histórico recuperado realmente útil.

Defina o limite da memória antes de instalar

Comece com memória local se você está avaliando o Funes ou trabalhando com repositórios sensíveis. Vincule um dataset do Hugging Face apenas quando precisar acessar o mesmo histórico em outra máquina ou entre várias pessoas.

A política de segurança do Funes informa que análise, divisão em trechos, geração de embeddings e reranking acontecem localmente por padrão. Os dados saem da máquina por meio de funes push ou de uma integração de memória compartilhada que publica os dados no limite de cada sessão. Uma memória apoiada pelo Hub é um repositório de dataset; por isso, confira sua visibilidade antes do primeiro push.

Para um primeiro piloto, use local. É possível alterar o vínculo depois, executando novamente funes add <agent> <memory>.

Instale o Funes e crie o primeiro índice

O repositório oficial do Funes oferece um instalador de shell que detecta a plataforma, baixa um binário versionado, verifica o checksum da versão publicada e coloca o executável no seu PATH — por padrão, em ~/.local/bin:

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

Abra um novo shell se o comando funes não for encontrado imediatamente e verifique a instalação:

funes status

O repositório lista binários versionados para Linux x86_64, Linux aarch64 e macOS com Apple Silicon. Se sua plataforma não estiver na lista, siga as instruções do projeto para compilar a partir do código-fonte, em vez de presumir que o instalador pré-compilado dará conta dela.

O bootstrap de cinco minutos

Execute o comando a seguir no ambiente em que já existem as sessões dos agentes que você quer preservar:

funes add claude

No Claude Code, isso pode criar o primeiro índice, registrar as ferramentas de leitura, instalar a automação de integração e continuar indexando os turnos concluídos. A primeira passagem prioriza texto e raciocínio antes das saídas volumosas de ferramentas e, depois da confirmação, é documentada como levando cerca de um minuto. (Documentação de configuração do Funes)

Em seguida, confira o estado:

funes status

Se precisar criar ou atualizar manualmente o índice das sessões do Claude, use:

funes index --harness claude

Sem um caminho, o comando funes index pode procurar as localizações padrão de sessões do Claude, Codex, pi e Hermes, incluindo ~/.claude/projects e ~/.codex/sessions. Com --harness claude, a varredura fica limitada ao Claude Code. O guia de indexação também documenta um limite de aproximadamente 60 segundos, priorizando texto, para atualizações sem caminho; sessões antigas e resultados grandes de ferramentas podem exigir passagens posteriores.

A indexação do Funes é incremental, então executá-la novamente não gera embeddings outra vez para os trechos que já foram gravados. Caminhos explícitos de transcrições e repositórios de rastros no Hub são indexados integralmente, sem usar o limite da atualização sem caminho. (Detalhes da indexação)

Conecte o Funes ao Claude Code

Para usar uma memória local no Claude Code, execute:

funes add claude local
funes status

Você pode omitir local, pois esse é o padrão. Se houver um token do HF disponível no terminal, o Funes poderá oferecer a configuração de um repositório pertencente ao usuário, <user>/funes-memory; recuse esse prompt em um piloto somente local.

A integração com o Claude usa um plugin baseado apenas em hooks e um registro MCP separado. O Funes não edita o settings.json do Claude Code: sua automação indexa os turnos concluídos, enquanto uma configuração de memória compartilhada adiciona a publicação nos limites das sessões. (Comportamento da automação)

Abra o Claude Code e teste uma decisão histórica conhecida, em vez de avaliar a configuração apenas pela instalação:

Find the previous decision about the streaming parser. Use Funes recall if the repository history does not explain it, and cite the session you used.

Um bom resultado aponta para uma passagem anterior, identifica a sessão de origem e diferencia um experimento antigo do estado atual do repositório.

Para desfazer a integração sem apagar os dados armazenados, execute:

funes remove claude

A documentação de remoção informa que esse comando elimina a conexão do Funes, mas preserva a memória local, as transcrições originais, os caches e a memória publicada.

Conecte o Codex à mesma memória

Depois que o Claude Code estiver funcionando, adicione o Codex à mesma memória local:

funes add codex local
funes status

Para usar uma memória compartilhada no Hub, informe o mesmo identificador de repositório para os dois agentes:

funes add claude <org>/<repo>
funes add codex <org>/<repo>

O Codex tem uma etapa de confiança que é fácil de ignorar. O Funes grava seus hooks em ~/.codex/hooks.json; dentro do Codex, execute /hooks, revise as entradas do Funes e confie nelas. Até que os hooks sejam aprovados, o Codex os ignora — portanto, novos turnos não são indexados e nenhuma memória é publicada. O fluxo documentado de vinculação de memória exige o Codex 0.151.0. (Requisitos da automação do Codex)

Faça um teste real de transferência entre agentes

Use uma decisão específica que exista em uma sessão, mas não na outra:

1. No Claude Code, localize a decisão sobre o parser e anote um termo marcante da discussão.
2. Encerre a sessão para que a indexação e a automação de limite possam ser executadas.
3. No Codex, pergunte sobre esse termo e solicite o raciocínio anterior.
4. Confirme que a resposta identifica o Claude como harness de origem e aponta para a sessão ou o turno original.

Também é possível consultar as evidências diretamente pelo terminal:

funes recall "why did we switch away from the streaming parser"

O comando recall retorna passagens classificadas, não um resumo gerado. Cada resultado inclui informações sobre a origem e um comando get gerado automaticamente; copie esse comando quando precisar dos turnos ao redor.

Se o Codex não retornar nada, confira a versão, o estado de confiança em /hooks, o resultado de funes status e se a sessão do Claude é anterior à integração. Depois, tente novamente usando um termo marcante da discussão original.

Conecte o pi, o Hermes ou outro cliente MCP

Além do Claude Code e do Codex, o Funes oferece suporte direto ao pi e ao Hermes. O pi usa eventos de extensão; o Hermes usa hooks de shell, e sua indexação por turno é documentada como beta. (Detalhes sobre os agentes compatíveis)

Para um cliente compatível com MCP que não esteja entre esses quatro, execute o Funes como um servidor local via stdio:

{
  "mcpServers": {
    "funes": {
      "command": "funes",
      "args": ["mcp"]
    }
  }
}

Para vincular o servidor a uma memória compartilhada, adicione o repositório depois de mcp:

{
  "mcpServers": {
    "funes": {
      "command": "funes",
      "args": ["mcp", "<org>/<repo>"]
    }
  }
}

A documentação do MCP disponibiliza recall, get e status. O comando funes mcp é somente leitura: ele não indexa sessões nem publica dados. Para essas tarefas, use funes index, funes push ou uma integração compatível com funes add.

Uma memória especificada em uma chamada MCP individual substitui o vínculo definido no servidor. Se nenhuma memória for informada, o Funes usa a memória local.

Use o recall sem abrir mão das evidências

O Funes oferece três fluxos distintos:

Os padrões documentados do recall são 8 resultados, um conjunto candidato de 30 resultados para reranking, meia-vida de recência de 30 dias e 1 trecho vizinho. (Opções e padrões do recall)

Um ciclo confiável para depuração é:

1. Execute funes recall com o erro, o nome do componente ou a frase que descreve a decisão.
2. Siga o comando get gerado para consultar o turno completo.
3. Compare a decisão recuperada com a branch atual.
4. Faça a alteração ou execute o experimento.
5. Faça um novo recall usando o resultado, para que a próxima sessão consiga encontrá-lo.

O funes ask é mais limitado. Primeiro ele faz a recuperação e, depois, envia as passagens selecionadas e sua pergunta ao Claude ou ao Codex para produzir uma resposta. O agente filho não recebe ferramentas, stdin nem servidores MCP e não pode tentar uma nova recuperação se o primeiro resultado for ruim. Embora a recuperação seja local, a pergunta e as passagens recuperadas são enviadas ao provedor configurado para o agente selecionado. Por isso, a documentação do ask recomenda usar funes recall para materiais que você não enviaria a esse provedor.

Mantenha a memória confiável e operacional

O Funes preserva as passagens de origem e a proveniência, mas não consegue decidir se toda solução temporária histórica ainda se aplica.

“Os agentes de código ficam bem menos estranhos quando a memória é uma infraestrutura sem graça: índice local, proveniência exata e privacidade por padrão.” — @TheArtemisHunts no X

Um checklist enxuto para produção

O Funes oculta credenciais durante a indexação e faz uma varredura TruffleHog com bloqueio em caso de falha antes da publicação. A documentação do push informa que a ausência do scanner bloqueia a publicação; se uma credencial ativa chegar a um dataset remoto, faça sua rotação imediatamente, pois limpar um commit posterior não apaga o histórico do repositório.

Use tokens do Hugging Face com o menor privilégio possível: escopo de escrita para máquinas que publicam e somente leitura para colegas ou hosts que fazem apenas recall. Duas máquinas publicando na mesma memória remota também podem entrar em uma disputa; a documentação da automação não afirma que exista serialização entre máquinas.

A decisão prática

Escolha um destes pontos de partida em vez de instalar todas as integrações de uma vez:

FAQ sobre a memória de agentes de código do Funes

O Funes é local?

O Funes processa e armazena a memória localmente por padrão. Ele prioriza o uso local, mas não é automaticamente somente local: push, hooks de memória compartilhada e ask podem enviar dados para fora do processo local.

O Funes funciona com Claude Code e Codex?

Sim. O funes add é compatível com Claude Code e Codex, além de pi e Hermes. A vinculação de memória do Codex exige a versão 0.151.0 e hooks confiáveis.

O Funes indexa as sessões automaticamente?

Depois de executar funes add, as integrações compatíveis instalam uma automação de indexação por turno. O bootstrap inicial tem limite de duração, então sessões antigas e resultados volumosos de ferramentas podem exigir passagens posteriores.

Como compartilho uma memória entre Claude Code e Codex?

Use o mesmo argumento <org>/<repo> nos comandos funes add claude e funes add codex. O Funes mantém o índice de trabalho local e publica o dataset compartilhado nos limites das sessões.

E se o Funes recuperar uma decisão desatualizada?

Inspecione-a com funes recall, expanda o resultado usando o comando get gerado e compare-o com a branch atual antes de agir. Reformule a consulta quando a primeira recuperação não encontrar o que você procura.

O funes ask mantém os dados na minha máquina?

A recuperação e o reranking são locais, mas o ask envia a pergunta e as passagens recuperadas ao provedor configurado do Claude ou do Codex. Use recall para evidências sensíveis.

Posso remover o Funes sem apagar a memória?

Sim. funes remove claude, funes remove codex, funes remove pi e funes remove hermes removem a configuração das integrações, preservando a memória indexada e as transcrições de origem.