chat-recall

chatrecall.dev · Como funciona · Ferramentas MCP · Preços · Self-host · Segurança

Uma única memória em todas as ferramentas de codificação por IA que você usa. Claude Code, Gemini CLI, Codex, OpenCode, Antigravity e Cursor compartilham um único histórico pesquisável — e o agente pode pesquisá-lo por conta própria.

Seus agentes de codificação guardam cada um seus próprios registros, em seu próprio formato, em seu próprio diretório, e nenhum deles consegue ler o do outro. O chat-recall indexa todos eles em um só lugar, remove segredos no caminho e expõe o resultado ao seu agente por meio de 61 ferramentas MCP, para que ele possa lembrar do próprio trabalho passado em vez de você precisar explicar tudo de novo.

Essa parte entre ferramentas é o ponto central. O histórico embutido de uma única ferramenta para na própria fronteira dela; este não para.

Veja funcionando

Cada tela abaixo é uma chamada MCP real contra um servidor real — a ferramenta e os argumentos exatos são mostrados acima de cada resposta. Nada é simulado, reproduzido ou re-temporizado.

Uma memória, todas as ferramentas. Aqui o OpenCode é questionado sobre uma sessão do Claude Code: uma ferramenta diferente, um formato de registro diferente, um único índice.

Ou simplesmente pergunte em português claro — sem nomes de ferramentas, sem IDs de sessão. O agente escolhe a chamada sozinho:

Ele também encontra as credenciais que você colou e verifica quais ainda funcionam. Uma chave morta é higiene. Uma viva é um incidente, e apenas as vivas geram alerta.

Instalação

npx chat-recall init

Isso indexa os registros já presentes no seu disco, detecta quais ferramentas de IA você tem e registra o servidor MCP na configuração de cada uma delas:

Ferramenta	Arquivo que ela grava
Claude Code	~/.mcp.json
Codex	~/.codex/config.toml
Gemini CLI	~/.gemini/settings.json
OpenCode	~/.config/opencode/opencode.json
Cursor	~/.cursor/mcp.json

Ele só toca na configuração de uma ferramenta que esteja nesta máquina, nunca sobrescreve uma entrada que você ajustou manualmente, e o chat-recall doctor imprime uma linha por ferramenta para que um registro ausente fique visível. Dentro do Claude Code, você pode instalar as skills e o servidor MCP juntos:

/plugin marketplace add munhq/chat-recall
/plugin install chat-recall@chat-recall

Depois:

chat-recall search "that auth bug"      # search everything you have ever done
chat-recall recent                      # what was I working on

Por padrão, isso sincroniza com o servidor hospedado em chatrecall.dev, que começa com um teste de 7 dias sem necessidade de cartão e vira assinatura paga depois — veja preços. Para manter tudo na sua própria máquina, execute o servidor você mesmo: é gratuito para uma pessoa, para sempre, com todos os recursos e sem chave de licença — incluindo o quadro de tarefas e o Toolkit — e a licença só compra colaboração: um segundo membro, histórico compartilhado, atribuição de trabalho. Veja Self-host abaixo. De qualquer forma, o CLI é o mesmo binário e os mesmos comandos; só muda a URL do servidor.

Nenhuma chave de API é necessária. A busca é full-text do Postgres. Os resumos de IA são um upgrade opcional, não um pré-requisito.

O que nunca sai da sua máquina

Ele indexa todas as sessões de IA neste disco, então o init mostra o que seria enviado — contagem, ferramentas e os projetos por nome — e espera um "sim" antes da primeira sincronização. (O --yes, ou sem TTY, imprime o mesmo resumo e prossegue; o --skip-sync segura o envio completamente.) Segredos são mascarados no lado do cliente e os caminhos de projeto são enviados como hashes; além disso, você escolhe o que está no escopo:

chat-recall exclude project ~/work/client   # a path, and everything under it, never syncs
chat-recall exclude tool cursor             # one AI tool never syncs
chat-recall sync-only add git:github.com/me/app   # invert it: ship ONLY what you list
chat-recall sources decline ~/.claude-work  # a whole transcript profile stays out
                                            #   (--delete-remote purges what it already sent)
chat-recall exclude list                    # every rule in force
chat-recall delete <session-id>             # purge one session on every server, tombstoned
chat-recall retention                       # how long the server keeps what you sent
chat-recall retention set 90                # delete anything older, on a timer (0 = keep everything)

