Recall: memória local para o Claude Code no VPS

O que o Recall faz pela memória do Claude Code

Recall é um plugin do Claude Code que fornece memória a cada projeto entre sessões. Grava dois ficheiros Markdown numa pasta .recall/ dentro do projeto: um registo apenas de acréscimos sobre o que aconteceu e um resumo curto do ponto onde ficou. Ambos são produzidos na máquina onde está a trabalhar por um sumarizador Python local, pelo que a própria memória não consome tokens de API.

A lacuna que preenche é pequena e constante. Encerra uma sessão no seu VPS na terça-feira. Na quarta-feira, uma sessão nova não carrega automaticamente a conversa de terça-feira, embora a memória automática integrada do Claude Code possa manter notas entre sessões. Se essas notas não indicarem o ponto onde parou, tem de explicar novamente o projeto à mão ou deixar o modelo ler metade do repositório para o perceber. Ambas as opções consomem tokens, e a segunda consome muitos.

A versão 0.4.0 do Recall, lançada em 18 July 2026, continua a ser a versão mais recente em October 2026, e o projeto está licenciado sob a licença MIT. É um plugin. Não faz chamadas de rede.

O que é necessário no VPS

Os hooks de captura do Recall são scripts Python distribuídos com o plugin. Não existem dependências de terceiros. Portanto, o único requisito real é um interpretador.

python3 -V

O Ubuntu 24.04 responde Python 3.12.3. O Recall é compatível com Python 3.9 e versões posteriores. Imagens de contentor mínimas, por vezes, não incluem nenhum interpretador. Nesse caso, a shell responde python3: command not found. Instale um antes de continuar.

sudo apt update && sudo apt install -y python3

O NumPy é um acelerador opcional para uma etapa do sumarizador. Não precisa dele.

python3 -c "import numpy"

ModuleNotFoundError: No module named 'numpy' é uma resposta aceitável neste caso. O sumarizador tem um caminho implementado em Python puro, e a suite de testes do projeto confirma que ambos os caminhos selecionam as mesmas frases.

A memória da sessão é mais importante num servidor do que num portátil, porque o trabalho de administração chega em visitas curtas distribuídas ao longo de vários dias. Se já tem o Claude Code a executar no tmux num VPS, o Recall é o componente que transporta a sessão de ontem para a sessão de hoje.

Instalar o Recall a partir do marketplace de plugins

Dois comandos, introduzidos numa sessão do Claude Code:

/plugin marketplace add raiyanyahya/recall
/plugin install recall@recall

O segundo comando lê plugin@marketplace. Ambos os nomes são recall aqui. Isto parece um erro de copiar e colar, mas não é.

Verifique a instalação executando um dos comandos do próprio plugin:

/recall:show

/recall:show mostra o resumo atual. Num projeto completamente novo, ainda não há nada para mostrar. Portanto, o que está realmente a verificar é se o comando existe. Se o Claude Code não reconhecer /recall:show, o plugin não foi carregado e nenhum hook será executado.

Para executar a partir de um checkout, clone o repositório e valide-o primeiro:

git clone https://github.com/raiyanyahya/recall ~/recall
cd ~/recall && claude plugin validate .

claude plugin validate . lê o manifesto em .claude-plugin/ e informa se o plugin está bem formado. Em seguida, inicie o Claude Code a partir do diretório do projeto com claude --plugin-dir ~/recall.

O que os hooks escrevem e quando

O Recall regista três hooks do Claude Code. Cada um executa um script Python a partir do diretório do plugin.

• SessionStart é executado no arranque, na retoma e ao limpar a sessão. Apresenta context.md para que a sessão abra com o resumo visível.
• Stop é executado sempre que o Claude termina uma resposta. Anexa esse turno ao log.
• SessionEnd é executado quando a sessão termina e pode gerar novamente o resumo.

São criados dois ficheiros, ambos dentro de .recall/.

• history.md é o registo apenas para anexação: pedidos, respostas, ficheiros alterados e comandos executados.
• context.md é o resumo gerado: o objetivo, um resumo, os passos seguintes, os ficheiros alterados, os comandos executados e o contexto do git.

Depois de uma sessão real, consulte o diretório.

