Activa Active Memory en OpenClaw: Guía de Configuración

¿Alguna vez has sentido que tu IA es un poco olvidadiza? A veces, los sistemas de memoria son demasiado reactivos y esperan a que tú les pidas recordar algo, perdiendo la oportunidad de que la conversación fluya de forma natural. Active Memory soluciona esto actuando como un sub-agent que busca información relevante justo antes de generar la respuesta principal.

Pega esto en tu Agent

Pega esto en tu agent si quieres activar Active Memory con una configuración autónoma y segura por defecto:

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          enabled: true,
          agents: ["main"],
          allowedChatTypes: ["direct"],
          modelFallbackPolicy: "default-remote",
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          persistTranscripts: false,
          logging: true,
        },
      },
    },
  },
}

Esto activa el plugin para el agent main, lo limita a sesiones de tipo mensaje directo por defecto, permite que herede el model de la sesión actual y mantiene el fallback remoto integrado si no hay un model explícito o heredado disponible.

Después, reinicia el Gateway:

openclaw gateway

Para inspeccionarlo en vivo durante una conversación:

/verbose on

Activa Active Memory

La configuración más segura es:

1. activar el plugin
2. apuntar a un agent conversacional
3. mantener el logging encendido solo mientras realizas ajustes

Empieza con esto en openclaw.json:

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          allowedChatTypes: ["direct"],
          modelFallbackPolicy: "default-remote",
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          persistTranscripts: false,
          logging: true,
        },
      },
    },
  },
}

Luego reinicia el Gateway:

openclaw gateway

Qué significa esto:

• plugins.entries.active-memory.enabled: true activa el plugin
• config.agents: ["main"] vincula solo al agent main con Active Memory
• config.allowedChatTypes: ["direct"] mantiene Active Memory solo para sesiones de mensajes directos por defecto
• si config.model no está definido, Active Memory hereda primero el model de la sesión actual
• config.modelFallbackPolicy: "default-remote" mantiene el fallback remoto integrado como predeterminado cuando no hay un model explícito o heredado
• config.promptStyle: "balanced" usa el estilo de prompt general por defecto para el modo recent
• Active Memory solo se ejecuta en sesiones de chat interactivas y persistentes que cumplan los requisitos

Cómo verlo

Active Memory inyecta contexto de sistema oculto para el model. No expone etiquetas <active_memory_plugin>...</active_memory_plugin> sin procesar al cliente.

Alternar sesión

Usa el comando del plugin cuando quieras pausar o reanudar Active Memory para la sesión de chat actual sin editar la configuración:

/active-memory status
/active-memory off
/active-memory on

Esto tiene alcance de sesión. No cambia plugins.entries.active-memory.enabled, el targeting del agent u otra configuración global.

Si quieres que el comando escriba en la configuración y pause o reanude Active Memory para todas las sesiones, usa la forma global explícita:

/active-memory status --global
/active-memory off --global
/active-memory on --global

La forma global escribe en plugins.entries.active-memory.config.enabled. Deja plugins.entries.active-memory.enabled activado para que el comando siga disponible para volver a encender Active Memory más tarde.

Si quieres ver qué está haciendo Active Memory en una sesión en vivo, activa el modo verbose para esa sesión:

/verbose on

Con verbose activado, OpenClaw puede mostrar:

• una línea de estado de Active Memory como Active Memory: ok 842ms recent 34 chars
• un resumen de depuración legible como Active Memory Debug: Lemon pepper wings with blue cheese.

Estas líneas se derivan del mismo paso de Active Memory que alimenta el contexto de sistema oculto, pero están formateadas para humanos en lugar de exponer el marcado del prompt original.

Por defecto, la transcripción del sub-agent de memoria de bloqueo es temporal y se elimina tras completar la ejecución.

Flujo de ejemplo:

/verbose on
what wings should i order?

Forma de la respuesta visible esperada:

...normal assistant reply...