Algumas ferramentas arquivam registros sob um hash em vez de uma pasta de projeto, então essas sessões não têm caminho para uma regra de caminho corresponder; o exclude tool é o controle que cobre esses casos, e o init imprime essa contagem. Uma janela de retenção exclui do servidor por temporizador. O retention set imprime quantas sessões seriam removidas e pede que você confirme o número. Só é desfeito se o registro original ainda estiver em uma máquina sua — amplie a janela e o chat-recall sync --full reenvia o que ele admite. Para um laptop que você não tem mais, histórico que sua ferramenta de IA rotacionou ou arquivos que você apagou, nossa cópia é a única cópia. Exporte antes se quiser uma.

As exclusões ficam na máquina que detém os dados, então o CLI é dono delas; elas valem a partir da próxima sincronização, e linhas já sincronizadas permanecem até serem excluídas. O painel Sync rules adiciona regras em todos os dispositivos — unidas às locais, então só pode adicionar proteção. Modelo completo, com limites: Segurança.

Quatro coisas que ele realmente faz

1. Memória unificada entre ferramentas. Um índice, uma busca, uma interface sobre Claude Code (~/.claude/projects/), Gemini CLI (~/.gemini/tmp/), Codex (~/.codex/), OpenCode (~/.local/share/opencode/), Antigravity e Cursor (~/.cursor/ para o CLI, ~/.config/Cursor/ para a IDE). Sessões, planos, tarefas, arquivos CLAUDE.md, cache de colagem, histórico de shell e diários de agente compartilham uma única interface MemorySource plugável.
2. O agente lembra sozinho. 61 ferramentas MCP, para o Claude Code poder recall_smart_resume, recall_search (com like_session para encontrar trabalho semelhante), recall_edits_timeline, recall_subagent_search e recall_redundant_files em vez de perguntar o que aconteceu da última vez. Ele também grava de volta, via recall_decision_record, recall_kg_add e recall_set.
3. Avisa antes de você refazer trabalho. Um hook UserPromptSubmit busca sessões passadas semelhantes a cada prompt e injeta uma nota curta "você já fez isso antes, na sessão X" no contexto do agente.
4. Grafo de conhecimento temporal. Decisões e menções a ferramentas viram triplas entidade-relacionamento com janelas valid_from/valid_to, para você perguntar o que foi decidido em março e se ainda vale.

Adicione sua própria ferramenta de IA

Um novo backend é um arquivo e uma linha — sem mudanças no motor. Se uma ferramenta que você usa grava registros em disco, ela pode ser indexada aqui, e um pull request é o caminho mais rápido para isso.

Opcional: painel web

O painel React faz parte do servidor (SaaS ou docker compose self-host) — o CLI em si não tem interface. Para desenvolvimento do painel:

npm run web:install                 # install web deps
npm run web:dev                     # API on :5000, UI on :5174

Self-host do servidor (docker compose)

Tudo na sua própria máquina, sem conta, sem enviar nada para lugar nenhum:

git clone https://github.com/munhq/chat-recall && cd chat-recall
echo "ADMIN_KEY=$(openssl rand -hex 24)"         >> .env
echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)" >> .env
docker compose up -d --build          # FIRST RUN BUILDS FROM SOURCE (minutes)

Depois, gere um token de dispositivo e conecte uma máquina — a sequência completa, com solução de problemas, está em docs/SELF_HOSTING.md.

Dois contêineres: o servidor mais um Postgres pgvector/pgvector embutido, então um docker compose up simples é autocontido. Traga seu próprio Postgres também é suportado (é assim que o serviço hospedado roda): defina DATABASE_URL para um Postgres 16+ externo.

Mantenha o índice ativo (+ sincronização opcional com o servidor)

Você não precisa de um daemon. O Claude Code inicia o servidor MCP, e esse processo sincroniza a cada 3 minutos sozinho — o binário é o daemon. Para uma máquina headless sem assistente rodando, opte por um serviço em segundo plano:

chat-recall watch                    # foreground daemon: watches every tool, summaries, precompute
chat-recall watch --install-service  # systemd user unit (Linux) · launchd (macOS) · Scheduled Task (Windows)

O init não instala isso, de propósito. Ambos os caminhos passam pelo mesmo syncIncremental() sob o mesmo lock de índice entre plataformas, então um escritor toca o ledger por vez — veja docs/SYNC.md antes de mudar qualquer coisa. Segredos são mascarados no lado do cliente antes de qualquer coisa sair da máquina. O chat-recall sync faz o mesmo push uma vez, sob demanda.

