gavdalf/total-recall

Total Recall — Memoria Autónoma para Agentes

La única habilidad de memoria que observa por sí sola.

Sin base de datos. Sin vectores. Sin guardados manuales. Solo un observador LLM que comprime tus conversaciones en notas priorizadas, las consolida cuando crecen y recupera cualquier cosa que se haya perdido. Cinco capas de redundancia, cero mantenimiento. ~$0.00/mes (usando modelos gratuitos).

Mientras otras habilidades de memoria te piden que recuerdes recordar, esta solo presta atención.

Arquitectura

Capa 1: Observador (cron, cada 15-30 min)
    ↓ comprime mensajes recientes → observations.md
Capa 2: Reflector (se activa automáticamente cuando observations > 8000 palabras)
    ↓ consolida, elimina información reemplazada → 40-60% de reducción
Capa 3: Recuperación de Sesión (se ejecuta en cada /new o /reset)
    ↓ captura cualquier sesión que el Observador haya omitido
Capa 4: Vigilante Reactivo (demonio inotify, solo Linux)
    ↓ activa el Observador tras 40+ nuevas escrituras JSONL, con 5 min de espera
Capa 5: Gancho de pre-compactación (memoryFlush)
    ↓ captura de emergencia antes de que OpenClaw compacte el contexto

Qué Hace

• Observador: lee las transcripciones recientes de la sesión (JSONL), las envía a un LLM y añade observaciones comprimidas a observations.md con niveles de prioridad (alta, media, baja)
• Reflector: se activa cuando las observaciones crecen demasiado, consolidando elementos relacionados y eliminando entradas obsoletas de baja prioridad
• Recuperación de Sesión: se ejecuta al inicio de la sesión, verifica si la sesión anterior fue capturada y, si no, realiza una observación de emergencia
• Vigilante Reactivo: vigila el directorio de sesiones con inotify para que los periodos de alta actividad se capturen más rápido que el intervalo de cron
• Gancho de pre-compactación: se activa cuando OpenClaw está a punto de compactar el contexto, asegurando que no se pierda nada

Inicio Rápido

1. Instala la habilidad

clawdhub install total-recall

2. Configura tu clave API

Añade a tu archivo .env o configuración de OpenClaw:

OPENROUTER_API_KEY=sk-or-v1-xxxxx

3. Ejecuta el script de configuración

bash skills/total-recall/scripts/setup.sh

Esto hará lo siguiente:

• Crear la estructura de directorios de memoria (memory/, logs/, backups)
• En Linux con inotify + systemd: instalar el servicio del vigilante reactivo
• Mostrar instrucciones para trabajos cron y configuración del agente que deberás añadir manualmente

4. Configura tu agente para cargar las observaciones

Añade al contexto del espacio de trabajo de tu agente (por ejemplo, MEMORY.md o el prompt del sistema):

Al iniciar la sesión, lee `memory/observations.md` para obtener el contexto entre sesiones.

O usa memoryFlush.systemPrompt de OpenClaw para inyectar una instrucción de inicio.

Compatibilidad de Plataformas

Plataforma	Observador + Reflector + Recuperación	Vigilante Reactivo
Linux (Debian/Ubuntu/etc.)	Soporte completo	Con inotify-tools
macOS	Soporte completo	No disponible (solo cron)

Todos los scripts principales usan bash portable. Los comandos stat, date y md5 se manejan multiplataforma a través de _compat.sh.

Configuración

Todos los scripts leen variables de entorno con valores predeterminados sensatos:

