Hindsight Starter Guide: añade memoria a largo plazo a tu AI Agent

Uno de los mayores problemas de un AI Agent no es que no sepa responder preguntas, sino que no sea capaz de recordar las cosas realmente importantes del pasado.

En la primera conversación, el usuario puede decirle al Agent:

“Mi proyecto utiliza TypeScript y PostgreSQL, y hemos decidido no usar Prisma.”

En ese momento, el Agent puede entenderlo. Pero al día siguiente, cuando se inicia una nueva Session, si el usuario dice “continúa con el proyecto de ayer”, el Agent puede tener que volver a analizar el código, preguntar de nuevo por el stack tecnológico o incluso repetir decisiones de arquitectura que ya se habían tomado.

Esto demuestra que Context no es lo mismo que Memory.

El Context resuelve la pregunta “¿qué información está disponible ahora?”. La memoria a largo plazo responde a otra cuestión: “¿qué ocurrió en el pasado y qué experiencias merece la pena seguir utilizando en el futuro?”.

El proyecto open source Hindsight, desarrollado por Vectorize, está diseñado precisamente alrededor de este problema: proporcionar un sistema de memoria a largo plazo para AI Agents. Ofrece tres operaciones principales —Retain, Recall y Reflect— que permiten guardar, recuperar y utilizar posteriormente información del pasado.

¿Qué es exactamente Hindsight?

Para empezar, puedes entender Hindsight como una capa de infraestructura entre el Agent y su memoria a largo plazo:

Usuario
 ↓
AI Agent
 ↓
Hindsight
 ├── Retain
 ├── Recall
 └── Reflect
 ↓
Memory Bank

No se limita a introducir las conversaciones en una base de datos.

Cuando el contenido entra en Hindsight, Retain utiliza un LLM para extraer hechos, identificar entidades y establecer relaciones. Esa información se convierte posteriormente en Memory que puede ser recuperada mediante consultas.

Uno de los conceptos más importantes es Memory Bank.

Puedes entender un Memory Bank como un espacio independiente de memoria a largo plazo. Un Bank puede contener recuerdos, documentos, entidades, relaciones y otros datos, mientras que diferentes Banks permanecen aislados entre sí. Durante el primer Retain, Hindsight incluso puede crear automáticamente el Bank correspondiente.

Por ejemplo, puedes separar la memoria por usuario, proyecto o Agent:

alice-memory
project-alpha
customer-123
coding-agent

De esta manera, recuerdos completamente independientes no terminan mezclados.

Primer paso: ejecutar Hindsight

El Quick Start oficial recomienda actualmente utilizar Docker. Hindsight puede ejecutarse dentro de un contenedor y utilizar el PostgreSQL integrado para almacenar los datos. Por defecto, la API está disponible en el puerto 8888 y el Web Control Plane en 9999.

export OPENAI_API_KEY=sk-xxx

docker run -it --pull always \
  --name hindsight \
  --restart unless-stopped \
  --shm-size=1g \
  -p 8888:8888 \
  -p 9999:9999 \
  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
  -v hindsight-data:/home/hindsight/.pg0 \
  ghcr.io/vectorize-io/hindsight:latest

La API Key anterior es solo un ejemplo. En un entorno real, debe proporcionarse mediante variables de entorno o un sistema seguro de gestión de Secrets, y nunca debe incluirse directamente en un repositorio de código.

Hindsight no es un LLM. Operaciones como Retain necesitan un LLM para realizar tareas como la extracción de hechos, por lo que su funcionamiento puede generar costes de inferencia. La versión actual admite diferentes proveedores de LLM y permite configurar distintos modelos para diferentes operaciones.

Después instala el cliente de Python:

pip install hindsight-client

El Quick Start oficial también ofrece clientes para Python, Node.js y Go, además de una interfaz CLI.

Segundo paso: Retain — enseñar al Agent a recordar información importante

Primero guarda un hecho sencillo:

from hindsight_client import Hindsight

client = Hindsight(base_url="http://localhost:8888")

client.retain(
    bank_id="my-agent",
    content="Alice works at Google as a software engineer and prefers TypeScript."
)