🧩 Active Memory: ok 842ms recent 34 chars
🔎 Active Memory Debug: Lemon pepper wings with blue cheese.

AI Setup Assistant

Siguiente paso

• Memory Systems
• Plugin Configuration

Cuándo se ejecuta

Active memory utiliza dos filtros principales:

1. Configuración de activación El plugin debe estar habilitado y el agent id actual debe aparecer en plugins.entries.active-memory.config.agents.
2. Elegibilidad estricta en tiempo de ejecución Aunque esté habilitado y configurado para un agent, active memory solo se ejecuta en sesiones de chat interactivas y persistentes que sean elegibles.

La regla real es:

plugin enabled
+
agent id targeted
+
allowed chat type
+
eligible interactive persistent chat session
=
active memory runs

Si cualquiera de estos puntos falla, active memory no se ejecuta.

Tipos de sesión

config.allowedChatTypes controla qué clases de conversaciones pueden ejecutar Active Memory.

El valor por defecto es:

allowedChatTypes: ["direct"]

Esto significa que Active Memory se ejecuta por defecto en sesiones de estilo mensaje directo, pero no en sesiones de grupo o canales a menos que los incluyas explícitamente.

Ejemplos:

allowedChatTypes: ["direct"]

allowedChatTypes: ["direct", "group"]

allowedChatTypes: ["direct", "group", "channel"]

Dónde se ejecuta

Active memory es una funcionalidad para enriquecer conversaciones, no es una característica de inferencia para toda la plataforma.

Superficie	¿Ejecuta active memory?
Sesiones persistentes de Control UI / web chat	Sí, si el plugin está habilitado y el agent configurado
Otras sesiones de canales interactivos en la misma ruta de chat persistente	Sí, si el plugin está habilitado y el agent configurado
Ejecuciones headless one-shot	No
Ejecuciones de heartbeat o en segundo plano	No
Rutas genéricas internas de agent-command	No
Ejecución de sub-agent o ayudantes internos	No

Por qué usarlo

Te recomiendo usar active memory cuando:

• la sesión sea persistente y esté orientada al usuario
• el agent tenga memoria a largo plazo valiosa para buscar
• la continuidad y la personalización importen más que el determinismo puro del prompt
• necesites que el contexto evolucione con el tiempo

Funciona especialmente bien para:

• preferencias estables
• hábitos recurrentes
• contexto de usuario a largo plazo que deba aparecer de forma natural
• interacciones que requieren recordar detalles de semanas anteriores

No es una buena opción para:

• automatización
• workers internos
• tareas de API de tipo one-shot
• lugares donde una personalización oculta resultaría extraña o confusa

Cómo funciona

La estructura en tiempo de ejecución es la siguiente:

flowchart LR
  U["User Message"] --> Q["Build Memory Query"]
  Q --> R["Active Memory Blocking Memory Sub-Agent"]
  R -->|NONE or empty| M["Main Reply"]
  R -->|relevant summary| I["Append Hidden active_memory_plugin System Context"]
  I --> M["Main Reply"]

El sub-agent de memoria de bloqueo solo puede usar:

• memory_search
• memory_get

Si la conexión es débil, debería devolver NONE.

Modos de consulta

config.queryMode controla cuánta conversación ve el sub-agent de memoria de bloqueo.

Estilos de prompt

config.promptStyle controla qué tan insistente o estricto es el sub-agent de memoria de bloqueo al decidir si devuelve una memoria.

Estilos disponibles:

• balanced: predeterminado de uso general para el modo recent.
• strict: el menos insistente; es ideal cuando quieres que el contexto cercano no afecte casi nada.
• contextual: el más amigable con la continuidad; es ideal cuando el historial de la conversación debe importar más.
• recall-heavy: más dispuesto a mostrar memorias con coincidencias más suaves pero plausibles.
• precision-heavy: prefiere agresivamente NONE a menos que la coincidencia sea obvia.
• preference-only: optimizado para favoritos, hábitos, rutinas, gustos y datos personales recurrentes.

