Seus agentes de código param de depurar de novo o que você já resolveu.
Claude Code, Codex, Cursor e os demais agentes desta máquina já salvam cada sessão em disco.
O deja indexa tudo, inclusive meses atrás, e entrega a parte que importa
ao agente que está trabalhando agora.
```sh
curl -fsSL https://raw.githubusercontent.com/vshulcz/deja-vu/main/install.sh | sh
deja install --auto
```
Recall 97.2% R@5 no LongMemEval-S todas as 500 perguntas · MemPalace 96.6%, agentmemory 95.2% mesmas 19,195 sessões: 19/100 em primeiro lugar, a seguinte 14
Tokens metade dos tokens do agentmemory 53,558 contra 104,974 numa tarefa já resolvida 477 tokens de definições de ferramentas, a menor de sete
Indexação 13.6 s para indexar 19,195 sessões a seguinte de sete: 72 s 26 ms até a primeira resposta, mediana de busca de 97 ms
## Instalação
```sh
curl -fsSL https://raw.githubusercontent.com/vshulcz/deja-vu/main/install.sh | sh
deja install --auto
```
O script coloca o binário em `~/.local/bin`. Se esse diretório ainda não estiver no seu `PATH`, o mesmo shell não encontra o segundo comando: rode a linha `next:` que o script imprime, com o caminho completo, ou abra um novo shell depois que a linha do `PATH` for adicionada.
Se o `raw.githubusercontent.com` não estiver acessível, existe um espelho no npm com a mesma versão:
```sh
npm i -g @vshulcz/deja-vu --registry=https://registry.npmmirror.com
deja install --auto
```
Dez segundos para instalar, uns dez para indexar. O segundo comando conecta o recall via MCP em cada agente que
encontrar, liga o recall no início da sessão onde o agente suporta isso, e monta o primeiro índice, para que a
sessão seguinte não espere nada.
Abra uma sessão nova e pergunte sobre algo de meses atrás:
> a gente já mexeu com jwt refresh rotation antes? procura na sua memória
Nem é preciso perguntar: com o recall automático ligado, o agente já sabe na abertura da sessão o que foi
resolvido neste projeto. Para procurar você mesmo, rode `deja`.
opencode, DeepSeek Harness, Zed, Kimi Code, Codex CLI, Grok Build, OpenClaw, pi e Hermes também têm pacote no próprio
ecossistema, para quem está acostumado a instalar extensões por lá:
```sh
opencode plugin opencode-deja
dsh plugin --profile web add dsh-deja
# Zed: procure deja no painel de extensões
# Kimi Code: /plugins install https://github.com/vshulcz/deja-vu
# Codex CLI: codex plugin marketplace add https://github.com/vshulcz/deja-vu && codex plugin add deja-vu@deja-vu
# Grok Build: grok plugin marketplace add vshulcz/deja-vu && grok plugin install deja
openclaw plugins install clawhub:@vshulcz/openclaw-deja && openclaw config set plugins.entries.deja-vu.hooks.allowConversationAccess true
pi install npm:@vshulcz/pi-deja
hermes plugins install deja-memory
```
O `deja install --auto` já conecta tudo isso, então qualquer um dos dois caminhos basta. Os dois juntos também
não incomodam: cada pacote lê o que o `deja install` escreveu e completa só o que falta, sem registrar
ferramentas em duplicidade nem fazer o recall duas vezes. Detalhes em [`extensions/`](../../extensions).
A mesma busca existe como skill, instalável por qualquer agente que leia `SKILL.md`:
```sh
npx skills add https://github.com/vshulcz/deja-vu --skill deja-search # skills CLI: Claude Code, Cursor, Goose, Copilot…
openclaw skills install @vshulcz/deja-search # ClawHub
hermes skills install vshulcz/deja-vu/skills/deja-search # Hermes
```
O skill chama o binário `deja` que você já instalou; não traz um próprio.
Outros caminhos: `brew install deja-vu`,
`go install github.com/vshulcz/deja-vu/cmd/deja@latest`, ou `npx @vshulcz/deja-vu "consulta"` para
experimentar sem instalar nada. No Windows o script de instalação termina com `unsupported OS` porque é um
script de shell; use `scoop install deja-vu` (está no bucket main do Scoop) ou `winget install vshulcz.deja-vu`, ou pegue `deja-vu__windows_amd64.zip` da
[última release](https://github.com/vshulcz/deja-vu/releases/latest) e coloque `deja.exe` no `PATH`.
Só o binário já é uma instalação completa: indexar, buscar, `show`, `ctx`, `blame`, `--json` e a limpeza de
credenciais não precisam de mais nada. O que o `deja install` faz é plugar o MCP nos seus agentes e ligar o
recall no início da sessão — vale a pena, mas é opcional.
## Pesquise você mesmo
`deja` sem argumentos num terminal abre uma busca no histórico de todos os agentes. Ela começa pelas sessões
por trás da sua mudança ainda não commitada, depois as recentes deste projeto, e a lista vai afunilando
enquanto você digita.
- `↑↓` escolhe uma sessão, `↵` abre no trecho encontrado, `n` e `N` passam pelas ocorrências, `esc` volta. Dentro de uma sessão, `/` procura uma palavra e `]` `[` pulam entre as perguntas que você fez.
- A caixa aceita filtros: um agente com dois-pontos (`codex:`), `today`, `yesterday`, `week`, `month` e `in:`.
- `r` retoma a sessão no agente que a escreveu. `o` continua em qualquer outro agente, que começa com o que a sessão perguntou, decidiu e deixou em aberto.
- `tab` alterna entre este projeto, todos os projetos e Deleted, as sessões que o próprio agente apagou e que o deja ainda guarda; `R` devolve uma ao lugar.
- `?` lista todas as teclas, `^k` tem o resto (copiar o id da sessão ou o caminho do projeto, esquecer uma sessão), na lista, `q` sai; `esc` volta um passo e sai com a caixa de busca vazia.
Com `DEJA_TUI=0` ele imprime o resumo em texto, que também é o `deja brief`. Num pipe, imprime o que está
indexado e qual comando rodar em seguida.
## O que você ganha
**Resolvido no Codex, lembrado pelo Claude.** Quarenta e um agentes de código escrevem cada conversa em
arquivos locais, e o deja transforma esses arquivos numa camada de memória que todos eles conseguem ler.
| | |
| --- | --- |
| **Busca para trás no tempo** | `deja "connection pool exhausted"` varre gigabytes, incluindo tudo o que veio antes de você instalar o deja. Uma pergunta em linguagem natural cai no modo por relevância. Tempo é uma dica, não um filtro. |
| **Recall entre agentes** | A ferramenta MCP `deja` no modo `recall` responde «isso a gente corrigiu três semanas atrás» de dentro de qualquer agente, não importa quem corrigiu na época. |
| **Sobrevive à compactação** | Medido em 43 compactações: o resumo preservou 77% das decisões e 0.2% dos comandos que você rodou. Os 99.8% restantes o deja devolve. No Claude Code e no Codex, o deja anota a tarefa, os arquivos e os comandos no instante em que a compactação começa, e devolve tudo uma vez, logo depois dela. |
| **Recall na hora de agir** | Antes de o agente editar um arquivo ou rodar um comando, o hook `PreToolUse` diz o que já foi decidido sobre aquele arquivo, qual forma daquele comando funciona aqui, ou que o programa simplesmente não existe nesta máquina. Quando um comando falha, o hook `PostToolUse` mostra o que foi rodado depois do mesmo erro nesta máquina — exatamente o par que o agente não vai perguntar. |
| **Indexa o trabalho, não só a conversa** | Cada arquivo aberto em cada turno, cada comando executado com seu código de saída, e o trecho exato que uma edição substituiu. Justamente o que todo resumo perde. |
Além disso: `deja promote --state rejected` marca uma decisão revertida, e daí em diante todo resultado
mostra que aquilo foi tentado e descartado; um resultado avisa que «4 arquivos desta sessão mudaram desde
então» e fica calado quando não tem como saber; `deja sync ssh laptop` move a memória entre máquinas só
acrescentando, sem nuvem no meio; `deja handoff --to codex` empacota o contexto atual para continuar em outro
agente; chaves, tokens, JWT e blocos de chave privada de formatos conhecidos são removidos na indexação — mas
casar padrão não é detectar segredo, e um formato desconhecido pode passar.
### Desenhe o seu próprio trabalho
`deja stats --card` desenha direto no terminal; passe um nome de arquivo e ele escreve um SVG para o README do
seu perfil. Para publicar em outro lugar,
[converta para PNG](https://vshulcz.github.io/deja-vu/card/) — essa página converte no seu próprio navegador.
A referência completa está no [site da documentação](https://vshulcz.github.io/deja-vu/).
## Privacidade
Indexar e buscar são operações locais. Só usam a rede `deja update`, `deja sync ssh`, a checagem de versão
dentro do `deja doctor`, o `deja embed`, que vai ao endpoint que você configurar (e, depois que o sidecar semântico existe, cada busca, que envia a consulta a esse endpoint), e uma olhada diária na
última release a partir de um comando interativo. Essa olhada não envia dados de sessão; `DEJA_OFFLINE=1` ou
`DEJA_NO_UPDATE_NOTICE=1` a desliga.
Credenciais são limpas na indexação: chaves AWS, atribuições `api_key=` e `token=`, tokens bearer e JWT nus,
blocos PEM de chave privada, tokens de vários provedores, URLs no formato `scheme://user:pass@host`, valores de
alta entropia que nenhuma regra cobre, e senhas escritas em prosa — «the admin password is …», onde não há
separador nenhum em que se apoiar. O valor vira `[redacted:]` e o texto ao redor continua pesquisável.
`deja share` e `deja sync export` limpam de novo na exportação. Casar padrão não é detectar segredo: um formato
que as regras não conhecem pode passar do jeito que está — veja o modelo de segurança.
`deja forget` tira sessões do índice reconstruído e deixa uma lápide, então o `deja index` seguinte não
consegue trazê-las de volta do histórico original.
O [modelo de segurança](../../docs/SECURITY-MODEL.md) documenta os fluxos de dados, os limites da limpeza, as
premissas de confiança e a verificação das releases.
## Linha de comando
`deja` sozinho num terminal abre [a tela de busca](#pesquise-você-mesmo). Com uma consulta, ou qualquer comando
abaixo, ele imprime e sai:
```text
$ deja "jwt refresh token"
[claude] api · Jul 8 · 8f31c0a9 — 2 matches
login started failing after refresh token rotation; jwt kid mismatch in tests
fixed by reloading jwks cache after rotateKey and adding a clock-skew test
[codex] web · Jul 1 · b77d91e2 — 1 match
refresh token cookie needed SameSite=Lax in local callback flow
```
| Comando | O que faz |
| --- | --- |
| `deja ` | Busca em todo o histórico. Várias palavras são AND, aspas exigem texto contíguo; sem correspondência exata ele tenta formas da palavra e grafias próximas. |
| `deja` | Num terminal, a busca em tela cheia descrita acima. `deja brief` imprime no lugar o resumo em texto: as sessões de hoje, o que o deja entregou, o trabalho recente e uma busca para experimentar. |
| `deja wip` | O que a última sessão neste diretório estava fazendo: a tarefa, o que ficou decidido, os arquivos em mão, o último comando e se ele falhou. Tudo deduzido dos registros, sem depender de alguém ter anotado. |
| `deja blame [:linha]` | Quais sessões discutiram este arquivo, o que foi decidido e por quê. Com número de linha: o commit que a alterou por último e a sessão que escreveu essa linha ou o texto que esse commit substituiu. |
| `deja files ` | Na direção contrária: quais arquivos o trabalho sobre um assunto realmente mexeu. |
| `deja how ` | Como isso é executado de verdade nesta máquina, com argumentos reais, tirados de comandos que os agentes já rodaram. |
| `deja fix ` | O que foi executado depois do mesmo erro nesta máquina, e depois do quê o erro não voltou. Nunca um merge, um force push nem uma exclusão. |
| `deja friction` | Erros que aparecem em três ou mais sessões diferentes, dizendo de quais ferramentas vieram. |
| `deja ctx ` | Resumo em Markdown do melhor resultado, com o código que ele alterou, pronto para entrar num prompt. |
| `deja resume ` | Reabre a sessão encontrada na ferramenta a que ela pertence. |
| `deja view` | Exporta toda a memória para um único arquivo HTML local. Sem servidor, nada sai da máquina. |
| `deja doctor [--deep]` | Autodiagnóstico; com `--deep` verifica o índice contra os arquivos de origem. |
| `deja mcp` | O servidor MCP por stdio, o mesmo que o `deja install` conecta. |
A referência completa está na [documentação dos comandos](https://vshulcz.github.io/deja-vu/guide/commands.html).
### Ferramentas MCP
O servidor expõe uma única ferramenta, `deja`, e o parâmetro `mode` escolhe a capacidade: `recall`, `context`,
`blame`, `fix`, `how`, `orient`, `remember`, `handoff`. O `deja install` conecta sozinho, então isso só importa se você configurar
um agente à mão. Os seis nomes antigos continuam funcionando nos clientes já conectados.
Uma ferramenta em vez de sete é questão de custo, não de estilo. Um servidor MCP conectado manda as definições
das suas ferramentas em cada requisição, então elas são pagas a cada turno, tenha o agente chamado algo ou não:
477 tokens aqui, contra 8,283 do maior dos sete servidores medidos. O do próprio deja era 828 até o schema ser
reduzido a uma ferramenta com modos.
## Ferramentas suportadas
Com o recall automático ligado, Claude Code e Codex entregam ao deja o registro atual quando a compactação
começa, e o deja guarda o que o resumo está a ponto de perder: a tarefa, as conclusões, os arquivos, no que
cada comando deu, e o que ficou pendente. O hook seguinte da mesma sessão e do mesmo diretório devolve isso de
uma vez, sem passar de 4 KB, com uma linha sobre se o repositório mudou desde então. O `deja stats` conta as
chamadas de ferramenta entre a compactação e a primeira edição, que foi com o que isso se mediu.
Detalhes em [recuperação depois da compactação](../../docs/compaction.md).
Claude Code · Cline · Codex CLI · opencode · aider · Gemini CLI · Cursor · Antigravity ·
Grok Build · Hermes · Goose · Qwen Code · Kimi Code · pi · omp (Oh My Pi) · OpenClaw ·
Copilot CLI · VS Code Copilot Chat · Amp · prime-agent (PrimeIntellect) · Roo Code ·
Continue · Crush · DeepSeek Harness · Cherry Studio · Senpi · gajae-code · Kimchi Coding ·
Command Code · ZCode · CodeWhale · Reasonix · Kiro · Kilo Code · CodeBuddy Code ·
TRAE CLI · Muse Code · Junie · JetBrains AI Assistant · Devin CLI · Windsurf / Devin Desktop · MiniMax Code · Zed.
O que cada um suporta — recall por MCP, recall automático, skills, comandos, resume, handoff — está na
[matriz de recursos do README em inglês](../../README.md#supported-harnesses). Locais de armazenamento customizados
se indicam com variáveis `DEJA_*_ROOT`, e as variáveis de migração de cada ferramenta também são respeitadas.
### Agentes com pacote próprio
O `deja install --auto` conecta estes como qualquer outro, e esse é sempre o caminho mais curto. Além disso
cada um tem um pacote no próprio ecossistema, para quem instala extensões por lá:
| Agente | Pacote | Instalação |
| --- | --- | --- |
| opencode | npm `opencode-deja` | `opencode plugin opencode-deja` |
| DeepSeek Harness | npm `dsh-deja` | `dsh plugin --profile web add dsh-deja` |
| Zed | `deja-context-server` | Zed → Extensions → deja |
| Kimi Code | plugin `deja` | `/plugins install https://github.com/vshulcz/deja-vu` |
| Codex CLI | plugin `deja-vu` | `codex plugin marketplace add https://github.com/vshulcz/deja-vu`, depois `codex plugin add deja-vu@deja-vu` |
| Grok Build | plugin `deja` | `grok plugin marketplace add vshulcz/deja-vu`, depois `grok plugin install deja` |
| OpenClaw | ClawHub e npm `@vshulcz/openclaw-deja` | `openclaw plugins install clawhub:@vshulcz/openclaw-deja` |
| pi (e omp) | npm `@vshulcz/pi-deja` | `pi install npm:@vshulcz/pi-deja` |
| Hermes | provedor de memória `deja-memory`, no catálogo de plugins do Hermes | `hermes plugins install deja-memory`, ou do GitHub: `hermes plugins install vshulcz/deja-vu/extensions/hermes` |
Qualquer um dos dois caminhos basta e os dois juntos não quebram nada: cada pacote lê primeiro o que o
`deja install` deixou escrito. opencode, dsh e OpenClaw só completam o que falta; Kimi, Grok, Codex e pi saem
de cena se o instalador já conectou; no Zed os dois lados usam o mesmo id de servidor. Então a ordem de
instalação não importa.
Todos usam o deja que você já instalou; a cópia dentro do pacote é só o plano B.
## Recall semântico, opcional
Aponte o `deja embed` para um Ollama local, LM Studio ou qualquer endpoint compatível com OpenAI via
`DEJA_EMBED_URL` e perguntar com outras palavras também acerta. Sem runtime disponível, a busca léxica e o
recall por MCP funcionam como sempre.
## Evidência
58% menos tokens numa tarefa que esta máquina já havia resolvido · 88.9% hit@1 no LongMemEval-S (conjunto limpo de 470 perguntas) · 71.9% no LoCoMo · consultas em milissegundos sobre gigabytes de histórico Onze execuções por braço: 53,558 tokens contra 126,222 sem nada conectado, e 52,815 contra 103,443 numa versão posterior, de novo onze execuções ·
quanto custa terminar uma tarefa ·
os dois harnesses de recuperação estão neste repositório e rodam sobre datasets públicos em minutos ·
confira os números você mesmo