Esta es la primera operación de Retain.

Pero no debes pensar en ella como una simple operación de guardar una frase completa. Hindsight procesa el contenido, extrae hechos estructurados, identifica entidades y relaciones, y crea los índices necesarios para las consultas posteriores.

En un proyecto real, tiene mucho más sentido guardar información como:

• Preferencias a largo plazo del usuario

• Stack tecnológico del proyecto

• Decisiones de arquitectura

• Soluciones que ya han sido verificadas

• Bugs históricos y sus soluciones

• Estado de tareas a largo plazo

En cambio, no es recomendable guardar permanentemente todas las conversaciones casuales.

Y, especialmente, no deberías almacenar contraseñas, API Keys, Tokens u otras credenciales sensibles en la memoria a largo plazo.

Tercer paso: Recall — recuperar el pasado

Ahora simulemos que ha pasado un día.

El usuario pregunta:

“¿A qué se dedica Alice y qué tecnología prefiere?”

Puedes utilizar:

results = client.recall(
    bank_id="my-agent",
    query="What does Alice do and which programming language does she prefer?"
)

print(results)

Esto es Recall.

No se trata simplemente de una búsqueda basada en similitud vectorial. El Recall actual de Hindsight combina diferentes estrategias de recuperación, incluyendo semántica, palabras clave, relaciones de grafo y aspectos temporales.

El proceso se parece más a:

Query
 ↓
Semantic Search
Keyword Search
Graph Search
Temporal Search
 ↓
Relevant Memories

Esta es también una de las principales diferencias entre Agent Memory y un simple sistema para almacenar conversaciones: lo importante no es cuánto se ha guardado, sino si en el futuro se puede encontrar la información realmente relevante.

Cuarto paso: Reflect — hacer que el Agent razone a partir de sus recuerdos

Recall devuelve recuerdos relevantes, mientras que Reflect va un paso más allá.

answer = client.reflect(
    bank_id="my-agent",
    query="What do we know about Alice?"
)

print(answer)

Una forma sencilla de distinguirlos es:

Recall   = ayúdame a encontrar información
Reflect  = analiza esa información y extrae conclusiones

El Reflect actual recupera automáticamente Memory relevante y después utiliza un LLM para combinar esa información y generar una respuesta. También puede devolver las memorias que respaldan la respuesta y utilizar la configuración correspondiente del Memory Bank y sus Mental Models.

Por tanto, las consultas sencillas sobre hechos suelen encajar bien con Recall, mientras que Reflect resulta más interesante cuando es necesario combinar diferentes recuerdos históricos.

Reflect requiere inferencia adicional del modelo, por lo que también implica un mayor consumo computacional y de Tokens.

Quinto paso: integrar Hindsight realmente en un Agent

El flujo realmente interesante no consiste en llamar de forma aislada a las tres APIs, sino en incorporarlas al ciclo de vida del Agent:

Usuario
 ↓
Agent
 ↓
Recall
 ↓
Hindsight Memory
 ↓
Obtener contexto histórico
 ↓
Ejecutar tarea
 ↓
Retain
 ↓
Guardar nuevas experiencias

Por ejemplo, el primer día un Coding Agent descubre:

El proyecto utiliza PostgreSQL 16
El proyecto no utiliza Prisma
La migración de base de datos utiliza el enfoque B

Cuando termina la tarea, puede hacer Retain de las nuevas decisiones importantes.

Al día siguiente, el usuario dice:

“Continúa con la parte de la base de datos.”

Antes de empezar, el Agent puede ejecutar Recall y recuperar:

PostgreSQL 16
No se utiliza Prisma
Ayer se adoptó el enfoque B

Así puede continuar directamente sobre las decisiones existentes, en lugar de volver a preguntar o repetir la fase de exploración.

Esta es precisamente la continuidad entre Sessions que Hindsight intenta proporcionar.

Hindsight frente al RAG tradicional

Un sistema RAG tradicional suele seguir este esquema:

Documents
 ↓
Chunks
 ↓
Embeddings
 ↓
Vector Search
 ↓
Context

Hindsight se centra más en acumular experiencias propias del Agent y conocimiento a largo plazo:

