Lab Notes
Agents

Memory and Context

Cómo recuerda el lab. El memory model: long-term curated memory, daily logs y las rules de qué va dónde.

Propósito

Esta página documenta el memory model del lab. El Coordinator es el dueño de la memory layer; esta página es la referencia canónica para la estructura, las policies y los boundaries.

El memory model tiene tres layers:

  1. Long-term memory (MEMORY.md) — curated, durable facts.
  2. Daily logs (memory/YYYY-MM-DD.md) — raw chronological record.
  3. Session context — el in-memory state de la sesión actual.

Más dos derived layers que forman parte del mismo ecosystem:

  1. Skill artifacts (SKILL.md, TOOL.md) — capabilities que el agent activa.
  2. Project notes — per-project context que el agent puede recall bajo demanda.

Los layers son complementary, not redundant. Cada uno tiene un propósito; mezclarlos genera confusión.

Long-term memory (MEMORY.md)

MEMORY.md es la curated long-term memory del lab. Es la destilación de todo lo que el lab ha aprendido y que vale la pena guardar.

Properties

  • Single file. Un MEMORY.md por agent (el main agent tiene uno; los specialized agents tienen el suyo o ninguno).
  • Loaded only in the main session. El fichero es sensible (puede contener personal context) y nunca se carga en shared o group contexts.
  • Editable freely in main sessions. El Coordinator puede leer, editar y actualizar MEMORY.md cuando el usuario lo pide.
  • Curated, not raw. Solo la esencia destilada va aquí, no el raw daily log.

What goes in

  • Decisiones significativas y su rationale.
  • Datos importantes sobre el lab (specs de la máquina, ports, paths, conventions).
  • Lessons learned de errores pasados.
  • Identity y relationship information (el user-agent bond).
  • Long-term preferences y policies.

What does NOT go in

  • Raw daily logs (van en memory/YYYY-MM-DD.md).
  • Secrets, credentials o API keys.
  • Planes in-progress o especulativos.
  • Session-specific state (usar el session context para eso).

Maintenance

MEMORY.md lo mantiene el Coordinator. El Coordinator:

  • Lee MEMORY.md al principio de cada sesión.
  • Escribe en MEMORY.md cuando se aprende un significant fact.
  • Periódicamente destila daily logs en MEMORY.md y elimina entries outdated.
  • Actualiza MEMORY.md para reflejar el current state del sistema (p. ej., cambios de modelo, cambios de port).

El Coordinator nunca edita MEMORY.md en shared contexts. El fichero es para la main session solo.

Daily logs (memory/YYYY-MM-DD.md)

Los daily logs son el raw chronological record de lo que ocurrió en el lab en un día dado. Un fichero por día.

Properties

  • One file per day. El nombre es memory/YYYY-MM-DD.md (fecha UTC).
  • Append-only. Los daily logs son historical records; el Coordinator no los edita después de que termina el día.
  • Loaded on demand. El Coordinator lee el daily log del día actual al principio de cada sesión y logs más antiguos cuando hace falta.
  • Not curated. Los daily logs son raw notes; la destilación a MEMORY.md ocurre periódicamente.

What goes in

  • Decisiones tomadas y su context.
  • Errores encontrados y cómo se resolvieron.
  • Tasks completadas (y cómo).
  • Lessons learned (pueden moverse luego a MEMORY.md).
  • Cualquier cosa que el usuario haya pedido explícitamente recordar.

What does NOT go in

  • Secrets o credentials.
  • Outputs de procesos long-running (usar artefacto files para eso).
  • Code snippets de más de unas pocas líneas (usar una referencia al fichero).

Retention

Los daily logs se guardan indefinidamente por defecto. El Coordinator se puede configurar para archivar logs de más de un año en un directorio separado.

Session context

El session context es el in-memory state de la sesión actual. Se crea cuando arranca la sesión y se descarta cuando termina.

