Espejo comentado · Vectorize · licencia MIT
Memoria para agentes que aprende
El agente guarda lo que vivió, busca de cuatro maneras y reúne lo que aprendió en creencias con respaldo. Corre en tu máquina.
El agente guarda lo que vivió, busca de cuatro maneras y reúne lo que aprendió en creencias con respaldo. Corre en tu máquina.
Hindsight es un sistema de memoria de largo plazo para agentes de IA, creado por Vectorize y abierto bajo licencia MIT. Sirve para quien arma agentes, bots o asistentes que necesitan recordar conversaciones y decisiones de una sesión a otra. En lugar de solo guardar el historial, extrae hechos, junta los repetidos y forma creencias con respaldo, y así el agente aprende con el tiempo. Para usarlo, necesitas Python 3.11 o Docker y un modelo de lenguaje, que puede ser tu suscripción de Claude, de Codex o un modelo local.
Solo llamas a tres cosas: guardar, buscar y reflexionar. El resto (hechos, entidades, fechas, consolidación) ocurre por debajo.
retain extrae hechos con un modelo de lenguaje; recall busca por sentido, palabra exacta, grafo de entidades y período; reflect analiza lo que está guardado y responde preguntas que requieren razonamiento.
Hechos parecidos se vuelven observaciones, con cita del respaldo y conteo de confirmaciones. Los modelos mentales son respuestas fijas ("¿cuáles son las preferencias del usuario?") que él reescribe solo a medida que aprende.
Cada banco es una memoria aislada: uno por usuario, cliente, agente o proyecto, sin filtraciones entre ellos. Opcionalmente bloquea claves y datos personales antes de guardar.
Cada retain pasa por un modelo de lenguaje. Después, en segundo plano, el banco se consolida.
"La estufa calienta." Lo que es verdad sobre el mundo del agente.
"Toqué la estufa y me quemé." Lo que vivió el propio agente.
Creencias consolidadas a partir de muchos hechos, refinadas (no sobrescritas) cuando llega evidencia nueva.
Páginas de conocimiento que el banco escribe sobre sí mismo y mantiene actualizadas. Leer una es solo una consulta a la base de datos, sin llamar al modelo.
Búsqueda en cuatro frentes. El recall ejecuta al mismo tiempo búsqueda semántica (vectores), por palabra exacta (BM25), por grafo (entidades, tiempo, causa) y por período, junta todo y reordena con un modelo de reordenamiento antes de ajustarlo al límite de tokens.
La base de datos viene integrada (PostgreSQL pg0) y los vectores se calculan localmente. El único recurso externo es el modelo de lenguaje.
El modo integrado se instala con pip o corre sin instalar con uvx.
python3 --version uvx hindsight-embed --help
Sin clave de API: claude-code (suscripción Claude Pro/Max), openai-codex (ChatGPT Plus/Pro) u ollama local. También acepta más de 25 proveedores por clave.
claude auth status # ¿ya iniciaste sesión?
En la primera ejecución descarga los modelos de vectores y de reordenamiento (1 a 3 minutos). En un servidor compartido, ejecútalo con tope de memoria.
systemd-run --user --scope -p MemoryMax=8G \
hindsight-embed daemon startCamino local, sin servidor y sin clave de API, usando la suscripción de Claude. Comandos tomados del README de hindsight-embed y de la documentación de modelos.
Un proceso en segundo plano arranca solo en el puerto 8888 y se apaga tras 5 minutos inactivo.
pip install hindsight-embed # o: uvx hindsight-embed ...
El modelo de vectores por defecto (bge-small-en) es solo en inglés. Para portugués y español, la propia documentación recomienda BAAI/bge-m3.
hindsight-embed configure \ --env HINDSIGHT_API_LLM_PROVIDER=claude-code \ --env HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL=BAAI/bge-m3
El primer argumento es el banco. Usa un banco por proyecto, cliente o agente.
hindsight-embed memory retain default "El usuario prefiere respuestas cortas y en español" hindsight-embed memory recall default "¿Cómo le gustan las respuestas al usuario?"
Para preguntas que requieren análisis, no solo búsqueda.
hindsight-embed memory reflect default "¿Qué patrones aparecen en las preferencias del usuario?" hindsight-embed bank list # bancos existentes hindsight-embed daemon logs -n 100 # lo que hizo el proceso
El plugin busca memorias en cada prompt y guarda la conversación después de cada respuesta, mediante ganchos (hooks). También trae herramientas MCP para páginas de conocimiento.
claude plugin marketplace add vectorize-io/hindsight claude plugin install hindsight-memory export HINDSIGHT_LLM_PROVIDER=claude-code
Tres ganchos: calienta el servidor al abrir, busca memorias en cada pedido y guarda al terminar. Requiere Codex 0.116 o más reciente. Lee el script antes de ejecutarlo.
curl -fsSL https://hindsight.vectorize.io/get-codex -o get-codex.sh less get-codex.sh && bash get-codex.sh
Cliente Python (también hay Node.js, Go y CLI) apuntando al servidor local.
from hindsight_client import Hindsight client = Hindsight(base_url="http://localhost:8888") client.retain(bank_id="cliente-42", content="Pidió presupuesto de 3 salas") client.recall(bank_id="cliente-42", query="¿Qué pidió el cliente?") client.reflect(bank_id="cliente-42", query="¿Cuál es el próximo paso con él?")
Antes de conectarlo a todo. Cada retain es una llamada al modelo: guardar cada respuesta de cada sesión consume la cuota de la suscripción. La documentación advierte que el proveedor claude-code es para uso personal y local (usa el Claude Agent SDK oficial con tu inicio de sesión); para equipo o producción, recomiendan clave de API.
Análisis hecho el 15/10/2026 leyendo el código. Nada de esto se instaló todavía: es el mapa de la adaptación.
| Hoy | Límite actual | Lo que agrega Hindsight |
|---|---|---|
| Memoria en archivos (MEMORY.md + un archivo por hecho) | Manual; el índice crece, los hechos repetidos y viejos se acumulan | Consolida solo, refina creencias con evidencia nueva, entiende fechas |
| Lecciones, FALHAS.md y LIMITES.md | Solo crecen; nadie extrae el patrón | reflect extrae el patrón de los errores repetidos |
| Búsqueda en el historial de sesiones | Solo palabra exacta | Búsqueda por sentido, entidad y período |
| Plugin de memoria actual de Claude Code | A veces falla la conexión | Plugin listo para Claude Code y para Codex |
| Bots y kits de atención | Sin memoria por cliente | Un banco aislado por cliente, con bloqueo de datos sensibles |
| Tema "segundo cerebro" | Conceptual | Base real para guía, curso y demostración |
En orden, cada etapa solo empieza si la anterior demuestra valor.
recall/reflect con la búsqueda actual en preguntas como "¿qué errores repito en video?". Medir el consumo de cuota por retain.