Variable	Valor por defecto	Descripción
OPENROUTER_API_KEY	(obligatorio)	Clave API de OpenRouter para llamadas LLM
MEMORY_DIR	$OPENCLAW_WORKSPACE/memory	Donde reside observations.md
SESSIONS_DIR	~/.openclaw/agents/main/sessions	Transcripciones de sesiones de OpenClaw
OBSERVER_MODEL	stepfun/step-3.5-flash:free	Modelo principal para compresión (gratuito)
OBSERVER_FALLBACK_MODEL	nvidia/nemotron-3-nano-30b-a3b:free	Modelo de respaldo si el principal falla (gratuito)
OBSERVER_LOOKBACK_MIN	15	Minutos hacia atrás para observar (durante el día)
OBSERVER_MORNING_LOOKBACK_MIN	480	Minutos hacia atrás para observar (antes de las 8am)
OBSERVER_LINE_THRESHOLD	40	Líneas antes del disparo reactivo (Linux)
OBSERVER_COOLDOWN_SECS	300	Tiempo de espera entre disparos reactivos (Linux)
REFLECTOR_WORD_THRESHOLD	8000	Palabras antes de que se ejecute el reflector
REFLECTOR_MODEL	nvidia/nemotron-3-super-120b-a12b:free	Modelo para consolidar observaciones (gratuito)
REFLECTOR_FALLBACK_MODEL	openrouter/hunter-alpha	Modelo de respaldo si el reflector falla (gratuito)
OPENCLAW_WORKSPACE	~/your-workspace	Raíz del espacio de trabajo

Configuración del Proveedor LLM

Total Recall usa cualquier API de finalización de chat compatible con OpenAI. Cambia de proveedor configurando variables de entorno:

Variable	Valor por defecto	Descripción
LLM_BASE_URL	https://openrouter.ai/api/v1	Endpoint de la API
LLM_API_KEY	recurre a OPENROUTER_API_KEY	Clave API
LLM_MODEL	deepseek/deepseek-v3.2	Modelo a usar

Ejemplos de proveedores

# OpenRouter (por defecto)
export OPENROUTER_API_KEY="tu-clave"

# Ollama (local)
export LLM_BASE_URL="http://localhost:11434/v1"
export LLM_API_KEY="ollama"
export LLM_MODEL="llama3.1:8b"

# Groq
export LLM_BASE_URL="https://api.groq.com/openai/v1"
export LLM_API_KEY="tu-clave-groq"
export LLM_MODEL="llama-3.3-70b-versatile"

Archivos Creados

memory/
  observations.md          # El registro principal de observaciones (se carga al inicio)
  observation-backups/     # Copias de seguridad del reflector (se conservan las últimas 10)
  .observer-last-run       # Marca de tiempo de la última ejecución del observador
  .observer-last-hash      # Hash de deduplicación de los últimos mensajes procesados
logs/
  observer.log
  reflector.log
  session-recovery.log
  observer-watcher.log

Trabajos Cron

El script de configuración crea estos trabajos cron de OpenClaw:

Trabajo	Horario	Descripción
memory-observer	Cada 15 min	Comprimir conversación reciente
memory-reflector	Cada hora	Consolidar si las observaciones son grandes

Vigilante Reactivo (solo Linux)

El vigilante reactivo usa inotifywait para detectar actividad en la sesión y activar el observador más rápido que el cron solo. Requiere Linux con inotify-tools instalado.

# Instalar inotify-tools (Debian/Ubuntu)
sudo apt install inotify-tools

# Verificar el estado del vigilante
systemctl --user status total-recall-watcher

# Ver registros
journalctl --user -u total-recall-watcher -f

Costo

Usando los modelos gratuitos predeterminados a través de OpenRouter:

• ~$0.00/mes (usando modelos gratuitos) para uso típico (observador + reflector)
• ~15-30 ejecuciones de cron/día, cada una procesando unos pocos cientos de tokens
• Todos los modelos predeterminados son de nivel gratuito

Notas sobre Modelos

Los scripts incluyen manejo defensivo tanto para los campos .content como .reasoning en las respuestas de la API. Mientras que la mayoría de los modelos devuelven contenido en el campo estándar .content, la alternativa a .reasoning asegura compatibilidad con modelos que pueden usar formatos de respuesta diferentes.

Cómo Funciona (Técnico)

Observador

1. Encuentra archivos de sesión JSONL modificados recientemente
2. Filtra sesiones de subagentes/cron
3. Extrae mensajes de usuario + asistente dentro de la ventana de observación
4. Deduplica usando comparación de hash MD5
5. Envía al LLM con el prompt del observador (compresión basada en prioridad)
6. Añade el resultado a observations.md
7. Si las observaciones superan el umbral de palabras, activa el reflector

