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 dá a cada projeto uma memória entre sessões. Escreve 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. Na terça-feira, fecha uma sessão no seu VPS. Na quarta-feira, o Claude Code não sabe nada sobre terça-feira. Tem de explicar o projeto novamente à mão ou deixar o modelo ler metade do repositório para o compreender. Ambas as opções consomem tokens, e a segunda consome muitos.

A versão 0.4.0 do Recall é a atual em julho de 2026, e o projeto é licenciado sob a licença MIT. É um plugin. Não faz qualquer chamada 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, ao retomar e ao limpar. Apresenta context.md para que a sessão abra com o seu resumo visível.
• Stop é executado sempre que o Claude termina uma resposta. Acrescenta essa interação 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 de acréscimos: prompts, 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/

Deverá ver history.md com conteúdo. É possível que não exista 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 solicitar:

/recall:save

Esse comando executa o sumarizador local sobre history.md e reescreve context.md. O algoritmo usa uma pontuação TF-IDF (frequência do termo, frequência inversa do documento), seguida de uma ordenação de frases com TextRank. O resultado é determinístico e extrativo, ou seja, seleciona frases que já existem no seu log. Nenhum modelo é chamado, pelo que esta etapa é gratuita e funciona offline na máquina.

Configurar o Recall para um projeto

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

{
  "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 ou desativa o log history.md.
• auto_save_context aceita off ou on_end e usa off por predefinição.
• summary_sentences define quantas frases permanecem em context.md. Aumentar este valor produz um resumo mais longo e aumenta ligeiramente a carga no arranque da sessão.
• redact remove padrões comuns de segredos antes de qualquer gravação em disco.
• include_git adiciona o diff atual e os commits recentes ao resumo.
• max_input_chars limita a quantidade de history.md que o sumarizador lê de cada vez.

Num projeto alojado num VPS, a alteração útil é ativar a gravação automática, porque uma sessão num servidor termina frequentemente quando o terminal é fechado, e não quando decide terminá-la.

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

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

touch .recall/.capture-paused

Faça isto antes de uma sessão em que vá trabalhar com credenciais de produção, porque a redação é um filtro e não uma garantia. O mesmo princípio aplica-se a manter 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 é barato. 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 estimativa publicada pelo projeto de mil a dois mil tokens para retomar uma sessão. Reproduzir uma transcrição anterior completa recarrega toda a conversa, na ordem de 85,000 tokens. Permitir que o modelo redescubra o projeto lendo ficheiros fica entre os dois, perto de 30,000 tokens, e esse valor aumenta com o repositório. A linha CLAUDE.md serve de 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 em código. Se também fornecer o resumo a um modelo local no mesmo VPS, verifique a janela em que ele está a ser colocado antes de confiar na retoma, porque Ollama trunca prompts longos num tamanho de contexto predefinido pequeno em vez de informar que eliminou o final.

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 resultados. Para obter a visão completa de como os tokens de uma sessão são efetivamente utilizados, como o Claude Code utiliza tokens apresenta a discriminação.

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 contida ajuda no outro lado da comparação, porque um agente orientado para fazer a menor alteração que funciona deixa um registo 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 escrito

Não existe nenhum diretório .recall/ depois de uma sessão completa. Os hooks nunca foram executados. Use /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. Por isso, uma caixa que não tenha nenhum dos dois não escreve nada e permanece silenciosa.

history.md aumenta, 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 Claude Code escreve usando como referência o diretório a partir do qual foi iniciado. Por isso, iniciar uma sessão a partir do diretório pessoal coloca 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 criados.

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 produzir esse efeito.

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

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

Onde o Recall termina

O Recall é um log com um sumarizador, e é importante deixar claro o que fica de fora.

O sumarizador é extrativo. O TextRank seleciona frases que já estão em history.md, portanto 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 tomada 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 procurar em history.md. Também não transporta informação entre sessões: duas sessões abertas ao mesmo tempo no mesmo VPS não conseguem ver os logs umas das outras. Quando uma precisa de saber o que a outra está a fazer, as sessões podem trocar texto diretamente entre si enquanto estão em execução.

Não ajuda dentro de uma sessão. O preenchimento da janela de contexto 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 complemento deste guia.

Por conceção, o resumo é tratado como entrada não confiável. context.md é inserido dentro de um bloco delimitado e identificado, e o Claude pergunta antes de confiar nele. Esta conceção 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 vai ler. A frequência com que o agente pede confirmação sobre aquilo que lê é definida pelo modo de permissões com que a sessão é iniciada, e o modo automático passa a ser o padrão do Claude Code em 14 August 2026. 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 com segurança num VPS aborda o limite mais amplo.

A redação é uma proteção de melhor esforço. Procura 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 reflete honestamente o nível de maturidade. Na versão 0.4.0, em July 2026, as chaves de configuração e a estrutura de ficheiros ainda podem mudar entre releases. Leia o changelog antes de atualizar uma configuraçã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. O resumo usa TF-IDF e TextRank em vez de um modelo, por isso esta etapa não tem 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 razão 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, os hooks não estão a ser executados: confirme que o plugin está carregado com /recall:show e, em seguida, confirme que python3 -V responde nesse sistema, porque os hooks são scripts Python.

Quanto poupa o Recall por sessão?

Carregar um resumo custa cerca de 1,200 tokens, contra os típicos 30,000 tokens de um modelo que tenha 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 retomada a partir de um resumo.

Ainda preciso de um ficheiro CLAUDE.md?

Sim, e os dois ficheiros têm funções diferentes. CLAUDE.md é aquilo 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 guarda 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.