Compaction & Pre-Compaction Memory Flush

1. Objetivo de la Investigación

Se buscaba entender y potencialmente extender el sistema de hooks de OpenClaw para ejecutar lógica personalizada before/after compaction. El caso de uso principal: asegurar que información crítica de sesión se persista a disco antes de que el contexto sea compactado (y potencialmente perdido).

Preguntas clave

• ¿Existe un sistema de hooks before_compaction / after_compaction?
• ¿Cómo funciona el memoryFlush nativo de OpenClaw?
• ¿Por qué no vemos archivos de sesión nuevos en ~/.openclaw/agents/main/sessions/?
• ¿Cómo verificar si el flush está ejecutándose?

2. Documentación vs. Código Real

Lo que dicen los docs

La documentación en /opt/openclaw/docs/ describe un sistema completo de memory flush pre-compaction:

agents.defaults.compaction.memoryFlush:
  enabled: true (default)
  softThresholdTokens: 4000 (default)
  prompt: "Write any lasting notes to memory/YYYY-MM-DD.md..."
  systemPrompt: "Session nearing compaction. Store durable memories now."

Lo que encontramos en código

El código en /opt/openclaw/dist/auto-reply/reply/agent-runner-memory.js confirma la existencia del sistema:

// Extractos del código real
const memoryFlushSettings = resolveMemoryFlushSettings(params.cfg);
if (!memoryFlushSettings) { return; }

const shouldFlushMemory = memoryFlushSettings &&
    memoryFlushWritable &&
    reserveTokensFloor: memoryFlushSettings.reserveTokensFloor,
    softThresholdTokens: memoryFlushSettings.softThresholdTokens,

// Tracking en session entry
memoryFlushAt: Date.now(),
memoryFlushCompactionCount: nextCount

Discrepancias observadas

3. Cómo Funciona memoryFlush

Flujo de ejecución

┌─────────────────────────────────────────────────────────────┐
│                    SESSION TURN                              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. Gateway recibe mensaje                                  │
│           ↓                                                  │
│  2. Calcula contextTokens vs contextWindow                  │
│           ↓                                                  │
│  3. Si contextTokens > (window - reserveFloor - softThresh) │
│           ↓                                                  │
│  4. ¿memoryFlushCompactionCount < compactionCount?          │
│           ↓                                                  │
│     YES → Ejecuta silent turn con prompt de flush           │
│           ↓                                                  │
│  5. Agente escribe a memory/YYYY-MM-DD.md                   │
│           ↓                                                  │
│  6. Responde "NO_REPLY" (suprimido al usuario)              │
│           ↓                                                  │
│  7. Actualiza memoryFlushAt + memoryFlushCompactionCount    │
│           ↓                                                  │
│  8. Continúa con el turn normal del usuario                 │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Condiciones para el flush

1. memoryFlush.enabled debe ser true
2. Workspace debe ser writable (workspaceAccess no "ro" ni "none")
3. Tokens cerca del límite: contextTokens > contextWindow - reserveTokensFloor - softThresholdTokens
4. No se ha hecho flush en este ciclo: memoryFlushCompactionCount < compactionCount
5. Solo sesiones Pi embedded (CLI backends lo saltan)

Defaults del sistema

Prompts default

// User prompt
"Pre-compaction memory flush. Store durable memories now 
(use memory/YYYY-MM-DD.md; create memory/ if needed). 
If nothing to store, reply with NO_REPLY."

// System prompt append
"Session nearing compaction. Store durable memories now."

4. Campos de Tracking en sessions.json

El archivo ~/.openclaw/agents/main/sessions/sessions.json contiene un objeto por cada sessionKey con los siguientes campos relevantes:

Estado actual observado

// Ejemplo de sesión WhatsApp principal
"agent:main:whatsapp:dm:+34690395233": {
  "compactionCount": 0,
  "memoryFlushAt": null,
  "memoryFlushCompactionCount": null
}

// Ejemplo de sesión MS Teams con compaction
"agent:main:msteams:group:19:d2e55d7c...@thread.v2": {
  "compactionCount": 2,
  "memoryFlushAt": null,
  "memoryFlushCompactionCount": null
}

5. Análisis de Evidencia

Evidencia positiva: JSONL transcripts

Encontramos 18 ocurrencias de NO_REPLY en los transcripts JSONL, con el patrón exacto del memory flush:

// Archivo: 0bcee1ba-4e58-41b2-a365-41e3c12840e1.jsonl (Jan 31)

// User prompt (silent injection)
{
  "role": "user",
  "text": "Pre-compaction memory flush. Store durable memories now 
           (use memory/YYYY-MM-DD.md; create memory/ if needed). 
           If nothing to store, reply with NO_REPLY."
}