Mapeo predeterminado cuando config.promptStyle no está configurado:

message -> strict
recent -> balanced
full -> contextual

Si configuras config.promptStyle explícitamente, esa configuración tiene prioridad.

Ejemplo:

promptStyle: "preference-only"

Política de respaldo del modelo

Si config.model no está configurado, Active Memory intenta resolver un modelo en este orden:

explicit plugin model
-> current session model
-> agent primary model
-> optional built-in remote fallback

config.modelFallbackPolicy controla el último paso.

Predeterminado:

modelFallbackPolicy: "default-remote"

Otra opción:

modelFallbackPolicy: "resolved-only"

Usa resolved-only si quieres que Active Memory omita la recuperación en lugar de recurrir al valor predeterminado remoto cuando no hay un modelo explícito o heredado disponible.

AI Setup Assistant

Escotillas de escape avanzadas

Estas opciones no forman parte de la configuración recomendada por defecto.

config.thinking puede sobrescribir el nivel de pensamiento del sub-agent de memoria bloqueante:

thinking: "medium"

Por defecto:

thinking: "off"

No actives esto a menos que sea necesario. Active Memory se ejecuta en la ruta de respuesta, por lo que el tiempo de pensamiento extra aumenta directamente la latencia que percibe el usuario.

config.promptAppend añade instrucciones adicionales del operador después del prompt por defecto de Active Memory y antes del contexto de la conversación:

promptAppend: "Prefer stable long-term preferences over one-off events."

config.promptOverride reemplaza el prompt por defecto de Active Memory. OpenClaw seguirá añadiendo el contexto de la conversación después:

promptOverride: "You are a memory search agent. Return NONE or one compact user fact."

No se recomienda personalizar el prompt a menos que estés probando deliberadamente un contrato de recuperación diferente. El prompt por defecto está ajustado para devolver NONE o un contexto de hecho de usuario compacto para el modelo principal.

message

Solo se envía el último mensaje del usuario.

Latest user message only

Usa esto cuando:

• buscas el comportamiento más rápido y el sesgo más fuerte hacia la recuperación de preferencias estables.
• los turnos de seguimiento no necesitan contexto conversacional.

Timeout recomendado:

• empieza entre 3000 y 5000 ms.

recent

Se envía el último mensaje del usuario más una pequeña parte final de la conversación reciente.

Recent conversation tail:
user: ...
assistant: ...
user: ...

Latest user message:
...

Usa esto cuando:

• buscas un mejor equilibrio entre velocidad y base conversacional.
• las preguntas de seguimiento suelen depender de los últimos turnos.

Timeout recomendado:

• empieza alrededor de 15000 ms.

full

Se envía la conversación completa al sub-agent de memoria bloqueante.

Full conversation context:
user: ...
assistant: ...
user: ...
...

Usa esto cuando:

• la calidad de recuperación más alta importa más que la latencia.
• la conversación contiene una configuración importante al principio del hilo.

Timeout recomendado:

• auméntalo de forma considerable en comparación con message o recent.
• empieza alrededor de 15000 ms o más, dependiendo del tamaño del hilo.

En general, el timeout debe aumentar según el tamaño del contexto:

message < recent < full

Persistencia de transcripciones

Las ejecuciones del sub-agent de memoria bloqueante de Active Memory crean una transcripción session.jsonl real durante la llamada al sub-agent.

Por defecto, esa transcripción es temporal:

• se escribe en un directorio temporal y se usa solo para la ejecución del sub-agent de memoria bloqueante.
• se elimina inmediatamente después de que la ejecución termina.

Si quieres mantener esas transcripciones del sub-agent en el disco para depuración o inspección, activa la persistencia explícitamente:

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          persistTranscripts: true,
          transcriptDir: "active-memory",
        },
      },
    },
  },
}

Cuando está activada, Active Memory guarda las transcripciones en un directorio separado bajo la carpeta de sesiones del agent objetivo, no en la ruta principal de transcripción de la conversación del usuario.

