Como adicionar memória ao Claude Code em uma VPS

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

Recall é um plugin do Claude Code que fornece memória para cada projeto entre as sessões. Ele grava dois arquivos Markdown em uma pasta .recall/ dentro do projeto: um log somente para acréscimos do que aconteceu e um resumo curto de onde você parou. Um resumidor local escrito em Python produz os dois arquivos na máquina em que você está trabalhando. Portanto, a memória não consome tokens de API.

Ele resolve uma lacuna pequena e constante. Você encerra uma sessão no seu VPS na terça-feira. Na quarta-feira, o Claude Code não sabe nada sobre a terça-feira. Você explica o projeto novamente à mão ou deixa o modelo ler metade do repositório para entender o contexto. As duas opções consomem tokens. A segunda consome muitos tokens.

A versão 0.4.0 do Recall é a atual em julho de 2026, e o projeto usa a licença MIT. Ele é um plugin. Nada nele faz chamadas de rede.

O que você precisa na VPS

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

python3 -V

Ubuntu 24.04 responde Python 3.12.3. O Recall é compatível com Python 3.9 e versões posteriores. Imagens de contêiner mínimas às vezes não incluem nenhum interpretador; nesse caso, o shell responde python3: command not found. Instale um antes de continuar.

sudo apt update && sudo apt install -y python3

NumPy é um acelerador opcional para uma etapa do sumarizador. Você não precisa dele.

python3 -c "import numpy"

ModuleNotFoundError: No module named 'numpy' é uma resposta aceitável aqui. O sumarizador tem um caminho em Python puro, e a suíte de testes do projeto verifica se os dois caminhos selecionam as mesmas frases.

A memória da sessão é mais importante em um servidor do que em um laptop, porque o trabalho no servidor ocorre em visitas curtas distribuídas ao longo de vários dias. Se você já tem Claude Code executando no tmux em uma VPS, o Recall é o componente que transporta a sessão de ontem para a sessão de hoje.

Instalar o Recall pelo marketplace de plugins

Dois comandos, executados dentro de uma sessão do Claude Code:

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

O segundo comando lê plugin@marketplace. Os dois nomes são recall aqui. Isso 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 exibe o resumo atual. Em um projeto novo, ainda não há nada para exibir. Portanto, o que você está verificando é 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 no diretório do projeto com claude --plugin-dir ~/recall.

O que os hooks gravam e quando

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

• SessionStart é executado na inicialização, na retomada e na limpeza. Ele exibe context.md para que a sessão seja aberta com o resumo visível.
• Stop é executado sempre que o Claude termina uma resposta. Ele adiciona esse turno ao log.
• SessionEnd é executado quando a sessão é encerrada e pode gerar o resumo novamente.

Isso gera dois arquivos, ambos dentro de .recall/.

• history.md é o registro somente para acréscimo: prompts, respostas, arquivos modificados e comandos executados.
• context.md é o resumo gerado: o objetivo, um resumo, as próximas etapas, os arquivos modificados, os comandos executados e o contexto do git.

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

ls -la .recall/

Você deverá ver history.md com conteúdo. Talvez não exista nenhum context.md, e esse é o comportamento padrão, não uma falha. auto_save_context é off, a menos que você o defina. Portanto, o resumo só é gravado quando você o solicita:

/recall:save

Esse comando executa o sumarizador local sobre history.md e regrava context.md. O algoritmo usa a pontuação TF-IDF (frequência do termo, frequência inversa do documento) e, em seguida, a classificação de sentenças TextRank. Ele é determinístico e extrativo, o que significa que seleciona sentenças que já existem no log. Nenhum modelo é chamado. Portanto, essa etapa é gratuita e funciona com a máquina offline.

Configurar o Recall para um projeto

A configuração fica em um arquivo recall.config.json no diretório raiz do projeto. Estes são os padrões 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 arquivos 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 padrão.
• summary_sentences define quantas frases permanecem em context.md. Aumentar esse valor gera um resumo mais longo e uma carga ligeiramente maior no início da sessão.
• redact remove padrões comuns de segredos antes que qualquer dado seja gravado no disco.
• include_git adiciona o diff atual e os commits recentes ao resumo.
• max_input_chars limita quanto de history.md o sumarizador lê em uma única passagem.

Para um projeto em um VPS, a alteração mais útil é ativar o salvamento automático, porque uma sessão em um servidor geralmente termina quando o terminal é fechado, e não quando você decide interrompê-la.

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

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

touch .recall/.capture-paused

Faça isso antes de uma sessão em que você manipulará credenciais de produção, porque a redação é um filtro, não uma garantia. O mesmo princípio orienta manter segredos fora dos agentes de IA em geral: o segredo seguro é aquele que o agente nunca vê.

Quantos tokens o Recall economiza?

Depende de qual era a 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 arquivos.