Experience
 ↓
Facts / Entities / Relationships
 ↓
Memory
 ↓
Recall / Reflect

Por eso no son necesariamente tecnologías que deban sustituirse entre sí.

RAG resulta especialmente útil para responder:

“¿Qué dicen los documentos de la empresa?”

Mientras que Agent Memory se centra más en:

“¿Qué ha ocurrido anteriormente en este proyecto y por qué tomamos esta decisión?”

Retain, Recall y Reflect de Hindsight están diseñados precisamente alrededor de este segundo escenario.

Sexto paso: conectar Hindsight con un Coding Agent real

Hindsight ya proporciona integraciones con varios Agents. Su integración oficial para Coding Agents es compatible con entornos como Claude Code, Codex CLI, OpenCode, Cursor CLI y GitHub Copilot CLI, utilizando Hooks o mecanismos de plugins para incorporar Recall y Retain al ciclo de vida del Agent.

Por ejemplo, con Codex, la integración oficial puede realizar Recall de recuerdos relevantes cuando el usuario envía un Prompt y ejecutar Retain al finalizar la Session. Para ello, la versión del Codex CLI debe ser compatible con los Hooks correspondientes.

La experiencia pasa así de:

Session 1 → el Agent olvida
Session 2 → vuelve a explorar
Session 3 → vuelve a preguntar

a:

Session 1
 ↓
Retain
 ↓
Memory Bank
 ↓
Session 2
 ↓
Recall
 ↓
Continuar el trabajo
 ↓
Retain nuevas experiencias

Esta es probablemente una de las aplicaciones más directas de la memoria a largo plazo en Coding Agents.

¿Qué deberías recordar de tu primera experiencia con Hindsight?

El flujo más sencillo solo requiere seis pasos:

Crear un Memory Bank
      ↓
Retain información valiosa
      ↓
Recall el historial relevante
      ↓
Usar Reflect para problemas complejos
      ↓
Conectar el Agent
      ↓
Acumular nuevas experiencias continuamente

No deberías entender Hindsight simplemente como una “base de datos de conversaciones”.

Una definición más precisa sería:

Hindsight añade a un AI Agent una capa de Memory capaz de acumular, recuperar y combinar experiencias pasadas a largo plazo.

Cuando un Agent deja de ser una herramienta utilizada durante una única Session y empieza a funcionar como un sistema que trabaja durante semanas o meses, ya no importa únicamente cuánto mide su Context Window. También importa si puede recordar lo ocurrido anteriormente, encontrar esa información cuando la necesita y utilizarla realmente en nuevas tareas.

FAQ

¿Cuál es la diferencia entre Hindsight y RAG?
RAG está más orientado a recuperar contexto desde conocimiento externo; Hindsight pone más énfasis en las experiencias a largo plazo del Agent, los hechos y el estado histórico. Ambas tecnologías pueden utilizarse conjuntamente.

¿Qué significan Retain, Recall y Reflect?
Una forma sencilla de recordarlo es: Retain = recordar, Recall = recuperar y Reflect = razonar a partir de los recuerdos.

¿Qué es un Memory Bank?
Es un espacio aislado de memoria a largo plazo que puede organizarse por usuario, proyecto o Agent. Los recuerdos de diferentes Banks no se exponen entre sí.

¿Hindsight funciona con Claude Code y Codex?
Sí. Actualmente existen integraciones oficiales para varios Coding Agents, aunque los pasos concretos de instalación deben comprobarse en la documentación correspondiente a cada versión.

¿Debería hacer Retain de todas las conversaciones?
No. Lo recomendable es priorizar preferencias, decisiones, experiencias y hechos del proyecto que puedan seguir siendo útiles en el futuro, evitando conversaciones temporales y credenciales sensibles.

¿Cuándo utilizar Reflect y cuándo Recall?
Si necesitas recuperar las memorias originales para que tu propio Agent las utilice, normalmente conviene utilizar Recall. Si quieres que Hindsight combine varias memorias y genere una respuesta a partir de ellas, utiliza Reflect. Reflect suele tener un coste computacional mayor.