El diseño conceptual es:

agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl

Puedes cambiar el subdirectorio relativo con config.transcriptDir.

Usa esto con cuidado:

• las transcripciones del sub-agent pueden acumularse rápido en sesiones activas.
• el modo de consulta full puede duplicar mucho contexto de la conversación.
• estas transcripciones contienen contexto de prompt oculto.
• incluyen memorias recuperadas que podrían ocupar espacio extra.

Configuración

Toda la configuración de active memory se encuentra en:

plugins.entries.active-memory

Los campos más importantes son:

Clave	Tipo	Significado
enabled	boolean	Habilita el plugin
config.agents	string[]	IDs de agentes que pueden usar active memory
config.model	string	Referencia opcional al modelo del sub-agente de blocking memory; si no se define, usa el modelo de la sesión actual
config.queryMode	"message" | "recent" | "full"	Controla cuánta conversación ve el sub-agente de blocking memory
config.promptStyle	"balanced" | "strict" | "contextual" | "recall-heavy" | "precision-heavy" | "preference-only"	Controla qué tan proactivo o estricto es el sub-agente de blocking memory al decidir si devuelve memoria
config.thinking	"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "adaptive"	Ajuste avanzado de pensamiento para el sub-agente de blocking memory; por defecto off para mayor velocidad
config.promptOverride	string	Reemplazo completo del prompt; no se recomienda para uso normal
config.promptAppend	string	Instrucciones extra añadidas al prompt por defecto o al personalizado
config.timeoutMs	number	Tiempo de espera máximo para el sub-agente de blocking memory
config.maxSummaryChars	number	Máximo de caracteres permitidos en el resumen de active-memory
config.logging	boolean	Emite logs de active memory mientras ajustas la configuración
config.persistTranscripts	boolean	Mantiene las transcripciones del sub-agente de blocking memory en el disco en lugar de borrar archivos temporales
config.transcriptDir	string	Directorio relativo para las transcripciones del sub-agente de blocking memory bajo la carpeta de sesiones del agente

Campos útiles para el ajuste:

Clave	Tipo	Significado
config.maxSummaryChars	number	Máximo de caracteres permitidos en el resumen de active-memory
config.recentUserTurns	number	Turnos previos del usuario a incluir cuando queryMode es recent
config.recentAssistantTurns	number	Turnos previos del asistente a incluir cuando queryMode es recent
config.recentUserChars	number	Máximo de caracteres por turno del usuario
config.recentAssistantChars	number	Máximo de caracteres por turno del asistente
config.cacheTtlMs	number	Reutilización de caché para consultas idénticas repetidas

Configuración recomendada

Empieza con recent.

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          logging: true,
        },
      },
    },
  },
}

Si quieres inspeccionar el comportamiento en vivo mientras haces ajustes, usa /verbose on en la sesión en lugar de buscar un comando de depuración de active-memory por separado.

Después, puedes cambiar a:

• message si buscas menor latencia
• full si decides que el contexto extra vale la pena a pesar de que el sub-agente de blocking memory sea más lento

Depuración

Si la active memory no aparece donde esperas, te recomiendo revisar estos puntos:

1. Confirma que el plugin esté habilitado en plugins.entries.active-memory.enabled.
2. Confirma que el agent id actual aparezca en config.agents.
3. Asegúrate de estar probando a través de una sesión de chat interactiva y persistente.
4. Activa config.logging: true y revisa los logs del gateway.
5. Verifica que la búsqueda de memoria funcione con openclaw memory status --deep.

Si los resultados de memoria tienen demasiado ruido, ajusta este parámetro:

• maxSummaryChars

Si la active memory es demasiado lenta, prueba lo siguiente:

• Baja el queryMode
• Baja el timeoutMs
• Reduce el conteo de turnos recientes
• Reduce los límites de caracteres por turno

Páginas relacionadas

• Memory Search
• Memory configuration reference
• Plugin SDK setup