[
  {
    "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 médio porte, 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 uma retomada. Reproduzir uma transcrição anterior completa recarrega toda a conversa, na faixa de 85,000 tokens. Permitir que o modelo redescubra o projeto lendo arquivos fica entre os dois, perto de 30,000 tokens, e esse número aumenta conforme o repositório cresce. A linha CLAUDE.md serve como referência de escala: ela é mais barata porque é curta e estática, e informa ao modelo suas regras permanentes, em vez do que aconteceu na noite anterior.

Meça seus próprios valores. Um token corresponde aproximadamente a quatro caracteres de prosa em inglês e a um pouco menos no código.

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 na janela de contexto no momento, e /cost informa os totais da sessão. Inicie uma sessão sem contexto, inicie a próxima com um resumo disponível e compare os resultados. Para ver exatamente onde os tokens de uma sessão são usados, como o Claude Code usa os 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 é usado representa um pequeno custo, não uma economia. Mantenha summary_sentences próximo do valor padrão, a menos que suas sessões sejam longas.

Recriar o resumo sem uma sessão

Se você clonou o repositório, o sumarizador tem seu próprio ponto de entrada de linha de comando. Isso é útil em um VPS quando uma sessão foi encerrada junto com o terminal e você ainda precisa do resumo.

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

A saída da ajuda lista as flags aceitas: --cwd para a raiz do projeto, --transcript para um arquivo 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, em seguida, grava context.md no diretório especificado. Se você instalou pelo marketplace, o plugin fica em um diretório gerenciado pelo Claude Code, e /recall:save é a forma compatível de executar a mesma tarefa.

Por que nada está sendo gravado

Nenhum diretório .recall/ após uma sessão completa. Os hooks nunca foram executados. Digite /recall:show para confirmar que o plugin está carregado e execute python3 -V. O comando do hook tenta python3 primeiro e python em seguida. Portanto, uma máquina sem nenhum dos dois não grava nada e não informa o problema.

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

Os arquivos aparecem no projeto errado. O Recall grava usando caminhos relativos ao diretório em que o Claude Code foi iniciado. Portanto, iniciar uma sessão no diretório inicial do usuário 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 arquivos foram gravados.

A captura parou e nenhum aviso foi exibido. Verifique o marcador de pausa com ls -a .recall/. Um arquivo .capture-paused criado na semana passada continua ativo.

O resumo é insuficiente após uma sessão longa. max_input_chars limita a entrada do sumarizador a 200000 caracteres. Portanto, um log muito longo é truncado. Faça a rotação dele.

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

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

Onde o Recall para

O Recall é um log com um sumarizador, e é importante deixar claro o que isso não inclui.

O sumarizador é extrativo. O TextRank seleciona frases que já estão em history.md, portanto nunca avalia se uma decisão estava correta. Uma decisão errada registrada na terça-feira é apresentada exatamente como uma decisão correta na quarta-feira. Quando há consequências reais, leia context.md e corrija-o manualmente. É um arquivo markdown, e nada impede que você o edite.

Não há pesquisa. Você tem um resumo atual e um log crescente por projeto, não uma memória pesquisável entre projetos. Se a pergunta for o que você decidiu sobre o banco de dados três semanas atrás, você estará usando grep em history.md.

Ele não ajuda dentro de uma sessão. Uma janela de contexto que se esgota no meio da sessão é um problema diferente, com correções diferentes, e gerenciar a janela de contexto dentro de uma sessão é o material complementar a este guia.

O resumo é tratado como entrada não confiável por definição. context.md é inserido em um bloco cercado e identificado, e o Claude pergunta antes de confiar nele. Essa abordagem existe porque um diretório .recall/ versionado é um local onde qualquer pessoa com acesso de commit pode escrever texto que seu agente lerá. Decida uma vez se .recall/ é pessoal ou compartilhado: adicione-o a .gitignore para memória pessoal, ou faça commit dele e revise-o como qualquer outra contribuição. Se o agente for executado sem supervisão, executar o Claude Code com segurança em um VPS aborda o limite mais amplo.

A redação é feita com o melhor esforço. Ela 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 informa honestamente o nível de maturidade. Na versão 0.4.0, em julho de 2026, as chaves de configuração e a estrutura de arquivos ainda podem mudar entre releases. Portanto, leia o changelog antes de atualizar uma configuração da qual você depende.

FAQ

O Recall envia meu código ou minhas 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, não um modelo, portanto essa etapa não tem custo e funciona com a máquina offline. A desvantagem é que o resumo é extrativo: ele seleciona frases do seu log em vez de escrever frases novas.

Por que meu .recall/context.md está ausente ou desatualizado?

auto_save_context usa off por padrão, portanto o resumo só é regenerado quando você executa /recall:save. Defina "auto_save_context": "on_end" em recall.config.json para que ele seja reescrito ao final de cada sessão. Se history.md também estiver ausente, os hooks não estão sendo executados: confirme se o plugin está carregado com /recall:show. Em seguida, confirme se python3 -V responde nesse servidor, pois os hooks são scripts Python.

Quanto o Recall economiza 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 precisa ler o repositório novamente para descobrir em que ponto está. Esses são valores típicos. Meça os seus com wc -c .recall/context.md e o comando /context dentro de uma sessão, comparando uma inicialização sem resumo com uma que retoma a partir de um resumo.

Ainda preciso de um arquivo CLAUDE.md?

Sim, e os dois têm funções diferentes. CLAUDE.md é o que você escreve intencionalmente: as regras permanentes e os comandos de build. context.md é gerado com base no que realmente aconteceu na última sessão, portanto contém a migração parcialmente concluída que você nunca pensaria em registrar. Mantenha os dois.

Um único VPS pode armazenar a memória de vários projetos?

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