Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-010 title: Separar el historial de conversaciones, la memoria curada y la autoridad de enriquecimiento date: 2026-07-19 status: propuesta relates-to:

  • ADR-005
  • docs/book/src/foundations/fnd-002-documentation-standards.md
  • docs/book/src/architecture/memory-payload-lifecycle.md
  • https://github.com/zeroclaw-labs/zeroclaw/issues/9048
  • https://github.com/zeroclaw-labs/zeroclaw/issues/9103
  • https://github.com/zeroclaw-labs/zeroclaw/issues/6850
  • https://github.com/zeroclaw-labs/zeroclaw/pull/9072
  • crates/zeroclaw-api/src/memory_traits.rs
  • crates/zeroclaw-memory
  • crates/zeroclaw-infra/src/session_backend.rs
  • crates/zeroclaw-infra/src/session_store.rs
  • crates/zeroclaw-infra/src/acp_session_store.rs

ADR-010: Separar el historial de conversaciones, la memoria curada y la autoridad de enriquecimiento

Contexto

ADR-005 registra un contrato de memoria duradera independiente del backend con SQLite como valor predeterminado. No decide qué datos recordados pertenecen a la memoria duradera ni si una integración de memoria externa es otro almacén autoritativo.

Las rutas actuales de tiempo de ejecución, puerta de enlace y canal pueden conservar los turnos de conversación tanto en los almacenes de sesión como en entradas de MemoryCategory::Conversation. Esto hace que una misma transcripción tenga dos posibles propietarios, con comportamientos diferentes de retención, recuperación, exportación, eliminación y alcance. Una fila antigua de conversación también puede volver a aparecer en un prompt posterior como si fuera conocimiento entre sesiones seleccionado.

Las integraciones externas crean el riesgo de una segunda fuente de autoridad. Un conector puede mejorar la búsqueda o proporcionar contexto derivado, pero tratar su índice como otro almacén persistente permite que el estado del conector, las interrupciones o un alcance menos estricto compitan con los datos canónicos de ZeroClaw.

Los RFC aceptados #9048 y #9103 resuelven estas cuestiones conjuntamente. Este registro amplía ADR-005 sin reescribirlo: el contrato Memory independiente del backend y el valor predeterminado de SQLite siguen siendo válidos, mientras que este ADR asigna por separado la autoridad sobre el historial de sesiones, la memoria curada y el enriquecimiento.

Decisión

El historial de conversaciones garantiza la continuidad

El almacén de sesiones de chat, canal, gateway o ACP aplicable es la fuente autoritativa para la continuidad de la conversación. La persistencia automática de transcripciones corresponde a ese almacén de sesiones y preserva la estructura de mensajes necesaria para una reanudación segura, incluido el emparejamiento de llamadas a herramientas y resultados de herramientas donde sea compatible.

El historial de sesión preserva cada límite de sesión, agente, tenant y principal aplicable. No es conocimiento entre sesiones de forma automática. Recortar el historial modifica el contexto visible para la sesión y para el proveedor; eliminar la memoria curada no elimina el historial de sesión.

Cuando la entrada actual o el historial de sesión entra en conflicto con la memoria curada, la entrada actual y el historial de sesión rigen el turno. La memoria curada no debe reescribir, reemplazar ni anular ese registro de continuidad.

La memoria curada gestiona el conocimiento seleccionado entre sesiones

La memoria a largo plazo seleccionada por el agente contiene hechos, preferencias, decisiones, convenciones y procedimientos aprendidos seleccionados que se conservan intencionadamente entre sesiones. Las escrituras deben ser deliberadas o producirse mediante una política explícita y acotada de consolidación, conservar una procedencia útil y mantener todos los límites aplicables del agente, la sesión, el inquilino y el principal.

La memoria curada utiliza el contrato Memory agnóstico al backend de ADR-005. Un backend configurado es el almacén duradero autoritativo para esa memoria. El ensamblado de prompts, la consolidación, la gobernanza y la retroalimentación siguen siendo preocupaciones de política de ciclo de vida por encima de la implementación de almacenamiento; la issue #6850 hace seguimiento de ese límite.

Este ADR no decide si el Markdown por agente es la representación canónica de memoria curada visible para el operador o una proyección de otro backend configurado. Eso sigue siendo una decisión de implementación independiente; no se puede introducir implícitamente una segunda autoridad duradera.

Las sesiones de ACP/Code, incluido el panel ACP de ZeroCode, permanecen aisladas de la inyección automática de memoria a largo plazo. Los paquetes de conocimiento y la generación aumentada por recuperación son fuentes de contexto deliberadas y separadas; no reactivan la memoria curada para dichas sesiones de Code.