// Assistant response
{
  "role": "assistant",
  "thinking": "Good, I've updated the memory file with the current state. 
              The summary is now persisted. I should reply NO_REPLY since 
              this was a memory flush request...",
  "text": "NO_REPLY"
}

Archivos de memoria existentes

6. Estado Actual del Sistema

Configuración de compaction

// ~/.openclaw/openclaw.json (extracto)
{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard"
      }
    }
  }
}

Sesiones activas por uso de contexto

Hooks disponibles

$ openclaw hooks list

Hooks (3/4 ready)
┌───────────┬──────────────────┬────────────────────────────────────────┐
│ Status    │ Hook             │ Description                            │
├───────────┼──────────────────┼────────────────────────────────────────┤
│ ✓ ready   │ 🚀 boot-md        │ Run BOOT.md on gateway startup         │
│ ✓ ready   │ 📝 command-logger │ Log all command events                 │
│ ✓ ready   │ 💾 session-memory │ Save session context on /new command   │
│ ✗ missing │ 😈 soul-evil      │ Swap SOUL.md with SOUL_EVIL.md         │
└───────────┴──────────────────┴────────────────────────────────────────┘

7. ¿Por Qué No Hay Archivos Recientes?

Varias razones explican por qué no vemos actividad de memoryFlush en los últimos días:

Hipótesis 1: Threshold no alcanzado

El flush se dispara cuando:

contextTokens > contextWindow - reserveTokensFloor - softThresholdTokens

Para Claude Opus (200k window):
contextTokens > 200,000 - 20,000 - 4,000 = 176,000 tokens

La sesión más cargada tiene 109k tokens (54%), aún lejos del threshold de ~176k (88%).

Hipótesis 2: Daily session reset

OpenClaw hace reset automático de sesión a las 4:00 AM por defecto. Si las sesiones se resetean antes de alcanzar el threshold, nunca se dispara el flush.

Hipótesis 3: Cambio de modelo mid-conversation

Si una sesión cambia de modelo (ej: claude → gpt-5.2), el context window cambia. Un session con 181k tokens en gpt-5.2 (400k window) está al 45%, muy lejos del threshold.

Hipótesis 4: Session archivos son de sesiones antiguas

Los archivos memory/*.md fueron creados por sesiones que ya no existen (session IDs diferentes). Las sesiones actuales no han alcanzado el threshold todavía.

8. Recomendaciones y Próximos Pasos

Opción A: Ajustar thresholds de memoryFlush

Reducir el threshold para que el flush ocurra más temprano:

// En ~/.openclaw/openclaw.json
{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 20000,  // Trigger más temprano
          "reserveTokensFloor": 30000    // Más margen
        }
      }
    }
  }
}

Pro: Flush ocurre más frecuentemente. Con: Más turns silenciosos, más tokens consumidos.

Opción B: Personalizar el prompt de flush

Hacer el prompt más específico para tu workflow:

"memoryFlush": {
  "prompt": "Session approaching compaction. Write critical context to memory/YYYY-MM-DD.md:\n- Key decisions made\n- User preferences learned\n- Action items pending\n- Important facts mentioned\nIf nothing critical, reply NO_REPLY.",
  "systemPrompt": "You are about to lose context. Preserve anything important."
}

Opción C: Hook en session-memory

El hook session-memory ya existe y se ejecuta en /new. Se podría extender para:

• Ejecutar también en compaction events (si OpenClaw expone el hook)
• Forzar escritura de memoria a intervalos regulares

Opción D: Inyección en before_agent_start

Si no hay hook nativo, se puede inyectar lógica en el system prompt para recordar al agente que escriba a memoria periódicamente:

// En AGENTS.md o system prompt
"Every ~10 turns, proactively write a summary of the conversation
to memory/YYYY-MM-DD.md. Don't wait for compaction."

Opción E: Plugin custom

Crear un plugin de OpenClaw que intercepte eventos de sesión y fuerce flush basado en criterios custom (tiempo, turns, tokens).

9. Checklist de Verificación

Para verificar que memoryFlush está funcionando:

1. Revisar sessions.json

   cat ~/.openclaw/agents/main/sessions/sessions.json | \
     jq '.[] | select(.memoryFlushAt != null)'

2. Buscar NO_REPLY en transcripts recientes

   grep -l "NO_REPLY" ~/.openclaw/agents/main/sessions/*.jsonl | \
     xargs ls -la

3. Monitorear archivos de memoria

   watch -n 60 'ls -la /root/kleo/memory/'

4. Verificar logs del gateway

   grep -i "memory.*flush\|compaction" /tmp/openclaw/openclaw-*.log

5. Forzar threshold bajo temporalmente para testear que el mecanismo funciona