ls -la .recall/

Com a captura ativada, sem marcador de pausa e com uma transcrição disponível, deverá ver history.md com conteúdo. É possível que não veja context.md, o que corresponde ao comportamento predefinido e não a uma falha. auto_save_context é off, a menos que o defina. Por isso, o resumo só é escrito quando o solicita:

/recall:save

Esse comando executa o resumidor local sobre history.md e reescreve context.md. O algoritmo usa a pontuação TF-IDF (frequência dos termos, frequência inversa dos documentos), seguida da ordenação de frases TextRank. O resultado é determinístico e extrativo, o que significa que seleciona frases que já existem no log. Nenhum modelo é chamado, por isso esta etapa é gratuita e funciona com a máquina offline.

Configure o Recall para um projeto

A configuração fica num ficheiro recall.config.json na raiz do projeto. Estes são os valores predefinidos:

{
  "output_dir": ".recall",
  "capture_history": true,
  "summary_sentences": 8,
  "redact": true,
  "include_git": true,
  "max_input_chars": 200000
}

• output_dir define onde os dois ficheiros ficam. Mantenha-os dentro do projeto.
• capture_history ativa e desativa o log history.md.
• auto_save_context aceita off ou on_end e, por predefinição, usa off.
• summary_sentences define quantas frases permanecem em context.md. Aumentar este valor produz um resumo mais longo e aumenta ligeiramente a carga no início da sessão.
• redact remove padrões comuns de segredos antes de qualquer conteúdo ser escrito no disco.
• include_git adiciona ao resumo as estatísticas do diff atual e os commits recentes.
• max_input_chars limita a quantidade de history.md que o sumarizador lê de cada vez.

Num projeto alojado num VPS, a alteração mais útil é ativar a gravação automática, porque uma sessão num servidor termina muitas vezes quando o terminal é desligado, e não quando decide parar.

{
  "auto_save_context": "on_end",
  "summary_sentences": 12
}

Para interromper temporariamente a captura sem alterar a configuração, crie o marcador de pausa. Remova-o para iniciar novamente a captura.

touch .recall/.capture-paused

Faça isto antes de uma sessão em que vá tratar de credenciais de produção, porque a redação é um filtro e não uma garantia. O mesmo princípio aplica-se a manter os segredos fora dos agentes de IA em geral: o segredo seguro é aquele que o agente nunca vê.

Quanto o Recall economiza em tokens?

Depende da alternativa. Carregar um resumo no início da sessão tem um custo baixo. O que ele substitui pode ser caro, porque um modelo sem memória do seu projeto precisa redescobri-lo lendo ficheiros.

[
  {
    "label": "Recall context.md",
    "char_count": "4,800",
    "est_tokens": "1,200"
  },
  {
    "label": "Hand-written CLAUDE.md",
    "char_count": "3,200",
    "est_tokens": "800"
  },
  {
    "label": "Re-reading the repo",
    "char_count": "120,000",
    "est_tokens": "30,000"
  },
  {
    "label": "Full transcript replay",
    "char_count": "340,000",
    "est_tokens": "85,000"
  }
]

Estes são valores típicos para um projeto de tamanho médio, não uma medição do seu projeto. Um resumo do Recall é carregado com aproximadamente 1,200 tokens, em linha com a indicação publicada pelo projeto de que um reinício usa entre mil e dois mil tokens. Reproduzir uma transcrição anterior completa carrega novamente toda a conversa, num total próximo de 85,000 tokens. Deixar o modelo redescobrir o projeto lendo ficheiros fica entre os dois valores, perto de 30,000 tokens, e esse número aumenta com o repositório. A linha CLAUDE.md serve como referência de escala: é mais barata porque é curta e estática, e informa o modelo sobre as suas regras permanentes, em vez de descrever o que aconteceu na noite anterior.

Meça os seus próprios valores. Um token corresponde aproximadamente a quatro caracteres de prosa em inglês e a um pouco menos no código. Se também enviar o resumo para um modelo local no mesmo VPS, verifique a janela em que ele está a ser colocado antes de confiar no reinício, porque o comprimento de contexto predefinido do Ollama depende da VRAM disponível.