El enriquecimiento es un derivado reconstruible

Un MemoryEnricher es un derivado opcional y de mejor esfuerzo del almacén autoritativo de memoria curada, no otra fuente de verdad. El almacén autoritativo confirma primero. Un error del conector, un tiempo de espera agotado, una salida con formato incorrecto o un estado obsoleto no pueden invalidar una escritura correcta en el almacén autoritativo ni hacer que la recuperación desde el almacén autoritativo deje de estar disponible.

El límite de enriquecimiento compartido posee la política independiente del conector: capacidades declaradas, alcance del llamador y del agente, comportamiento de fallo acotado, orden de fusión determinista y cualquier rehidratación de fila canónica necesaria para rechazar resultados obsoletos, reemplazados o de un agente incorrecto. El contexto derivado del conector se aísla como no confiable antes de volverse visible para el modelo.

Las nuevas escrituras automáticas de transcripciones no deben reenviarse a un conector de enriquecimiento. La política de migración debe definir explícitamente cualquier manejo del lado del conector de las filas heredadas de MemoryCategory::Conversation, evitar que esos derivados se recuperen como memoria curada y proporcionar orientación de limpieza o reconstrucción. Un futuro índice de historial de sesiones requiere su propia decisión explícita de autoridad, privacidad, retención y alcance; no puede llegar de forma implícita a través de la unión de memoria curada.

La primera implementación puede seguir siendo específica de SQLite. La generalización del enriquecimiento sobre otros almacenes duraderos espera un segundo consumidor concreto en lugar de hacer que cada backend adopte las suposiciones de un conector.

Las filas de conversación heredadas requieren una transición explícita

Los datos existentes de MemoryCategory::Conversation son un estado de compatibilidad, no la autoridad futura para las transcripciones. La migración debe preservar la reversión y evitar la eliminación silenciosa. Las implementaciones pueden mantener lecturas de compatibilidad, migrar los turnos recuperables al almacén de sesiones correcto, promover deliberadamente hechos duraderos seleccionados a la memoria curada, o expirar filas según reglas de retención documentadas.

Ninguna implementación puede tratar la promoción masiva de transcripciones a memoria curada como comportamiento predeterminado. La promoción es una decisión acotada y consciente de la procedencia, no una conversión de formato de almacenamiento.

Controles de aceptación

Este ADR permanece propuesto hasta que se cumplan todas estas condiciones:

  • Las nuevas escrituras automáticas de transcripción utilizan almacenes de sesión canónicos en las rutas de tiempo de ejecución, gateway, canal y ACP cubiertas;
  • la memoria curada no puede anular la entrada actual ni el historial de sesión que entren en conflicto, y el aislamiento de memoria automática de ACP/Code se mantiene aplicado;
  • el seam authoritative-store/enricher está activo con escrituras authoritative-first, recuperación con scope y gating de capacidades, cercado de contexto no confiable, y fallback por fallo;
  • Las nuevas escrituras automáticas de transcripciones se excluyen de los conectores de enriquecimiento; y
  • El comportamiento de compatibilidad y migración para filas de conversación heredadas, incluida la recuperación de conectores seguros por categoría y el comportamiento de limpieza o reconstrucción, está documentado y cubierto por pruebas con capacidad de reversión.

Consecuencias

Consecuencias positivas:

  • La reanudación de conversaciones, la retención de transcripciones y la eliminación de transcripciones tienen un único propietario canónico.
  • La memoria curada puede evolucionar sin convertirse en un segundo sistema de historial de sesiones.
  • El enriquecimiento externo puede mejorar la recuperación sin asumir autoridad persistente sobre el backend de memoria configurado.
  • Las interrupciones del conector y los protocolos de conector más débiles recurren a datos autoritativos con ámbito.
  • Las sesiones de ACP/Code mantienen su protección existente contra la deriva de memoria, incluido el panel de ACP de ZeroCode.

Consecuencias negativas:

  • Las rutas existentes de guardado automático de transcripciones y las filas de conversaciones heredadas requieren trabajo de compatibilidad y migración por fases.
  • Las sesiones de almacenamiento deben proporcionar suficiente fidelidad y cobertura antes de que las escrituras de transcripción puedan salir de la memoria general.
  • Los adaptadores de enriquecimiento no pueden recibir indiscriminadamente cada escritura en Memory; el envoltorio compartido debe hacer cumplir los límites de categoría y ámbito.
  • Es posible que los operadores vean temporalmente tanto las filas de conversación heredadas como el historial de sesión canónico mientras la migración permanezca activa.

Referencias