Reflector

1. Crea una copia de seguridad de las observaciones actuales
2. Envía todo el registro al LLM con instrucciones de consolidación
3. Valida que la salida sea más corta que la entrada (comprobación de cordura)
4. Reemplaza las observaciones con la versión consolidada
5. Limpia las copias de seguridad antiguas (conserva las últimas 10)

Recuperación de Sesión

1. Se ejecuta en cada /new o /reset
2. Genera un hash de las líneas recientes del último archivo de sesión
3. Compara con el hash almacenado de la última ejecución del observador
4. Si no coinciden: ejecuta el observador en modo de recuperación (ventana de 4 horas)
5. Alternativa: extracción de mensajes sin procesar si el observador falla

Vigilante Reactivo

1. Usa inotifywait para monitorear el directorio de sesiones
2. Cuenta escrituras JSONL solo en los archivos de sesión principales
3. Después de 40+ líneas: activa el observador (con 5 min de espera)
4. Reinicia el contador cuando se detectan ejecuciones del observador por cron/externo

Personalización de Prompts

Los prompts del sistema del observador y el reflector están en prompts/:

• prompts/observer-system.txt — controla cómo se comprimen las conversaciones
• prompts/reflector-system.txt — controla cómo se consolidan las observaciones

Edítalos para que coincidan con la personalidad y prioridades de tu agente.

---

Ciclo de Sueño

El Ciclo de Sueño es un agente nocturno opcional que se ejecuta fuera del horario laboral para consolidar observations.md. Archiva elementos obsoletos y añade ganchos semánticos para que nada útil se pierda realmente. El contexto se mantiene ligero; todo sigue siendo localizable.

Qué Hace

• Clasifica cada observación por impacto (crítico / alto / medio / bajo / mínimo) y antigüedad
• Archiva elementos que han superado su umbral de relevancia
• Añade un gancho semántico para cada elemento archivado (palabras clave específicas + referencia de archivo)
• Valida el resultado y revierte automáticamente si algo sale mal

Características

Recuperación Multi-Gancho — 4-5 frases de búsqueda alternativas por elemento archivado. Las búsquedas con palabras diferentes a las originales siguen encontrando la memoria.

Puntuación de Confianza — cada observación recibe una puntuación de confianza (0.0-1.0) y un tipo de fuente (explicit, implicit, inference, weak, uncertain). Los elementos de alta confianza se conservan más tiempo; los de baja confianza se archivan antes.

Sistema de Tipos de Memoria — 7 tipos con TTLs por tipo: event (14d), fact (90d), preference (180d), goal (365d), habit (365d), rule (nunca), context (30d). Incrustados como comentarios HTML de metadatos invisibles en observations.md.

Fragmentación de Observaciones — grupos de 3 o más observaciones relacionadas se comprimen en resúmenes únicos. Las observaciones fuente se archivan; un gancho de fragmento las reemplaza. Logra hasta un 75% de reducción de tokens.

Decaimiento de Importancia — decaimiento diario por tipo aplicado a las puntuaciones de importancia antes de cada decisión de archivo. Los elementos que decaen por debajo del umbral de archivo se ponen en cola para su eliminación. Tasas: event (-0.5/día), fact (-0.1/día), preference (-0.02/día), rule/habit/goal (sin decaimiento).

Promoción de Patrones — escanea los registros de sueño recientes en busca de temas recurrentes (3+ ocurrencias en 3+ días separados). Escribe propuestas de promoción en memory/dream-staging/ para revisión humana. Usa staging-review.sh para listar, mostrar, aprobar o rechazar propuestas. El tipo context nunca se promociona automáticamente.

Configuración

1. Ejecuta bash skills/total-recall/scripts/setup.sh — crea los directorios del Ciclo de Sueño automáticamente.

