Memoria del workspace v2 (offline): notas de investigación

Objetivo: workspace estilo Clawd (agents.defaults.workspace, por defecto ~/.openclaw/workspace) donde la “memoria” se almacena como un archivo Markdown por día (memory/YYYY-MM-DD.md) más un conjunto pequeño de archivos estables (ej. memory.md, SOUL.md).

Este documento propone una arquitectura de memoria offline-first que mantiene Markdown como la fuente de verdad canónica y revisable, pero agrega recuperación estructurada (búsqueda, resúmenes de entidades, actualizaciones de confianza) mediante un índice derivado.

¿Por qué cambiar?

La configuración actual (un archivo por día) es excelente para:

• Registro “append-only” tipo diario
• Edición humana
• Durabilidad + auditabilidad respaldada por git
• Captura de baja fricción (“simplemente anótalo”)

Es débil para:

• Recuperación con alta cobertura (“¿qué decidimos sobre X?”, “¿la última vez que probamos Y?”)
• Respuestas centradas en entidades (“cuéntame sobre Alice / The Castle / warelay”) sin releer muchos archivos
• Estabilidad de opiniones/preferencias (y evidencia cuando cambian)
• Restricciones temporales (“¿qué era cierto durante noviembre 2025?”) y resolución de conflictos

Objetivos de diseño

• Offline: funciona sin red; puede ejecutarse en laptop/Castle; sin dependencia de la nube.
• Explicable: los elementos recuperados deben ser atribuibles (archivo + ubicación) y separables de la inferencia.
• Baja ceremonia: el registro diario sigue siendo Markdown, sin trabajo pesado de esquema.
• Incremental: v1 es útil solo con FTS; semántica/vectores y grafos son mejoras opcionales.
• Amigable para agentes: facilita “recuperar dentro de presupuestos de tokens” (devolver pequeños paquetes de hechos).

Modelo norte (Hindsight x Letta)

Dos piezas a combinar:

1. Bucle de control estilo Letta/MemGPT

• Mantener un “core” pequeño siempre en contexto (persona + hechos clave del usuario)
• Todo lo demás está fuera de contexto y se recupera mediante herramientas
• Las escrituras de memoria son llamadas de herramientas explícitas (append/replace/insert), persistidas, y luego reinyectadas en el siguiente turno

2. Sustrato de memoria estilo Hindsight

• Separar lo observado vs lo creído vs lo resumido
• Soportar retener/recuperar/reflexionar
• Opiniones con nivel de confianza que pueden evolucionar con evidencia
• Recuperación consciente de entidades + consultas temporales (incluso sin grafos de conocimiento completos)

Arquitectura propuesta (fuente de verdad en Markdown + índice derivado)

Almacén canónico (compatible con git)

Mantener ~/.openclaw/workspace como memoria canónica legible por humanos.

Estructura sugerida del workspace:

~/.openclaw/workspace/
  memory.md                    # pequeño: hechos duraderos + preferencias (tipo core)
  memory/
    YYYY-MM-DD.md              # registro diario (append; narrativo)
  bank/                        # páginas de memoria "tipadas" (estables, revisables)
    world.md                   # hechos objetivos sobre el mundo
    experience.md              # qué hizo el agente (primera persona)
    opinions.md                # preferencias/juicios subjetivos + confianza + punteros de evidencia
    entities/
      Peter.md
      The-Castle.md
      warelay.md
      ...

Notas:

• El registro diario sigue siendo registro diario. No es necesario convertirlo en JSON.
• Los archivos de bank/ son curados, producidos por trabajos de reflexión, y pueden editarse manualmente.
• memory.md sigue siendo “pequeño + tipo core”: las cosas que quieres que Clawd vea en cada sesión.

Almacén derivado (recuperación por máquina)

Agregar un índice derivado bajo el workspace (no necesariamente rastreado por git):

~/.openclaw/workspace/.memory/index.sqlite

Respaldado por:

• Esquema SQLite para hechos + enlaces de entidades + metadatos de opiniones
• SQLite FTS5 para recuperación léxica (rápido, pequeño, offline)
• Tabla de embeddings opcional para recuperación semántica (también offline)

El índice siempre es reconstruible desde Markdown.

Retener / Recuperar / Reflexionar (bucle operativo)

Retener: normalizar registros diarios en “hechos”

La idea clave de Hindsight que importa aquí: almacenar hechos narrativos, autocontenidos, no fragmentos diminutos.

Regla práctica para memory/YYYY-MM-DD.md:

• Al final del día (o durante), agregar una sección ## Retain con 2-5 viñetas que sean:
  • Narrativas (contexto entre turnos preservado)
  • Autocontenidas (tienen sentido de forma independiente después)
  • Etiquetadas con tipo + menciones de entidades

Ejemplo:

## Retain
- W @Peter: Currently in Marrakech (Nov 27–Dec 1, 2025) for Andy's birthday.
- B @warelay: I fixed the Baileys WS crash by wrapping connection.update handlers in try/catch (see memory/2025-11-27.md).
- O(c=0.95) @Peter: Prefers concise replies (<1500 chars) on WhatsApp; long content goes into files.

Parsing mínimo:

