Deja Vu: memória dos agentes no Linux

Você resolveu um problema no Claude Code, continuou o projeto no Codex e, semanas depois, o Cursor tenta investigar tudo de novo. A solução talvez ainda esteja no disco — enterrada nos históricos de sessão. O Deja Vu, cujo comando é deja, transforma esses registros em memória pesquisável, acessível pelo terminal e pelos próprios agentes. O projeto é escrito em Go e distribuído sob licença MIT.

Este é um complemento do nosso comparativo de alternativas ao Claude-Mem em Go, Rust e C. Aqui vamos além do README: arquitetura, instalação rápida, integração seletiva, privacidade, limites e uma avaliação de maturidade baseada no código e em testes locais.

O que o Deja Vu faz de diferente

Muitas ferramentas de memória começam vazias. Você instala hooks, deixa o agente trabalhar e espera acumular observações ou pede que ele grave decisões. O Deja Vu pode começar pelo passado: lê os históricos que os agentes já mantêm localmente e os reúne em um índice.

• Busca retroativa: uma sessão anterior à instalação pode aparecer na primeira consulta, desde que o histórico ainda exista e seja suportado.
• Continuidade entre agentes: uma decisão registrada no Claude pode ser recuperada em uma sessão do Codex, sem importar manualmente cada conversa.
• Contexto do trabalho: além da conversa, pode recuperar arquivos mencionados, comandos, resultados e trechos substituídos por ferramentas de edição, conforme o formato do agente.
• Utilidade sem integração: a CLI e a interface de terminal já funcionam sem registrar um servidor MCP.
• Busca básica sem modelo: o caminho padrão não exige API key, download de LLM ou serviço de embeddings.

Isso não significa recuperar uma sessão que nunca foi salva nem reconstruir integralmente qualquer conversa apagada. A qualidade depende do que cada agente registrou e do que o parser consegue interpretar. Para conhecer os formatos efetivamente lidos, consulte a tabela de fontes da versão analisada.

Como funciona: histórico, índice e recuperação

O fluxo é simples de entender: descobrir os arquivos ou bancos dos agentes, interpretar sessões, sanitizar os textos, construir o índice e entregar trechos relevantes. Claude Code usa JSONL; Codex tem rollouts; outras ferramentas guardam sessões em JSON, Markdown ou SQLite. Não há um formato universal, por isso os parsers são parte central do projeto.

Um detalhe fácil de errar: ~/.cache/deja/index.db é o nome de um diretório, não de um banco SQLite. Na 0.22.1, ele contém registros binários, listas de ocorrências dos termos e metadados. Não tente abri-lo com sqlite3. O formato e o ranking lexical são explicados na documentação de arquitetura.

A consulta lexical usa termos e ranking BM25; frases e filtros refinam a recuperação. Também existem mecanismos de aproximação quando a consulta exata não basta. Isso é diferente de afirmar que toda busca é semântica: a camada de embeddings é opcional e precisa de configuração própria.

O servidor MCP roda sobre stdio: o cliente inicia deja mcp e conversa pela entrada e saída padrão. Você não precisa abrir uma porta HTTP nem manter um daemon central apenas para usar esse caminho.

Instalação rápida no Linux

As releases fornecem binários para Linux amd64 e arm64. Para começar pelo instalador oficial, sem compilar Go, baixe o script, leia-o e só então execute. O exemplo fixa a revisão do script analisada; o próprio script consulta a release estável mais recente, portanto não fixa a versão do binário.

mkdir -p "$HOME/.cache/deja-installer"
curl -fsSL \
  https://raw.githubusercontent.com/vshulcz/deja-vu/v0.22.1/install.sh \
  -o "$HOME/.cache/deja-installer/install.sh"

less "$HOME/.cache/deja-installer/install.sh"
sh "$HOME/.cache/deja-installer/install.sh"

export PATH="$HOME/.local/bin:$PATH"
deja version
deja index
deja search "connection pool"
deja doctor

Por padrão, o destino é ~/.local/bin. Não use sudo para instalar no diretório pessoal. Se o comando não aparecer em um terminal novo, inclua ~/.local/bin no PATH do seu shell; o instalador também informa o caminho completo que pode ser usado imediatamente.

