Espelho comentado · Vectorize · licença MIT
Memória para agentes que aprende
O agente guarda o que viveu, busca de quatro jeitos e junta o que aprendeu em crenças com prova. Roda na sua máquina.
O agente guarda o que viveu, busca de quatro jeitos e junta o que aprendeu em crenças com prova. Roda na sua máquina.
O Hindsight é um sistema de memória de longo prazo para agentes de IA, criado pela Vectorize e aberto sob licença MIT. Ele serve para quem monta agentes, bots ou assistentes que precisam lembrar de conversas e decisões de uma sessão para outra. Em vez de só guardar o histórico, ele extrai fatos, junta os repetidos e forma crenças com prova, e assim o agente aprende com o tempo. Para usar, você precisa de Python 3.11 ou Docker e de um modelo de linguagem, que pode ser a sua assinatura do Claude, do Codex ou um modelo local.
Você só chama três coisas: guardar, buscar e refletir. O resto (fatos, entidades, datas, consolidação) acontece por baixo.
retain extrai fatos com um modelo de linguagem; recall busca por sentido, palavra exata, grafo de entidades e período; reflect analisa o que está guardado e responde perguntas que pedem raciocínio.
Fatos parecidos viram observações, com citação da prova e contagem de confirmações. Modelos mentais são respostas fixas ("quais as preferências do usuário?") que ele reescreve sozinho conforme aprende.
Cada banco é uma memória isolada: um por usuário, cliente, agente ou projeto, sem vazamento entre eles. Opcionalmente bloqueia chaves e dados pessoais antes de guardar.
Cada retain passa por um modelo de linguagem. Depois, em segundo plano, o banco se consolida.
"O fogão esquenta." O que é verdade sobre o mundo do agente.
"Encostei no fogão e queimei." O que o próprio agente viveu.
Crenças consolidadas a partir de muitos fatos, refinadas (não sobrescritas) quando chega prova nova.
Páginas de conhecimento que o banco escreve sobre si e mantém atualizadas. Ler uma é só uma consulta ao banco de dados, sem chamar o modelo.
Busca em quatro frentes. O recall roda ao mesmo tempo busca semântica (vetores), por palavra exata (BM25), por grafo (entidades, tempo, causa) e por período, junta tudo e reordena com um modelo de reordenação antes de caber no limite de tokens.
O banco de dados vem embutido (PostgreSQL pg0) e os vetores são calculados localmente. O único recurso externo é o modelo de linguagem.
O modo embutido instala pelo pip ou roda sem instalar com uvx.
python3 --version uvx hindsight-embed --help
Sem chave de API: claude-code (assinatura Claude Pro/Max), openai-codex (ChatGPT Plus/Pro) ou ollama local. Também aceita mais de 25 provedores por chave.
claude auth status # já logado?
Na primeira execução ele baixa os modelos de vetores e de reordenação (1 a 3 minutos). Em servidor compartilhado, rode com teto de memória.
systemd-run --user --scope -p MemoryMax=8G \
hindsight-embed daemon startCaminho local, sem servidor e sem chave de API, usando a assinatura do Claude. Comandos tirados do README do hindsight-embed e da documentação de modelos.
Um processo em segundo plano sobe sozinho na porta 8888 e desliga após 5 minutos parado.
pip install hindsight-embed # ou: uvx hindsight-embed ...
O modelo de vetores padrão (bge-small-en) é só em inglês. Para português e espanhol, a própria documentação recomenda o BAAI/bge-m3.
hindsight-embed configure \ --env HINDSIGHT_API_LLM_PROVIDER=claude-code \ --env HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL=BAAI/bge-m3
O primeiro argumento é o banco. Use um banco por projeto, cliente ou agente.
hindsight-embed memory retain default "O usuário prefere respostas curtas e em português" hindsight-embed memory recall default "Como o usuário gosta das respostas?"
Para perguntas que pedem análise, não só busca.
hindsight-embed memory reflect default "Que padrões aparecem nas preferências do usuário?" hindsight-embed bank list # bancos existentes hindsight-embed daemon logs -n 100 # o que o processo fez
O plugin busca memórias a cada prompt e guarda a conversa depois de cada resposta, por ganchos (hooks). Também traz ferramentas MCP para páginas de conhecimento.
claude plugin marketplace add vectorize-io/hindsight claude plugin install hindsight-memory export HINDSIGHT_LLM_PROVIDER=claude-code
Três ganchos: aquece o servidor ao abrir, busca memórias a cada pedido e guarda ao terminar. Exige Codex 0.116 ou mais novo. Leia o script antes de rodar.
curl -fsSL https://hindsight.vectorize.io/get-codex -o get-codex.sh less get-codex.sh && bash get-codex.sh
Cliente Python (também há Node.js, Go e CLI) apontando para o servidor local.
from hindsight_client import Hindsight client = Hindsight(base_url="http://localhost:8888") client.retain(bank_id="cliente-42", content="Pediu orçamento de 3 salas") client.recall(bank_id="cliente-42", query="O que o cliente pediu?") client.reflect(bank_id="cliente-42", query="Qual o próximo passo com ele?")
Antes de ligar em tudo. Cada retain é uma chamada ao modelo: guardar toda resposta de toda sessão consome a cota da assinatura. A documentação avisa que o provedor claude-code é para uso pessoal e local (ele usa o Claude Agent SDK oficial com o seu login); para equipe ou produção, eles recomendam chave de API.
Análise feita em 15/10/2026 lendo o código. Nada disso foi instalado ainda: é o mapa da adaptação.
| Hoje | Limite atual | O que o Hindsight acrescenta |
|---|---|---|
| Memória em arquivos (MEMORY.md + um arquivo por fato) | Manual; o índice cresce, fatos repetidos e velhos se acumulam | Consolida sozinho, refina crenças com prova nova, entende datas |
| Lições, FALHAS.md e LIMITES.md | Só crescem; ninguém tira o padrão | reflect extrai o padrão dos erros repetidos |
| Busca no histórico das sessões | Só palavra exata | Busca por sentido, entidade e período |
| Plugin de memória atual do Claude Code | Falha de conexão às vezes | Plugin pronto para Claude Code e para Codex |
| Bots e kits de atendimento | Sem memória por cliente | Um banco isolado por cliente, com bloqueio de dados sensíveis |
| Assunto "segundo cérebro" | Conceitual | Base real para guia, curso e demonstração |
Em ordem, cada etapa só começa se a anterior provar valor.
recall/reflect com a busca atual em perguntas como "que erros repito em vídeo?". Medir consumo da cota por retain.