wc -c .recall/context.md .recall/history.md
echo $(( $(wc -c < .recall/context.md) / 4 ))

Dentro de uma sessão, /context mostra o que está carregado atualmente na janela de contexto, e /cost apresenta os totais da sessão. Inicie uma sessão sem contexto, inicie a seguinte com um resumo disponível e compare os valores. Para obter a visão completa de como os tokens de uma sessão são utilizados, consulte como o Claude Code utiliza os tokens.

Há uma ressalva importante. O resumo é carregado no início de todas as sessões. Portanto, um resumo que nunca é utilizado representa um pequeno custo, não uma poupança. Mantenha summary_sentences próximo do valor predefinido, exceto se as suas sessões forem longas. Uma sessão mais controlada também ajuda no outro lado da contagem, porque um agente orientado para fazer a menor alteração que funciona deixa um log mais curto para o sumarizador classificar.

Reconstruir o resumo sem uma sessão

Se clonou o repositório, o sumarizador tem o seu próprio ponto de entrada de linha de comandos. Isto é útil num VPS quando uma sessão terminou com o terminal e ainda precisa do resumo.

python3 ~/recall/scripts/make_context.py --help

A saída da ajuda lista as flags aceites: --cwd para a raiz do projeto, --transcript para um ficheiro de transcrição explícito, --quiet para suprimir a saída e --harness para escolher entre claude e opencode. Aponte-o para um projeto:

python3 ~/recall/scripts/make_context.py --cwd /srv/projects/api

Ele lê a transcrição da sessão e history.md e depois escreve context.md no diretório indicado. Se instalou através do marketplace, o plugin fica num diretório gerido pelo Claude Code, e /recall:save é a forma suportada de executar o mesmo trabalho.

Por que nada está a ser gravado

Não existe nenhum diretório .recall/ depois de uma sessão completa. Verifique se a captura está desativada, se o diretório de saída está configurado noutro local ou se não foi encontrado nenhum transcript antes de concluir que os hooks nunca foram executados. Execute /recall:show para confirmar que o plugin está carregado e, em seguida, execute python3 -V. O comando do hook tenta primeiro python3 e depois python. Uma máquina sem nenhum dos dois falha com stderr e status de saída 127. O Claude Code mostra um aviso de erro não bloqueante do hook com a primeira linha de stderr.

history.md cresce, mas context.md nunca muda. Por predefinição, auto_save_context é off. Execute /recall:save ou defina a chave como on_end e deixe o hook SessionEnd tratar disso.

Os ficheiros aparecem no projeto errado. O Recall grava caminhos relativos ao diretório a partir do qual o Claude Code foi iniciado. Por isso, iniciar uma sessão a partir do diretório pessoal grava a memória nesse local. Inicie a sessão a partir da raiz do projeto e use ls -la .recall/ para descobrir onde os ficheiros foram realmente gravados.

A captura parou e não recebeu nenhum aviso. Verifique o marcador de pausa com ls -a .recall/. Um ficheiro .capture-paused que tenha criado na semana passada continua a desempenhar essa função.

O resumo é curto depois de uma sessão longa. max_input_chars limita a entrada do sumarizador a 200000 caracteres, por isso um log muito longo é truncado. Faça a rotação do log.

mv .recall/history.md .recall/history-2026-07-30.md

Depois, execute uma sessão curta e verifique novamente ls -la .recall/ para confirmar que foi criado um novo history.md.

Onde o Recall deixa de atuar

O Recall é um log com um resumidor, e é importante deixar claro o que isso exclui.

O resumidor é extrativo. O TextRank seleciona frases que já estão em history.md, por isso nunca avalia se uma decisão foi correta. Uma decisão errada registada na terça-feira tem exatamente o mesmo aspeto que uma boa decisão registada na quarta-feira. Quando os riscos são reais, leia context.md e corrija-o manualmente. É um ficheiro markdown e nada impede que o edite.

Não existe pesquisa. Tem um resumo atual e um log crescente por projeto, não uma memória consultável entre projetos. Se a pergunta for o que decidiu sobre a base de dados há três semanas, terá de fazer grep em history.md. Isto não fornece coordenação em tempo real: duas sessões no mesmo projeto partilham o ficheiro de log, mas o Recall não envia novas entradas do log para o contexto da outra sessão. Por isso, quando uma sessão precisa de saber o que a outra está a fazer, as sessões podem passar texto diretamente entre si enquanto estão em execução.