Conecte ao Claude Code

O chat-recall init faz isso por você. Equivalente manual em ~/.mcp.json:

{
  "mcpServers": {
    "chat-recall": {
      "command": "chat-recall-mcp"
    }
  }
}

Depois instale os hooks (um comando configura auto-save, backup pré-compactação e a dica de retomada que avisa quando você está prestes a refazer trabalho):

chat-recall install-hooks                 # registers all five events, in every Claude profile
chat-recall install-hooks --no-resume-hint  # skip the resume warning
chat-recall install-hooks --no-wakeup       # skip the session-start wake-up bundle
chat-recall install-hooks --no-escalate     # skip the session-end escalation
chat-recall install-hooks --uninstall     # remove all of ours, leave third-party hooks alone

Hook	Quando dispara	O que faz
SessionStart	Nova sessão (startup / clear)	Injeta o pacote de ativação com escopo de projeto
UserPromptSubmit	Quando você digita um prompt	Busca sessões passadas; se existir uma semelhante, injeta "você já trabalhou nisso antes" no contexto do agente
Stop	Após cada turno do assistente	Auto-salva tópicos, decisões e ferramentas em ~/.chat-recall/memory/
PreCompact	Antes do Claude Code compactar o contexto	Salvamento de emergência para nada se perder na compactação
SessionEnd	Quando a sessão fecha	Escala os aprendizados da sessão em segundo plano, sem atrasos

Companheiro: codeindex (auto-detectado)

Existe um servidor MCP separado chamado codeindex (binário Zig, ~56 MB) do munhq que dá ao agente consulta em nível de código. Os dois se complementam:

• chat-recall = memória de sessão. No que trabalhei? O que decidimos?
• codeindex = memória de código. Onde está esse símbolo? Quem o chama? O que quebra se eu mudar?

Juntos, o agente consegue responder "já construí isso antes?" e "isso já existe neste codebase?" antes de refazer trabalho.

Como o chat-recall lida com isso: o chat-recall init detecta se o codeindex está no seu PATH (ou em ~/.local/bin/codeindex). Se sim, registra-o como servidor MCP no ~/.mcp.json automaticamente — sem download, sem surpresa. Se não, imprime uma dica de uma linha sobre como obtê-lo.

chat-recall init                       # default — detect and register if installed
chat-recall init --with-codeindex      # additionally force-download the binary
chat-recall init --skip-codeindex      # don't even check
chat-recall companions install         # download manually (after init)
chat-recall companions status          # show what was detected
chat-recall companions uninstall       # remove the binary + MCP registration

O codeindex é open source (MIT) em github.com/munhq/codeindex. A instalação é opcional — o chat-recall funciona totalmente sem ele; você só não tem as ferramentas de nível de código.

O que é indexado