O atalho divulgado pelo projeto é baixar o script da branch principal e passá-lo diretamente para sh, seguido de deja install --auto. É rápido, mas são duas decisões distintas: executar código recém-baixado e autorizar alterações nas configurações dos agentes. O procedimento acima permite inspecionar a primeira e adiar a segunda. Veja o guia oficial de instalação.

Precisa instalar sqlite3?

Para históricos em SQLite, sim: o Deja Vu chama o executável local sqlite3 para ler o banco de origem. Isso aparece, por exemplo, em integrações com Cursor IDE e opencode. O binário Go não embute uma biblioteca SQLite via CGO.

# Debian / Ubuntu: necessário para fontes que usam SQLite
sudo apt update
sudo apt install sqlite3

deja sources
deja doctor

Ter um binário principal único não significa que todos os formatos de todos os agentes funcionem sem utilitários auxiliares. Use o diagnóstico para descobrir dependências ausentes na sua combinação de fontes, especialmente formatos comprimidos.

Alternativa com Go e versão fixa

O go.mod da release declara Go 1.25. Quem já tem um toolchain compatível pode compilar a tag explicitamente:

go install github.com/vshulcz/deja-vu/cmd/deja@v0.22.1

# Sem GOBIN personalizado, o executável fica no bin do GOPATH.
export PATH="$(go env GOPATH)/bin:$PATH"
deja version

Uma compilação via go install pode mostrar dev em deja version: a distribuição oficial injeta o número da release no build. Isso não altera a tag solicitada no comando de instalação.

O projeto também documenta Homebrew, npm e pacotes para Windows. Para Linux, o binário de release evita instalar uma linguagem só para usar a ferramenta. Em ambientes controlados, prefira uma release fixa e valide sua assinatura, não apenas o checksum.

Integração com Claude Code e Codex sem instalar tudo

Antes de modificar configurações, faça backup dos arquivos dos agentes que serão afetados. O instalador do Deja Vu também cria snapshots de configuração, mas isso não substitui seu próprio backup.

backup="$HOME/deja-config-backup-$(date +%Y%m%d-%H%M%S)"
mkdir -m 700 "$backup"

# Caminhos padrão; ajuste se você usa perfis ou diretórios personalizados.
for file in \
  "$HOME/.claude.json" \
  "$HOME/.claude/settings.json" \
  "$HOME/.claude/CLAUDE.md" \
  "$HOME/.codex/config.toml" \
  "$HOME/.codex/AGENTS.md"
do
  if [ -f "$file" ]; then
    cp --parents -- "$file" "$backup/"
  fi
done

# Registra MCP e orientação para os dois agentes, sem o modo automático.
deja install claude-code codex
deja doctor

Reinicie as sessões dos agentes para carregar a configuração. A distinção entre as opções importa:

Indexar um agente não é a mesma coisa que instalar hooks nele. O histórico pode ser pesquisável mesmo sem integração automática. Os eventos disponíveis também variam: não presuma que todos os clientes ofereçam o mesmo ciclo do Claude Code. Consulte o guia de integração por agente e rode deja help install na versão instalada.

Busca e facilidades que fazem diferença no dia a dia

A pergunta útil não é “quantas ferramentas existem?”, mas “quanto trabalho repetido consigo evitar?”. Comece com mensagens de erro, nomes de arquivos e termos que realmente apareceram na conversa.

# Busca nos históricos indexados
deja search "connection pool exhausted"

# Restringe ao agente e a uma janela de tempo
deja search --harness codex --since 30d "refresh token"

# Consulta uma expressão que começa com hífen
deja search -- "--force-with-lease"

# Resultado estruturado para automação
deja search --json "refresh token"

# Consulta a sintaxe e os filtros disponíveis
deja help search

Em um terminal interativo, deja sem argumentos abre a TUI. Ela permite pesquisar, ler uma sessão e navegar pelos resultados. Para saída textual, use deja brief. Filtros por agente, projeto e período ajudam a não confundir a decisão do aplicativo A com uma experiência feita no aplicativo B.

