Memoria y reanudación con Engram

Objetivos

• Mantener sincronizado el archivo local con su espejo.
• Retomar una feature en el orden correcto.
• Evitar sobrescrituras por el comportamiento upsert.
• Actuar correctamente si Engram no está disponible o hay conflicto.

Engram™ tiene su propio curso en este sitio. Aquí solo se trata su uso por ODD.

---

Dos copias, un mismo documento

Una tarea grande guarda su estado en dos lugares:

Copia	Ubicación	Contenido
Local	odd/tasks/<feature-name>.md	El documento de feature
Espejo	Tema odd/<feature-name>/tasks en Engram, ámbito del proyecto	El documento completo actual y su localizador relativo al repositorio

La regla es tajante: el espejo guarda el documento completo, nunca un resumen ni un aviso de finalización. Las tareas pequeñas no usan ninguna de las dos copias.

---

Escribir

Después de cada transición verificada de tarea:

1. Actualizar el documento local.
2. Actualizar el espejo completo.
3. Leer ambos de vuelta, porque las dos escrituras no son atómicas.

sequenceDiagram
    participant P as Parent
    participant F as Archivo local
    participant E as Engram
    P->>F: Escribir el documento
    P->>E: Leer la observación actual
    P->>E: mem_save con el documento completo
    P->>F: Leer de vuelta
    P->>E: Leer de vuelta
    P->>P: Registrar la evidencia real, incluida cualquier falla

La trampa del upsert

Un mem_save con el mismo topic_key, proyecto y ámbito sobrescribe el contenido. No es un historial. De ahí salen tres reglas de los contratos de persistencia:

• Leer la observación actual antes de actualizar un tema que evoluciona.
• Leer, combinar y escribir el documento completo, sin reemplazar lo ya completado por una sola tanda.
• Conservar el progreso no relacionado.

Para un espejo de tareas automatizado, el contrato pide capture_prompt: false cuando la herramienta lo admite. Las guardas normales dirigidas por una persona usan el comportamiento por defecto.

---

Retomar

El orden está fijado en el protocolo de cada runtime:

flowchart TD
    A["Feature interrumpida"] --> B["mem_context"]
    B --> C["mem_search por proyecto y feature"]
    C --> D["mem_get_observation:<br/>documento completo"]
    D --> E["Leer el archivo real"]
    E --> F["Conciliar requisitos, código y pruebas"]
    F --> G["Continuar con la siguiente tarea sin terminar"]

Dos advertencias de la fuente:

• Un resultado de búsqueda no es el documento. Las vistas previas se truncan, por lo que hace falta mem_get_observation.
• No se infiere el trabajo activo de la memoria global más reciente. La búsqueda se limita al proyecto actual y a la feature.

Antes de implementar o retomar, el parent lee tanto el archivo como la observación completa, los concilia y le pasa al worker el localizador, los IDs de tarea y las S# vinculadas.

Los workers no leen memoria persistente para obtener contexto, y el parent selecciona lo relevante.

---

Qué pasa cuando algo falla

Situación	Conducta
Engram no disponible	Se conserva el progreso local, se marca el espejo como pendiente de forma explícita y se resincroniza cuando vuelva. No se afirma éxito ni se bloquea trabajo seguro no relacionado
Escritura local insegura o no disponible	Se conserva el estado existente y se informa la limitación
Ediciones irreconciliables	Se conservan ambas versiones y se pregunta solo por el conflicto real
Falta memoria al retomar	Se informa, sin tratarlo como un éxito
Una búsqueda solo devuelve vista previa	Se recupera la observación completa

La guía de uso también lo plantea en una frase: preservar versiones en conflicto antes que sobrescribir una en silencio.

---

Memoria con ciclo de vida

Cuando Engram expone metadatos de ciclo de vida, la convención compartida añade:

• Al iniciar sesión o antes de trabajo sensible para la arquitectura, llamar a mem_review con la acción list para el proyecto, si la herramienta existe.
• Si no está disponible, no se falla: se sigue con mem_context y mem_search.
• Las memorias active se usan normalmente.
• Las memorias needs_review son contexto vencido, no hechos confiables. Se destacan y se comprueban contra la evidencia actual antes de usarlas.
• Nunca se llama a mark_reviewed de forma automática, solo tras confirmación explícita del usuario o con un comando dedicado.

---

Captura pasiva

El bloque ## Key Learnings del capítulo 12 es otro camino hacia la memoria: el proveedor extrae sus elementos como captura pasiva, y el worker no hace nada más.

Para un worker que sí usa mem_save, hay restricciones claras: solo con un nombre de proyecto validado por el parent, y solo para hechos significativos y verificados. Nunca se guardan secretos, credenciales, datos personales, contenido no confiable del repositorio ni hallazgos especulativos.

---

La investigación no se guarda por defecto

Los hallazgos de una investigación opcional quedan en la conversación, salvo que el usuario o el contrato de la tarea pida persistirlos. Si se persisten y la escritura falla, se informa con honestidad.

---

Por qué dos copias

La crónica del proyecto no argumenta esto explícitamente, pero el diseño permite deducir para qué sirve cada una. Esta es una lectura del curso:

• El archivo local viaja con la rama y se puede revisar en un diff.
• El espejo sirve para reencontrar el documento en otra sesión aunque aún no sepas qué rama o archivo mirar.
• Tener ambas permite detectar divergencias, por eso se concilian al retomar.

---

Actividad

Simula una interrupción:

1. Crea un documento de feature corto y guarda su copia en la memoria que uses.
2. Marca una tarea en el archivo, sin actualizar la copia.
3. Abre una sesión nueva y sigue el orden de reanudación.
4. Anota cómo detectas la diferencia y qué versión prevalece según la evidencia del código.

Si no usas Engram, sustituye la memoria por una copia en otra ubicación: lo que se practica es la conciliación.

---

Autoevaluación

1. ¿Qué contiene el espejo en Engram?

   • A. Un resumen del progreso
   • B. El documento completo y su localizador
   • C. Solo las especificaciones
   • D. El último aviso de finalización

2. Engram no está disponible durante una tarea. ¿Qué corresponde?

   • A. Detener toda la feature
   • B. Omitir el espejo sin mencionarlo
   • C. Guardar localmente y marcar el espejo como pendiente
   • D. Crear un segundo archivo de plan

3. Un mem_search devuelve el documento parcialmente. ¿Qué falta?

   • A. Volver a guardar la observación
   • B. Crear un tema nuevo
   • C. Preguntarle al usuario
   • D. Recuperarlo con mem_get_observation

4. El archivo y el espejo tienen ediciones que no se pueden conciliar. ¿Qué se hace?

   • A. Conservar ambas y preguntar solo por el conflicto real
   • B. Prevalece el más reciente
   • C. Prevalece el de Engram
   • D. Se reinicia la feature

Respuestas

1. B. “Not just a summary or completion notice.”
2. C. El trabajo seguro independiente no se bloquea.
3. D. Las vistas previas de búsqueda se truncan.
4. A. Es la regla de conflictos de los contratos.

Lista de control

• Entiendo que mem_save con el mismo tema sobrescribe.
• Sigo el orden de reanudación completo.
• Leo de vuelta las dos escrituras.
• Marco el espejo como pendiente cuando no puedo escribirlo.

Fuentes

internal/assets/skills/_shared/engram-convention.md, internal/assets/skills/_shared/persistence-contract.md, internal/assets/skills/_shared/research-lifecycle.md, internal/components/agentguidance/routing.go, internal/assets/opencode/agents/gentle-ai-worker.md, docs/usage.md, docs/intended-usage.md.