Ciclo de vida de la memoria y la carga útil

ZeroClaw lleva varios tipos de información “recordada” durante un turno. No todas tienen el mismo propietario, durabilidad, límite de privacidad o riesgo de revisión.

Usa esta página cuando un cambio afecte a la memoria, el historial, la persistencia de la sesión, los resultados de herramientas, los archivos, los adjuntos de medios, los resúmenes, el recorte de contexto o el ensamblado del prompt. La pregunta más importante no es “¿recuerda esto el agente?”, sino “¿qué superficie es propietaria de estos datos y cuánto tiempo viven?”

Qué posee qué

Superficie	Propietario	Durabilidad	Qué deben comprobar los revisores
Memoria a largo plazo	`zeroclaw-memory` detrás de `Arc<dyn Memory>`	Específico del backend: SQLite/Postgres/Lucid/Qdrant/almacenes compartidos, o archivos Markdown por agente	Los almacenamientos y los recuerdos deben permanecer delimitados por agente. El resultado de una herramienta, una línea de registro o una fila de sesión no es memoria a largo plazo a menos que haya ocurrido una escritura de memoria.
Memoria de relación	`knowledge` tool y grafo de conocimiento	Backend de gráficos, cuando está habilitado	La captura es explícita. Habilitar el grafo no ingiere automáticamente conversaciones, archivos ni datos de canal.
Historial de sesiones	`zeroclaw-infra` backends de sesión, almacén ACP y mapas RPC/sesión en vivo	El historial de Chat/ACP puede persistir; los handles RPC en vivo son locales al proceso	El historial conserva la continuidad de la conversación. No es el almacén canónico para las preferencias del usuario, la configuración ni los archivos.
Contexto actual del prompt	Ensamblaje del prompt del bucle del agente	Solicitud de proveedor efímero	La memoria recuperada, RAG de hardware, la entrada actual, el prompt del sistema, las habilidades y los resultados de herramientas pueden enviarse al proveedor. Esto no los hace duraderos.
Recorte del historial	`agent::history` y `agent::history_trim`	Cambio con pérdida en la forma del historial de solicitudes/sesiones	El recorte debe ser visible, preservar el emparejamiento de llamada de herramienta/resultados de herramienta y evitar fingir que el contexto antiguo sigue disponible.
Cargas útiles de resultados de herramientas	`ToolResult`, `ToolResultMessage` y el despachador de herramientas	Turno actual y cualquier historial de sesión persistente que registre el turno	Tamaño acotado y procedencia. Las salidas grandes deben limitarse o resumirse de forma intencional; la promoción de rutas de imágenes solo debe ocurrir para herramientas que producen archivos, no para herramientas que solo enumeran rutas.
Archivos y espacios de trabajo	Política de seguridad del espacio de trabajo por agente	Los archivos persisten según el sistema de archivos, no la memoria	El contenido de los archivos no es memoria solo porque una herramienta los haya leído. Las escrituras pertenecen al espacio de trabajo del agente, a menos que la política permita explícitamente más.
Adjuntos multimedia	Canal/pasarela de la canalización de medios y `MediaAttachment`	Carga de entrada por defecto; la persistencia depende de la ruta de recepción	Los bytes sin procesar deben permanecer acotados y con la ruta validada. Almacena resúmenes o referencias deliberadamente en lugar de copiar medios silenciosamente en memoria.
Registros y eventos de observador	`zeroclaw-log`, `ObserverEvent`, traza de ejecución	Rastreo opcional en tiempo de ejecución y observadores en vivo	Los registros son evidencia y diagnóstico, no memoria fuente de verdad. Depura o limita los cargas útiles de usuario/herramienta antes de registrarlas.
Registros de costo y uso	Seguimiento de costos y eventos de uso del proveedor	Libro mayor de costos cuando está habilitado	Los registros de uso describen las llamadas al modelo. No deben incluir cuerpos de prompt, salidas de herramientas ni contenidos de memoria.

Esta tabla complementa Estado en tiempo de ejecución y persistencia. Esa página indica dónde reside el estado; esta página indica cómo las cargas útiles orientadas al usuario se mueven a través de la memoria, el historial, las herramientas, los archivos, el contenido multimedia y las solicitudes al proveedor.

Memoria a largo plazo