A 0.22.1 também amplia a leitura do código alterado na sessão, quando os transcripts contêm as chamadas de edição. É valioso para recuperar o raciocínio junto com o patch, mas não substitui um commit, um teste atual ou a revisão do diff.

MCP, hooks e memória curada

Na versão analisada, tools/list anuncia uma ferramenta principal chamada deja, com modos de operação. O agente pode consultar memória, contexto, arquivos e outros recortes sem carregar uma definição separada para cada comando da CLI. Confirmamos esse contrato em um teste JSON-RPC local.

MCP é o canal de consulta; hooks são os pontos de ativação automática. Sem hook, o agente precisa decidir chamar a ferramenta. Com integração automática, uma parte do contexto pode chegar na abertura ou em outros eventos suportados pelo cliente. Isso aumenta a conveniência, mas também merece atenção ao orçamento de contexto e ao escopo das informações recuperadas.

O Deja Vu não fica restrito à busca de conversa bruta. deja remember registra uma nota e deja promote transforma uma sessão em informação curada com proveniência e estado de ciclo de vida. Isso ajuda a distinguir “tentamos essa abordagem” de “essa é a decisão vigente”. Ainda assim, cabe à equipe validar decisões e retirar as que ficaram obsoletas.

Se você já usa ai-memory ou Engram, uma estratégia conservadora é testar o Deja Vu primeiro como CLI de investigação. Evite ativar dois sistemas de auto-recall ao mesmo tempo sem medir a duplicação de contexto e definir quem guarda a memória durável.

Maturidade do código: os sinais positivos

O repositório foi criado em 14 de julho de 2026, segundo os metadados públicos do GitHub. Portanto, é um projeto jovem na data desta análise. A conclusão “ainda jovem” não depende do número de estrelas: depende de tempo de operação, estabilidade dos contratos e evidência de testes.

• Separação de responsabilidades: a árvore distingue fontes, indexação, consulta, ranking, sanitização, política de recuperação, digest e interface de terminal.
• Escopo Go enxuto nas dependências: o go.mod dessa tag contém a declaração do módulo e da versão de Go, sem uma lista de dependências externas. Isso simplifica parte da cadeia de build, embora aumente a responsabilidade sobre implementações próprias.
• Testes além do caminho feliz: há cenários de índice corrompido, interrupção de escrita, concorrência, reconstrução, segredos, remoção e formatos de diferentes agentes. A tag tem 2.572 arquivos *_test.go; esse é um número de arquivos, não uma medição de cobertura nem de qualidade.
• CI com barreiras concretas: o workflow inclui go vet, testes com detector de corrida em Linux/macOS, verificação de vulnerabilidades e pisos de cobertura. A configuração define piso total de 87,5% para o código distribuído; isso não é uma cobertura total medida por nós.
• Distribuição cuidada: releases têm checksums, assinatura do arquivo de checksums e SBOM. O build de distribuição desabilita CGO.
• Limites documentados: o modelo de segurança explica exportação, políticas, sanitização e ausência de criptografia em repouso, em vez de prometer privacidade absoluta.

Checksum não é assinatura: o instalador e o atualizador comparam o SHA-256 do arquivo, mas não verificam automaticamente a assinatura. Isso detecta corrupção do download, não uma release adulterada junto com seu arquivo de checksums. A verificação criptográfica é um passo adicional documentado pelo projeto.

Esses sinais podem ser conferidos no workflow de CI, na configuração de release e no documento de segurança. Eles mostram disciplina de engenharia; não são certificação de segurança nem garantia de que todos os agentes estejam igualmente bem cobertos.

O que testamos — e o problema de fuso horário encontrado

Para não transformar o texto em reprodução de marketing, compilamos a tag, instalamos o binário estável em um diretório de laboratório e criamos sessões sintéticas de Claude Code e Codex. Nenhuma configuração real dos agentes foi modificada.