• Prefijo de tipo: W (mundo), B (experiencia/biográfico), O (opinión), S (observación/resumen; generalmente generado)
• Entidades: @Peter, @warelay, etc (slugs mapean a bank/entities/*.md)
• Confianza de opinión: O(c=0.0..1.0) opcional

Si no quieres que los autores piensen en ello: el trabajo de reflexión puede inferir estas viñetas del resto del registro, pero tener una sección explícita ## Retain es la “palanca de calidad” más fácil.

Recuperar: consultas sobre el índice derivado

La recuperación debería soportar:

• Léxica: “encontrar términos exactos / nombres / comandos” (FTS5)
• Por entidad: “cuéntame sobre X” (páginas de entidades + hechos vinculados a entidades)
• Temporal: “¿qué pasó alrededor del 27 de noviembre?” / “desde la semana pasada”
• Por opinión: “¿qué prefiere Peter?” (con confianza + evidencia)

El formato de retorno debería ser amigable para agentes y citar fuentes:

• kind (world|experience|opinion|observation)
• timestamp (día fuente, o rango de tiempo extraído si está presente)
• entities (["Peter","warelay"])
• content (el hecho narrativo)
• source (memory/2025-11-27.md#L12 etc)

Reflexionar: producir páginas estables + actualizar creencias

La reflexión es un trabajo programado (diario o heartbeat ultrathink) que:

• Actualiza bank/entities/*.md a partir de hechos recientes (resúmenes de entidades)
• Actualiza la confianza de bank/opinions.md basándose en refuerzo/contradicción
• Opcionalmente propone ediciones a memory.md (hechos duraderos “tipo core”)

Evolución de opiniones (simple, explicable):

• Cada opinión tiene:
  • Declaración
  • Confianza c in [0,1]
  • last_updated
  • Enlaces de evidencia (IDs de hechos que apoyan + contradicen)
• Cuando llegan nuevos hechos:
  • Encontrar opiniones candidatas por superposición de entidades + similitud (FTS primero, embeddings después)
  • Actualizar confianza con deltas pequeños; los saltos grandes requieren contradicción fuerte + evidencia repetida

Integración CLI: independiente vs integración profunda

Recomendación: integración profunda en OpenClaw, pero mantener una biblioteca central separable.

¿Por qué integrar en OpenClaw?

• OpenClaw ya conoce:
  • La ruta del workspace (agents.defaults.workspace)
  • El modelo de sesión + heartbeats
  • Patrones de logging + troubleshooting
• Quieres que el propio agente llame a las herramientas:
  • openclaw memory recall "..." --k 25 --since 30d
  • openclaw memory reflect --since 7d

¿Por qué separar una biblioteca?

• Mantener la lógica de memoria testeable sin gateway/runtime
• Reutilizar desde otros contextos (scripts locales, futura app de escritorio, etc.)

Forma: Las herramientas de memoria están pensadas como una pequeña capa CLI + biblioteca, pero esto es solo exploratorio.

”S-Collide” / SuCo: cuándo usarlo (investigación)

Si “S-Collide” se refiere a SuCo (Subspace Collision): es un enfoque de recuperación ANN que apunta a fuertes compensaciones de cobertura/latencia usando colisiones aprendidas/estructuradas en subespacios (paper: arXiv 2411.14754, 2024).

Perspectiva pragmática para ~/.openclaw/workspace:

• No empieces con SuCo.
• Empieza con SQLite FTS + embeddings (opcionales) simples; obtendrás la mayoría de las mejoras de UX inmediatamente.
• Considera soluciones clase SuCo/HNSW/ScaNN solo cuando:
  • El corpus es grande (decenas/cientos de miles de fragmentos)
  • La búsqueda de embeddings por fuerza bruta se vuelva demasiado lenta
  • La calidad de recuperación esté significativamente limitada por la búsqueda léxica

Alternativas compatibles con offline (en complejidad creciente):

• SQLite FTS5 + filtros de metadatos (cero ML)
• Embeddings + fuerza bruta (funciona sorprendentemente bien si el conteo de fragmentos es bajo)
• Índice HNSW (común, robusto; necesita un binding de biblioteca)
• SuCo (grado de investigación; atractivo si hay una implementación sólida que puedas embeber)

Pregunta abierta:

• ¿Cuál es el mejor modelo de embeddings offline para “memoria de asistente personal” en tus máquinas (laptop + escritorio)?
  • Si ya tienes Ollama: genera embeddings con un modelo local; de lo contrario, incluye un modelo de embeddings pequeño en la cadena de herramientas.

Piloto más pequeño útil

Si quieres una versión mínima pero útil:

• Agregar páginas de entidades en bank/ y una sección ## Retain en los registros diarios.
• Usar SQLite FTS para recuperación con citas (ruta + números de línea).
• Agregar embeddings solo si la calidad o escala de recuperación lo demandan.

Referencias

• Conceptos de Letta / MemGPT: “bloques de memoria core” + “memoria de archivo” + memoria con autoedición basada en herramientas.
• Reporte técnico de Hindsight: “retener / recuperar / reflexionar”, memoria de cuatro redes, extracción de hechos narrativos, evolución de confianza de opiniones.
• SuCo: arXiv 2411.14754 (2024): recuperación de vecinos más cercanos aproximados por “Subspace Collision”.