Fonte	Origem	Notas
Sessões (Claude)	~/.claude/projects/<hash>/<uuid>.jsonl	Registros completos, tokens, custo, arquivos tocados, modelos usados
Sessões (Gemini CLI)	~/.gemini/tmp/*/chats/*.json	Tokens e uso de ferramentas extraídos quando presentes
Sessões (OpenCode)	~/.local/share/opencode/opencode.db (SQLite)	Custo, tokens, todos
Registros de subagentes	<session-dir>/<id>/subagents/*.jsonl	Explore, aside, e acompact-* (histórico compactado órfão)
Planos	~/.claude/plans/*.md	Documentos de planejamento do agente, divididos por ##
Tarefas	~/.claude/tasks/<session>/*.json	Vinculadas à sessão pai
CLAUDE.md	Auto-descoberto a partir de hashes de projeto	Vinculado a sessões no mesmo projeto
Histórico	~/.claude/history.jsonl	Histórico de shell, opcionalmente vinculado a uma sessão
Colagem	~/.claude/paste-cache/*.txt	Blocos grandes colados
Diário	~/.chat-recall/index/diary/<agent>/*.json	O que o agente contou ao seu eu futuro via recall_diary_write

Ferramentas MCP (61, incluindo 4 ferramentas de inteligência de código que se registram quando o binário companheiro está instalado)

Busca e recuperação — recall_search, recall_memory_search, recall_recent, recall_show, recall_context, recall_summary, recall_smart_resume, recall_project_context, recall_weekly_digest, recall_analytics_summary, recall_wake_up.

Detecção de padrões — recall_search com like_session: <id> (encontra trabalho semelhante a uma sessão dada), recall_redundant_files (avisa quando um novo nome de arquivo sobrepõe trabalho anterior), recall_diff com files_only: true (quais arquivos a sessão X realmente tocou), recall_edits_timeline com group_by: "session" (quais sessões editaram auth.rs).

Subagentes e filtros — recall_subagent_search (busca dentro de registros ocultos Explore/aside/compact), recall_user_prompts (apenas o que o humano digitou, sem banners).

Descobertas, ranqueadas — recall_claude_suggestions (toda descoberta que vira mudança de instrução do agente: as regras de CLAUDE.md e instalações de skill, mescladas no escopo da conta e de cada projeto indexado) e recall_improvements (todo o resto, ranqueado do mais urgente para o menos, com create_tasks: true para abrir uma tarefa de equipe por item). Elas particionam os mesmos motores de recomendação, então um item nunca aparece nas duas.

Grafo de conhecimento — recall_kg_query, recall_kg_add, recall_kg_invalidate, recall_kg_timeline, recall_kg_stats. Mais recall_decision_record para gravar uma decisão como tripla e entrada de diário em uma única chamada.

Estado KV — recall_set, recall_get (sem chave = lista o escopo). Valores persistentes pequenos, chaveados por strings com namespace: "URL do PR atual", "branch em que estou trabalhando", preferências do usuário. Diário e status — recall_diary_write, recall_diary_read, recall_status (inclui detalhamento de memória), recall_index. Planos/tarefas: pesquise via recall_memory_search(source_types:['plan','task']), leia via recall_show.

Removendo coisas — recall_forget exclui permanentemente uma conversa do servidor, com tombstone para que nenhuma sincronização posterior a restaure (seu próprio arquivo de transcrição permanece intacto); recall_exclude_path interrompe a sincronização de um caminho, nesta máquina e na sua conta. Eles existem como ferramentas porque "esqueça essa conversa" e "pare de sincronizar este repositório" são coisas que as pessoas dizem no meio de uma conversa, não coisas para as quais abrem um painel. Ambos exigem confirm: true, ambos são anotados como destrutivos, e nenhum é aprovado automaticamente — seu cliente pergunta toda vez. O limite é unilateral de propósito: um agente pode restringir o que é armazenado e não há ferramenta que o amplie novamente (sem des-exclusão, sem lista de permissões, sem retenção). Ampliar é com você: chat-recall exclude remove, ou o painel.

Quando o companheiro codeindex está instalado, o agente também recebe 16 ferramentas de nível de código (find_symbol, find_callers, get_imports, plan_change, get_change_impact, analyze, etc.) de um servidor MCP separado. Elas se compõem: chat-recall encontra o que você fez; codeindex informa o que existe atualmente.

Arquitetura de busca

A busca é executada no servidor, e é busca de texto completo do Postgres: correspondência de palavras-chave com classificação, além de tolerância a erros de digitação pg_trgm. Não precisa de embedder, nem de chave de API, nem de serviço extra.

O CLI envia chunks redigidos ao servidor, que os indexa.

Rastreamento de custos

O custo em USD é calculado a partir do uso de tokens quando pelo menos um modelo na sessão tem uma tarifa que o servidor conhece. Para todos os outros modelos — qualquer coisa local, qualquer coisa auto-hospedada, qualquer coisa mais nova que a tabela de tarifas — o painel mostra — em vez de inventar um número. O resumo exibe um contador de sessionsWithoutPricing, para que você veja quanto do total o valor realmente cobre.

Contexto de retomada

chat-recall memory wake-up

Cria um pequeno pacote para uma sessão de IA: texto opcional de identidade, os 10 principais chunks que o classificador marcou como decisões/preferências/marcos com importância ≥ 4, e um instantâneo dos fatos atualmente válidos do grafo de conhecimento. Sem compressão mágica — apenas os itens de maior sinal que o indexador já etiqueta.

Locais de dados

O CLI mantém quase nada localmente — apenas o necessário para alcançar o servidor:

Caminho	O quê
~/.chat-recall/credentials.json	Alvo(s) do servidor + token do dispositivo (modo 0600)
~/.chat-recall/sync-ledger.json	Marca d'água de sincronização por servidor (o que já foi enviado)
~/.chat-recall/hooks/	Hooks instalados (após install-hooks)
~/.chat-recall/index/diary/	Diários de agente escritos por recall_diary_write
~/.chat-recall/shadow/	Cópia compactada com gzip da transcrição mais completa vista por sessão, para que uma truncagem --resume a montante não possa destruir o histórico
~/.chat-recall/cache.db	Cache local de resultados/metadados para o painel local. Não é um índice, e não é usado no modo servidor

Todo o conteúdo indexado — chunks, FTS, vetores, grafo de conhecimento, descobertas de segredos, diário — vive no servidor (Postgres para auto-hospedagem e SaaS). Redefina-o apagando os dados do Postgres do servidor, não qualquer coisa sob ~/.chat-recall.

Privacidade

Suas sessões sincronizam com um servidor chat-recall — seja um que você auto-hospeda (sua própria máquina, seu próprio Postgres) ou o SaaS. Antes de qualquer coisa sair do CLI, ela é redigida: segredos são mascarados no lado do cliente, então o servidor nunca recebe credenciais brutas. A auto-hospedagem mantém todos os dados em infraestrutura que você controla; o SaaS é a alternativa hospedada.

Sem telemetria. Seus dados vivem no Postgres do seu servidor — faça backup como quiser. No SaaS, eles vivem no Postgres hospedado; auto-hospede se preferir manter tudo inteiramente na sua própria infraestrutura.

Arquitetura

packages/
├── engine/src/
│   ├── core/
│   │   ├── backends/        ToolBackend per AI tool (claude, gemini, opencode, codex, agy)
│   │   ├── tool-backend.ts  Registry interface — single source of truth for tool identity
│   │   ├── tool-paths.ts    Env-overridable default paths for each tool
│   │   ├── generic-engine.ts  Shared turn extraction / edit scan / replay (canonical events)
│   │   └── …                Indexing, storage, embeddings, summaries, KG, classifier
│   └── parsers/             *-source.ts plugins per content type (sessions, plans, tasks, …)
├── cli/
│   ├── src/cli.ts           CLI
│   ├── src/mcp.ts           MCP server
│   ├── auto-indexer/        chokidar-based watcher daemon (systemd-friendly)
│   └── hooks/               Claude Code hooks (install via `chat-recall install-hooks`)
└── server/
    ├── src/                 Express API
    ├── client/              React + Vite UI — the dashboard
    └── cloud/migrations/    Empty by design — pg-schema.ts owns the schema

docker/                  Dockerfile + entrypoint for the server image
e2e/                     Playwright tests for the dashboard

Dois pontos de extensão, ambos orientados por registro:

• Adicionar um novo tipo de conteúdo (ex.: outro formato de arquivo para indexar) — implemente MemorySource (discover → parse → extractLinks) e registre-o no SourceRegistry.
• Adicionar uma nova ferramenta de IA (um sétimo backend ao lado de Claude/Gemini/OpenCode/Codex/Antigravity/Cursor) — implemente ToolBackend (caminhos, manipulação de ID, readEvents, fileToolMap, extractEditDelta) e registre-o em packages/engine/src/core/backends/index.ts. Todos os caminhos podem ser sobrescritos por variáveis de ambiente via CHAT_RECALL_{CLAUDE,GEMINI,CODEX,AGY,CURSOR,CURSOR_IDE}_HOME / CHAT_RECALL_OPENCODE_DB.

Requisitos

• Node.js 22 ou posterior. A imagem Docker e o CI executam a versão 24.
• Sessões escritas por uma ferramenta suportada, em seu local padrão: ~/.claude/, ~/.codex/, ~/.local/share/opencode/, ~/.gemini/.

Essa é a lista completa. Nenhuma chave de API é necessária para instalar, indexar ou pesquisar.

Um recurso é opcional, e precisa de um backend que você escolhe:

Recurso	Backends para os quais você pode apontá-lo
Resumos de IA	Ollama, um CLI no qual você já está conectado (SUMMARY_CLI_CMD), um endpoint compatível com OpenAI, ou ANTHROPIC_API_KEY

Sem ele, as sessões não carregam resumo gerado. Todo o resto funciona igual.

Licença

Elastic License 2.0 para todo o repositório.

Em termos simples: use, modifique, execute para você mesmo ou dentro da sua empresa, gratuitamente e sem pedir permissão. A única coisa que você não pode fazer é oferecê-lo a terceiros como um serviço hospedado ou gerenciado — isso é o produto. Você também não pode remover as verificações de chave de licença ou os avisos de direitos autorais.

É código-fonte disponível, não open source OSI, e este README não vai fingir o contrário. Ele substituiu uma divisão onde o CLI e o motor eram MIT e o servidor era BSL 1.1, o que respondia "posso usar isso?" de três maneiras diferentes dentro de um único repositório.