Isto não ajuda dentro de uma sessão. Uma janela de contexto que fica cheia a meio de uma sessão é um problema diferente, com soluções diferentes, e gerir a janela de contexto dentro de uma sessão é o artigo complementar a este guia.

O resumo é tratado deliberadamente como entrada não confiável. context.md é inserido num bloco delimitado e identificado, e o Claude pergunta antes de confiar nele. Esta abordagem existe porque um diretório .recall/ submetido ao repositório é um local onde qualquer pessoa com acesso de commit pode escrever texto que o seu agente irá ler. O grau de intervenção do agente para perguntar sobre aquilo que lê é definido pelo modo de permissões com que a sessão é iniciada. Com o Claude Code v2.1.283 ou posterior, o modo automático já é o modo de arranque integrado para sessões interativas no terminal e no VS Code, em todos os planos e fornecedores, pelo que um classificador, e não o utilizador, analisa a maioria das ações; as organizações com a configuração HIPAA continuam a iniciar no modo Manual. Decida uma vez se .recall/ é pessoal ou partilhado: adicione-o a .gitignore para memória pessoal, ou faça commit dele e reveja-o como qualquer outra contribuição. Se o agente for executado sem supervisão, executar o Claude Code em segurança numa VPS aborda o limite mais amplo.

A redação de dados é feita da melhor forma possível, sem garantia. Destina-se a padrões comuns, como chaves de API, tokens, blocos PEM e atribuições .env. Leia .recall/ antes de fazer commit dele.

O número da versão é honesto quanto ao grau de maturidade. Na versão 0.4.0, ainda a versão mais recente em outubro de 2026, as chaves de configuração e a estrutura de ficheiros ainda podem mudar entre versões. Por isso, leia o changelog antes de atualizar uma instalação da qual dependa.

FAQ

O Recall envia o meu código ou as transcrições para algum lugar?

Não. Os hooks de captura e o sumarizador são scripts Python executados na sua própria máquina, o plugin não contém nenhuma chave de API e não faz chamadas de rede. A sumarização usa TF-IDF e TextRank em vez de um modelo, por isso não tem qualquer custo e funciona com a máquina offline. A desvantagem é que o resumo é extrativo: seleciona frases do seu log em vez de escrever frases novas.

Por que motivo o meu .recall/context.md está em falta ou desatualizado?

auto_save_context usa off por predefinição, por isso o resumo só é regenerado quando executa /recall:save. Defina "auto_save_context": "on_end" em recall.config.json para que seja reescrito quando cada sessão terminar. Se history.md também estiver em falta, verifique capture_history, o marcador .capture-paused e se existe uma transcrição da sessão: os hooks em execução não escrevem o histórico nesses casos. Confirme que o plugin está carregado com /recall:show e depois confirme que python3 -V responde nesse servidor, porque os hooks são scripts Python.

Quanto é que o Recall poupa por sessão?

Carregar um resumo custa cerca de 1,200 tokens, em comparação com os 30,000 tokens típicos de um modelo que tem de ler novamente o seu repositório para determinar em que ponto está. Estes são valores típicos. Meça os seus próprios valores com wc -c .recall/context.md e o comando /context dentro de uma sessão, comparando um arranque a frio com uma sessão que retoma a partir de um resumo.

Ainda preciso de um ficheiro CLAUDE.md?

Sim, e os dois têm funções diferentes. CLAUDE.md é o que escreve deliberadamente: as regras permanentes e os comandos de compilação. context.md é gerado a partir do que realmente aconteceu na sessão anterior, por isso contém a migração inacabada que nunca se lembraria de registar. Mantenha ambos.

Um VPS pode guardar memória para vários projetos?

Sim. O Recall mantém a memória em .recall/ dentro do diretório de cada projeto, por isso dois projetos no mesmo servidor mantêm logs e resumos separados. Inicie sempre o Claude Code a partir da raiz do projeto, porque os ficheiros seguem o diretório de trabalho e não a conta de utilizador.