A falha foi TestNotesPathAndAppendParse, em notes_test.go. O teste espera que duas notas fiquem no mesmo grupo diário. Porém, seus horários caem em dias diferentes no fuso de São Paulo, e o parser agrupa pelo dia local. O resultado são três grupos onde o teste espera dois. Repetimos o caso em UTC e em São Paulo para confirmar a diferença.

Interpretação: encontramos uma suposição de fuso no teste, não evidência de perda de notas ou de falha geral na indexação. É um exemplo concreto de portabilidade ainda a melhorar. Também seria errado dizer que “a suíte inteira passou”: não executamos todos os testes de todos os pacotes e clientes, nem uma auditoria completa de segurança ou benchmarks de escala.

Veredito: há engenharia suficiente para um piloto sério no desktop, sobretudo como busca local sob demanda. Ainda não classificaria como infraestrutura crítica sem ressalvas: a linha é 0.x, o projeto é recente, os formatos dos agentes mudam e o formato de índice próprio precisa acompanhar essas mudanças. Adote com versão controlada, backups e validação do seu próprio fluxo.

Benchmarks: úteis, mas não um ranking universal

O projeto publica medições de recuperação, indexação e custo de contexto, além de código para reprodução. Isso é melhor do que uma promessa sem método. Ainda assim, os ensaios são produzidos pelo próprio mantenedor; não os tratamos como validação independente nem repetimos seus percentuais como resultado do LinuxPro.

No teste de utilidade “no primeiro dia”, a hipótese favorece justamente o diferencial do Deja Vu: já existe um grande histórico no disco. Uma ferramenta que depende de notas gravadas depois da instalação resolve outro estágio do problema. Compare corpus, máquina, preparação dos concorrentes, versão e critério de sucesso antes de declarar um vencedor.

A pergunta prática é: “ele encontra a solução antiga do meu projeto com poucos falsos positivos?”. Separe consultas conhecidas, registre se o trecho certo aparece e meça latência e volume de contexto. O ensaio day zero e o catálogo de benchmarks são pontos de partida, não substitutos dessa avaliação.

Privacidade: local não significa imune a vazamentos

O mecanismo de sanitização remove padrões reconhecidos de credenciais antes da gravação no índice. A implementação examinada sanitiza o texto antes de aplicar seu limite de tamanho, evitando que um corte no meio de um segredo atrapalhe uma regra de detecção. É uma defesa concreta, não uma garantia universal.

• Transcripts originais: podem continuar contendo a credencial. Construir o índice não apaga o histórico de origem.
• Dados pessoais e código proprietário: não viram conteúdo público só porque um token foi mascarado. Trate o índice como sensível.
• Disco: o Deja Vu não fornece criptografia em repouso nem é um sistema de controle de acesso. Proteja usuário, permissões, backups e volume.
• Agente remoto: se um agente que usa um modelo em nuvem consultar o MCP, o trecho recuperado pode entrar no contexto enviado àquele provedor. Busca local não torna o restante da cadeia local.
• Exportação e sincronização: revise o destino e o material compartilhado. Uma cópia importada por outra máquina não é revogada automaticamente quando você a remove aqui.

Consulte o modelo de segurança antes de indexar históricos de clientes ou ambientes regulados.

Excluir projetos e reduzir rede

mkdir -p "$HOME/.config/deja"

# Edite ANTES da primeira indexação: um projeto/padrão por linha.
# Também aceita nomes de fontes, por exemplo: harness:opencode
${EDITOR:-vi} "$HOME/.config/deja/exclude"

# Se mudou exclusões depois de indexar, reconstrua o índice.
deja index --rebuild

# Desliga verificações automáticas de versão; não é firewall.
export DEJA_OFFLINE=1

# Relatório de credenciais reconhecidas nos históricos, sem seus valores.
deja secrets

Na configuração padrão, adicionar uma exclusão não elimina imediatamente todo conteúdo que já estava indexado: a reconstrução é importante. deja forget remove sessões e mantém tombstones para evitar reingestão. Veja deja help forget antes de usá-lo.

Não execute deja secrets --scrub como rotina de diagnóstico: esse modo modifica os transcripts suportados e guarda uma cópia original, que também pode conter segredos. É uma operação de escrita a avaliar separadamente. Nunca desabilite sanitização em históricos sensíveis.