Un agente recibe su identificador de memoria de la fábrica de memoria. Los backends compartidos y el almacenamiento Markdown tienen disposiciones concretas diferentes, pero la regla de revisión es la misma: el acceso a la memoria debe permanecer vinculado a la identidad del agente y a la lista de अनुमति de pares configurada descrita en Runtime internals.

Hay dos formas normales en que la información se convierte en memoria duradera:

el agente llama a una herramienta de memoria como memory_store;
el código en tiempo de ejecución almacena explícitamente una entrada de memoria, como la ruta de autoguardado de la conversación configurada.

No trates el contexto del prompt, la salida de herramientas, los archivos ni los registros como memoria duradera de forma predeterminada. Un PR que haga persistente una de esas superficies debe nombrar la categoría de memoria, el alcance de sesión, el alcance de agente, el comportamiento de retención y el control visible para el operador.

Contexto y recuerdo

Al inicio del turno, el runtime puede recuperar recuerdos relevantes e inyectar un bloque acotado de [Memory context] en el contexto del prompt visible para el usuario. Los puntos de entrada relacionados no aplican todos los mismos filtros. El bucle de canal/interactivo filtra ruido de guardado automático generado, bloques <tool_result> obsoletos y entradas de Conversation cuando el turno no tiene un ámbito de sesión seguro o no está iniciado por el usuario. La carga genérica de memoria filtra ruido de guardado automático y relevancia, pero por sí sola no impone esa exclusión de Conversation del bucle de canal.

La solicitud del proveedor puede, por tanto, contener memoria recuperada sin convertir el turno actual en una memoria nueva. Revisa los cambios en la ensamblación del prompt preguntando:

qué backend de memoria y alcance del agente se consultaron;
si la consulta está delimitada por sesión cuando se permiten entradas de conversación;
si el ruido de autoguardado, los bloques de resultados de herramientas obsoletos y las entradas de baja relevancia siguen filtrados;
si el usuario o el operador pueden ver cuándo se eliminó el contexto anterior.

Historial de sesión y recorte

El historial de sesión es el registro de continuidad de una conversación. Puede incluir mensajes de chat, llamadas de herramientas del asistente y resultados de herramientas. No es lo mismo que la memoria a largo plazo.

Gestión del historial se encarga de la mecánica de recorte. Esta página solo nombra el límite del ciclo de vida: el recorte es un cambio con pérdida en el contexto visible para el proveedor y la sesión, no una eliminación de memoria, y debe ser visible en lugar de fingir silenciosamente que el contexto antiguo sigue disponible.

La correspondencia entre llamadas de herramienta importa más que el ahorro de bytes. Un cambio en el historial no debe dejar una solicitud al proveedor con un tool_use huérfano sin el tool_result correspondiente, ni al revés.

Resultados de la herramienta

Las herramientas devuelven un pequeño resultado estructurado: success, output y error. El despachador convierte esos resultados en mensajes del proveedor para la siguiente llamada del modelo, mientras que los clientes en streaming pueden recibir eventos correlacionados de ToolCall y ToolResult durante el turno.

Las cargas útiles de resultados de herramientas son fáciles de sobreconservar. Los revisores deben comprobar:

tamaño máximo del resultado, incluyendo max_tool_result_chars;
si la truncación preserva los envoltorios estructurados y los marcadores de imagen;
si las herramientas de búsqueda/listado evitan convertir rutas de imágenes incidentales en cargas multimedia;
si los recibos, registros y eventos de observador contienen evidencia limitada y depurada en lugar de salida sensible en bruto;
si el resultado está solo en el historial de la sesión/turno actual o si también se escribe intencionalmente en la memoria.

Si un PR dice que el resultado de una herramienta está “recordado”, exija que indique si eso significa historial visible para el proveedor, historial de sesión persistido, una fila en el backend de memoria, un artefacto de archivo, un recibo o un evento de registro.

Archivos y multimedia

Los contenidos de los archivos y los bytes de medios son cargas útiles, no memorias. El propietario del filesystem es la política de espacio de trabajo por agente descrita en Filesystem components y Runtime internals. Una lectura de archivo puede colocar contenido en un resultado de herramienta o en un prompt; una escritura de archivo puede crear estado duradero en el filesystem; ninguna crea automáticamente una fila de memoria.

Los mensajes del canal de entrada pueden transportar valores MediaAttachment con un nombre de archivo, bytes y un tipo MIME opcional. MediaKind se deriva del tipo MIME o de la extensión del archivo. El cargador de adjuntos de bajo nivel lee las rutas proporcionadas por el llamador literalmente, por lo que los llamadores que aceptan rutas no confiables deben validar o restringir esas rutas antes de cargar.

