Arquitectura de memoria de tres capas para el contexto persistente del agente OpenClaw

Arquitectura de memoria para contexto persistente de agentes

Un desarrollador que ejecuta una operación de múltiples agentes en OpenClaw para bienes raíces encontró una pérdida persistente de contexto donde los agentes comenzaban cada sesión desde cero, requiriendo reexplicación del trabajo anterior. Esto generó costos comerciales concretos, incluyendo agentes tratando a clientes potenciales calientes como extraños y perdiendo plazos debido a la falta de estado.

La solución es una arquitectura de memoria de 3 capas construida sobre la infraestructura existente de espacio de trabajo y memoria de OpenClaw. La información fluye hacia abajo a través de las capas y nunca se duplica entre ellas.

Capa 1: Cerebro (archivos de espacio de trabajo)

OpenClaw inyecta automáticamente un conjunto fijo de archivos de espacio de trabajo como contexto del proyecto en cada turno. Estos siete archivos forman el sistema operativo del agente:

• SOUL.md: personalidad, voz, valores
• AGENTS.md: rol, reglas, carril
• MEMORY.md: qué está activo ahora mismo (una línea por elemento, tiempo presente)
• USER.md: cómo piensa el usuario y qué necesita
• TOOLS.md: comandos específicos de máquina y soluciones alternativas
• IDENTITY.md: nombre, rol, referencia rápida
• HEARTBEAT.md: tareas permanentes para verificaciones recurrentes

El desarrollador estableció una regla de presupuesto: aunque OpenClaw permite hasta 20,000 caracteres por archivo, apuntan a 500-1,000 tokens por archivo, manteniendo el total de L1 bajo 7,000 tokens. Esto asegura que los agentes realmente lean todo en lugar de ojear archivos inflados. Un comando trim hace cumplir este límite.

Regla de estabilidad: solo el usuario o un punto de control actualizan los archivos L1. Los agentes no cambian aleatoriamente sus propias reglas, con la excepción de que MEMORY.md puede actualizarse para reflejar el estado actual.

Capa 2: Memoria (búsqueda semántica)

Esta es la recuperación a largo plazo usando la herramienta incorporada de OpenClaw memory_search que busca semánticamente a través de MEMORY.md y todo dentro del directorio memory/. Cuando se le pregunta a un agente sobre trabajo previo, decisiones o contexto, busca automáticamente en L2.

Dos tipos de archivos viven aquí:

• Notas diarias: memory/YYYY-MM-DD.md (convención de OpenClaw) que contiene historial de sesiones, decisiones tomadas, trabajo completado y correcciones
• Archivos de migas de pan: memory/[nombre-del-tema].md (adición del desarrollador) que contiene hechos curados organizados por situación, con máximo 4KB por archivo, un hecho por línea

Cada hecho clave en los archivos de migas de pan incluye un puntero a L3: → Inmersión profunda: reference/nombre-del-archivo.md. Esto crea un puente entre L2 y L3 para que los agentes no necesiten cargar documentos de referencia completos solo para recordar un hecho relevante.

Perspicacia crítica: la precisión de L2 depende completamente de lo que se escribe en ella. Si un agente realiza una acción y no la captura antes de continuar, el archivo de estado comienza a devolver información desactualizada.

Capa 3: Referencia (bajo demanda)

Esta es completamente una adición del desarrollador, no una convención de OpenClaw. Un directorio reference/ contiene contexto profundo: SOPs, marcos de trabajo, manuales de procedimientos e investigación.

Los agentes acceden a L3 bajo demanda cuando una tarea específica requiere profundidad. No es buscado por memory_search por diseño para evitar consumir contexto cargando cosas que rara vez importan.

El flujo completo: L1 (siempre cargado) → buscar L2 (memoria) → abrir L3 (referencia) bajo demanda.