Memória recuperada não é instrução

Um transcript pode conter comandos errados, decisões rejeitadas ou uma instrução maliciosa copiada de uma página. O projeto enquadra parte do recall voltado a agentes como histórico não confiável, mas o enquadramento não elimina prompt injection. Não execute um comando só porque apareceu na memória; confira o estado atual do repositório e a autorização do usuário.

Embeddings, sincronização e recuperação de sessões

O caminho lexical padrão não precisa de modelo. deja embed acrescenta um índice semântico auxiliar usando o endpoint de embeddings que você configurar. Com Ollama local, o processamento pode continuar na máquina; com endpoint externo, textos e consultas podem sair dela. Leia deja help embed antes de ativar. Para entender a base local, veja nosso guia do Ollama no Linux.

deja sync oferece exportação, importação e sincronização por SSH. É diferente de colocar arquivos de um índice em uso dentro de uma pasta sincronizada e esperar consistência. Siga o protocolo da ferramenta e proteja o host de destino; comece com deja help sync.

O índice pode manter sessões que o agente apagou depois. Isso é útil na recuperação, mas muda a expectativa de retenção: apagar uma conversa no aplicativo não implica apagá-la do Deja Vu. A TUI tem uma área de sessões removidas pelo agente, e deja resume oferece caminhos de retomada conforme o cliente. Já deja restore recupera trechos substituídos sem sobrescrever automaticamente o arquivo original.

Backup continua indispensável: preserve históricos de origem quando necessário, notas, exclusões, políticas e configurações. Não confunda “índice reconstruível” com “nenhuma perda possível”: um registro retido cuja origem já desapareceu não será recuperado novamente do nada.

Deja Vu, Engram, ai-memory ou grafo de código?

Não são categorias perfeitamente exclusivas: o Deja Vu também tem notas e handoff; outros projetos também podem importar informações. A diferença é o ponto de partida e a operação cotidiana. Consulte o comparativo completo para outras opções e a evolução do ai-memory para o fluxo de wiki.

Problemas comuns e como desfazer a integração

• deja: command not found: confira ~/.local/bin, GOBIN e o PATH. Instalar e configurar os agentes são passos separados.
• Uma fonte ficou vazia: rode deja sources e deja doctor; confira perfil, diretório do agente, exclusões e utilitários ausentes.
• Busca não encontra o que você lembra: use um termo literal do erro, amplie o período e confira o projeto. O histórico pode ter sido apagado antes da primeira indexação.
• MCP configurado, mas agente não lembra sozinho: carregar a ferramenta não implica auto-recall. Reinicie a sessão e confira o modo de instalação.
• Primeira execução após upgrade demora: mudanças de formato podem exigir reconstrução. A release 0.22.1 avisa explicitamente sobre isso.
• Testes de notas falham no seu fuso: reproduza o caso isolado; UTC é uma comparação diagnóstica, não motivo para ocultar a falha original.

# Diagnóstico mais detalhado
deja doctor --deep

# Remove a integração de todos os alvos instalados pelo Deja Vu.
deja uninstall --all

Desinstalar a integração não é sinônimo de apagar notas, índice e todos os backups. Decida a retenção desses dados separadamente e consulte a ajuda da versão instalada. Não remova ~/.claude ou ~/.codex para “limpar o Deja Vu”: esses diretórios pertencem aos próprios agentes.

Vale a pena?

Sim, para quem alterna agentes e já acumulou histórico local. A facilidade mais convincente é começar encontrando trabalho antigo, não esperar a próxima semana para a memória ficar útil. CLI, TUI e integração seletiva permitem experimentar sem transformar a máquina inteira de uma vez.

O código mostra testes, organização e preocupação real com integridade e segredos, mas a ferramenta ainda é jovem. Nosso piloto funcionou e também revelou uma suposição de fuso em um teste. A recomendação é começar sob demanda, medir o ganho no próprio projeto e só depois habilitar automação. Memória boa reduz investigação repetida; não substitui Git, documentação e revisão.