2. Añade el trabajo cron nocturno como un turno completo del agente:

   # Ciclo de Sueño — nocturno (se recomienda a las 3am; ajústalo a tu zona horaria)
   # El ciclo de sueño se ejecuta como un turno completo del agente — NO como una llamada bash directa.
   # dream-cycle.sh es un ayudante de operaciones de archivos llamado POR el agente, no el punto de entrada.
   #
   # 0 3 * * * bash -c 'source ~/.openclaw/shared/secrets/openclaw-secrets.env \
   #   && openclaw agent --agent main \
   #   --message "Ejecuta el Ciclo de Sueño de Total Recall. Sigue las instrucciones en \
   # $WORKSPACE/skills/total-recall/prompts/dream-cycle-prompt.md exactamente. \
   # Usa READ_ONLY_MODE=false y DREAM_PHASE=1." \
   #   --json >> $WORKSPACE/logs/dream-cycle.log 2>&1'
   

3. Configura tu agente cron usando prompts/dream-cycle-prompt.md como prompt del sistema. Modelos recomendados: Claude Sonnet para el Soñador (análisis + decisiones), DeepSeek v3.2 para el Observador (barato, rápido).

4. Empieza con READ_ONLY_MODE=true durante las primeras noches. Revisa memory/dream-logs/ después de cada ejecución para verificar qué habría archivado.

5. Cambia a READ_ONLY_MODE=false una vez que estés satisfecho.

Configuración

Variable	Valor por defecto	Descripción
DREAM_TOKEN_TARGET	8000	Objetivo de tokens para observations.md después de la consolidación
READ_ONLY_MODE	false	Pon true para análisis de prueba sin escrituras

Archivos

Archivo	Descripción
scripts/dream-cycle.sh	Ayudante de shell llamado por el agente (no es un ejecutable independiente): pre-vuelo, archivo, actualizar-observaciones, escribir-registro, escribir-métricas, validar, revertir
prompts/dream-cycle-prompt.md	Prompt del agente para la ejecución nocturna del Ciclo de Sueño
dream-cycle/README.md	Referencia rápida del Ciclo de Sueño
schemas/observation-format.md	Formato de metadatos extendido de observación

Directorios Creados

memory/
  archive/
    observations/        # Elementos archivados (un archivo .md por noche)
    chunks/              # Grupos de observaciones fragmentadas
  dream-logs/            # Informes de ejecuciones nocturnas
  dream-staging/         # Propuestas de promoción de patrones pendientes de revisión humana
  .dream-backups/        # Copias de seguridad previas a la ejecución
research/
  dream-cycle-metrics/
    daily/               # Métricas JSON por noche

---

Solución de Problemas

¿El observador no se ejecuta?

• Revisa logs/observer.log para ver errores
• Verifica que OPENROUTER_API_KEY esté configurada y sea válida
• Confirma que el cron esté activo: crontab -l

¿Las observaciones no se cargan al iniciar la sesión?

• Asegúrate de que las instrucciones de inicio de tu agente incluyan la lectura de memory/observations.md
• Verifica que MEMORY_DIR apunte a la ubicación correcta

¿El vigilante reactivo no se activa (Linux)?

• Ejecuta systemctl --user status total-recall-watcher
• Verifica que inotify-tools esté instalado: which inotifywait
• Consulta los registros del vigilante: journalctl --user -u total-recall-watcher -f

¿El Ciclo de Sueño archiva de forma demasiado agresiva?

• Activa READ_ONLY_MODE=true y revisa los registros de sueño antes de ponerlo en marcha
• Aumenta DREAM_TOKEN_TARGET para archivar menos por ejecución

¿El Ciclo de Sueño no archiva lo suficiente?

• Reduce DREAM_TOKEN_TARGET para activar una consolidación más agresiva

---

Inspirado Por

Este sistema está inspirado en cómo funciona la memoria humana durante el sueño: el hipocampo (observador) captura experiencias, y durante la consolidación del sueño (reflector), los recuerdos importantes se fortalecen mientras que el ruido se descarta.

Lee más: Your AI Has an Attention Problem

"Lleva tu trasero a Marte." — Bueno, lleva la memoria de tu agente a funcionar.