Para archivos y contenido multimedia, los revisores deben buscar:

aplicación de políticas del espacio de trabajo antes de lecturas y escrituras;
validación de la ruta cuando una ruta provenía de un usuario, una solicitud HTTP, una carga útil de canal o un argumento de herramienta;
manejo de bytes acotados y comportamiento claro de fallo para archivos faltantes o ilegibles;
resúmenes explícitos o referencias cuando cargas grandes/binarias entran en los prompts;
no copiar en silencio el contenido del archivo o adjunto a la memoria a largo plazo.

Registros y observabilidad

Los eventos de observador y los registros de ejecución ayudan a explicar lo que ocurrió. No deben convertirse en almacenes de cargas útiles ocultas. Los eventos de recuperación de memoria llevan un resumen de consulta depurado/truncado y conteos. Los eventos de almacenamiento de memoria llevan identificadores acotados de categoría y backend.

La observabilidad de llamadas a herramientas requiere cuidado adicional porque los destinos no comparten un único contrato de carga útil. Los eventos tipados actuales del observador de llamadas a herramientas pueden transportar argumentos completos y la salida completa del resultado depurada de credenciales, y OTel reenvía esos valores a los atributos del span. No describas esa ruta como “resúmenes” salvo que el código realmente acote o resuma eso. La nueva telemetría debería preferir identificadores acotados, conteos, duraciones, indicadores de éxito y resúmenes útiles para el operador. Pon el contenido en bruto en los registros o en los eventos del observador solo cuando la función lo requiera explícitamente y el límite de privacidad esté documentado.

Lista de verificación para revisores

Para cambios de memoria, payload, historial, archivo o medios, responda a estas preguntas antes de la aprobación del revisor:

¿Cuál es el propietario canónico de los datos?
¿Es solo del turno actual, persistente en la sesión, persistente en el sistema de archivos, persistente en memoria o persistente en los registros?
¿Qué agente, sesión, canal o ámbito de espacio de trabajo limita el acceso?
¿Puede un llamador ampliar el recuerdo de memoria más allá de la allowlist configurada?
¿Pueden los trabajos autónomos ver la memoria de conversación originada en el chat?
¿Qué limita la salida de la herramienta, los bytes de archivo, los bytes de medios y el tamaño del prompt?
¿Recortar o truncar hace que la pérdida sea visible en lugar de silenciosa?
¿Las cargas útiles visibles para el proveedor están separadas de las escrituras duraderas en memoria?
¿Se depuran y se acotan los registros y los eventos del observador?
Si la PR cambia una carga útil generada o derivada, ¿actualiza al propietario de origen en lugar de editar manualmente la salida generada?

Punteros de origen

Documentación canónica:

Puntos de entrada clave del código:

Traza de memoria y forma de entrada: crates/zeroclaw-api/src/memory_traits.rs
Fábrica de memoria y ámbito del agente: crates/zeroclaw-memory/src/lib.rs, crates/zeroclaw-memory/src/agent_scoped.rs y crates/zeroclaw-memory/src/agent_scoped_markdown.rs
Registro y ejemplos de herramientas de memoria: crates/zeroclaw-tools/src/lib.rs (MEMORY_TOOL_NAMES), crates/zeroclaw-tools/src/memory_store.rs y crates/zeroclaw-tools/src/memory_recall.rs
Recordatorio e inyección: crates/zeroclaw-runtime/src/agent/memory_inject.rs (política de recordatorio más el renderizador de [Memory context]), inyectado del lado del motor en crates/zeroclaw-runtime/src/agent/turn/mod.rs; el identificador de memoria por turno se transmite a través de crates/zeroclaw-runtime/src/agent/loop_.rs
Recorte del historial y estructuración de la carga útil de resultados de herramientas: crates/zeroclaw-runtime/src/agent/history.rs, crates/zeroclaw-runtime/src/agent/history_trim.rs y crates/zeroclaw-runtime/src/agent/turn/results_collect.rs
Formas de mensajes de herramientas y proveedores: crates/zeroclaw-api/src/tool.rs y crates/zeroclaw-api/src/model_provider.rs
Adjuntos del canal: crates/zeroclaw-api/src/channel.rs y crates/zeroclaw-api/src/media.rs

Keyboard shortcuts

ZeroClaw Docs