Properties

  • In-memory. No se persiste a disco (a menos que el usuario lo pida explícitamente).
  • Per-session. Cada sesión tiene su propio context.
  • Loaded with the session. El Coordinator lee el context al principio de cada sesión.

What goes in

  • La task actual y su state.
  • Variables y parámetros de trabajo in-flight.
  • Conversation history dentro de la sesión.
  • Cached tool results (durante la sesión).

What does NOT go in

  • Cualquier cosa que deba sobrevivir la sesión (usar daily logs o MEMORY.md).
  • Datos sensibles que el usuario no quiere en memoria.

Skill artifacts

Los skill artifacts son los ficheros que describen una capability que el agent puede activar. Forman parte del memory ecosystem pero se cargan on demand, no al arranque de la sesión.

SKILL.md

Un fichero SKILL.md describe un skill. Tiene:

  • Un name y una description.
  • Una lista de trigger phrases (cuándo usar el skill).
  • Un workflow (cómo usar el skill).
  • Una lista de inputs y outputs.

El Coordinator activa un skill cuando la request del usuario matchea las trigger phrases del skill. La activación carga las instrucciones del skill en el session context.

TOOL.md

Un fichero TOOL.md describe una tool. Es similar a SKILL.md pero para tools (commands que el agent puede invocar). El Coordinator carga el TOOL.md cuando necesita usar la tool.

La estructura de un TOOL.md está documentada en Tool Spec.

Project notes

Las project notes son per-project context que el agent puede recall bajo demanda. Viven bajo {workspace-root}/{project}/.

Properties

  • Per-project. Un set de notes por proyecto.
  • Loaded when the project is active. El Coordinator carga las notes cuando el usuario pregunta por el proyecto o cuando el Coordinator empieza a trabajar en el proyecto.
  • Editable freely. El Coordinator puede actualizar las notes según evoluciona el proyecto.

What goes in

  • Architecture decisions específicas del proyecto.
  • Conventions y patterns específicos del proyecto.
  • Pitfalls y lessons learned específicos del proyecto.
  • Configuration específica del proyecto.

What does NOT go in

  • Información que pertenece al MEMORY.md del lab.
  • Raw daily logs (usar el daily log para eso).

Memory boundaries

Los boundaries entre los layers son:

LayerScopeLifetimeEditable freely?
MEMORY.mdLab-wideIndefiniteYes (main session only)
Daily logsDayIndefiniteAppend-only
SessionSessionSessionYes (in-memory)
SkillCapabilitySkill-definedYes
Project notesProjectProject-definedYes

Un fact pertenece exactamente a un layer. La regla heurística:

  • ¿Es un durable fact sobre el lab? → MEMORY.md.
  • ¿Es un chronological record de lo que ocurrió? → Daily log.
  • ¿Es relevante solo para esta sesión? → Session context.
  • ¿Es sobre una capability? → Skill artifact.
  • ¿Es sobre un proyecto? → Project notes.

El Coordinator puede buscar en la memory layer. La búsqueda es semántica y devuelve los snippets más relevantes. El Coordinator usa la búsqueda para:

  • Recordar facts que el usuario mencionó en sesiones pasadas.
  • Encontrar la project note relevante para una pregunta.
  • Encontrar el skill relevante para una request.

La búsqueda la hace la tool memory del framework. El inventario completo de tools está en Tooling Layer.

Memory hygiene

El Coordinator sigue unas pocas rules para mantener saludable la memory layer:

  • One fact, one place. Evitar duplicar facts entre layers.
  • Cite sources. Al registrar un fact, citar de dónde viene (file, line, session).
  • Date everything. Cada entry en un daily log va fechado; cada entry en MEMORY.md lleva timestamp.
  • Prune regularly. Eliminar periódicamente entries outdated de MEMORY.md y daily logs antiguos.
  • Never store secrets. Si hace falta un secret, guardar una referencia al secret manager, no el secret en sí.

See also

Previous

Web Agent

Next

Context Boundaries

On this page