feat: v0.6.0 — Fase 1 ContextMemory synthesis + CLAUDE.md (CLAUDE.md)

CLAUDE.md

@@ -0,0 +1,167 @@
+# CLAUDE.md — Bruno / retro-cpu
+
+**Componente:** `d1d4c/retro-cpu` HF Space ("Retro Lite Online")
+**Propietario:** HFPilot (retro-hf)
+**Versión actual:** 0.6.0 (2026-06-21 — Fase 1: síntesis ContextMemory activa)
+**ADRs:** ADR-562 (Harness Independence), ADR-563 (Native Harness)
+
+---
+
+## Qué es Bruno
+
+Bruno es la instancia online y ligera de Retro que corre en un HF Docker Space
+con CPU gratuita (`cpu-basic`, free tier). Permite que Dídac opere desde el móvil
+(Telegram) cuando `satelite` está offline. **No es el Retro completo** — es un
+bridge conversacional con memoria propia.
+
+Bot Telegram: `@Bruno_Retro_bot`. Solo responde al `chat_id` de Dídac (`6622755810`).
+
+---
+
+## Arquitectura
+
+```
+[Móvil] ──Telegram──> [webhook POST /] ──> retro-cpu (CPU-only)
+                                                │
+                          ┌─────────────────────┴──────────────────────┐
+                          │                                             │
+                    texto (normal)                               voz (BLOQUEADA)
+                          │                                             │
+              retro-space /v1/chat/completions              getFile → api.telegram.org
+               (Qwen2.5-7B, Bearer HF_TOKEN)                    (ConnectTimeout en HF)
+                          │
+                  respuesta inline en webhook HTTP
+                  {"method":"sendMessage","chat_id":...}
+```
+
+**Constraint crítico de red (2026-06-21):** HF Spaces no pueden hacer outbound
+a `api.telegram.org`. La respuesta se devuelve inline en el body HTTP del webhook
+(mecanismo oficial de Telegram). Las notas de voz están bloqueadas hasta que haya
+un Cloudflare Worker relay (Fase 1, pendiente).
+
+---
+
+## Memoria — bruno/v1 (sovereign graph)
+
+Bruno tiene su **propio grafo soberano**, independiente del HyperGraph central
+de Retro (ADR-562: sin `sys.path` a casa, sin writes a la DB central).
+
+### Stack
+
+| Componente | Descripción |
+|------------|-------------|
+| `bruno_graph.py` | Adaptador stdlib (`sqlite3`+`json`), sin deps externas |
+| `/data/bruno_graph.db` | SQLite en bucket `retro-cpu-storage`, **sobrevive reinicios** |
+| `bruno_v1.json` | Ontología SSOT (horneada en imagen + copia en `retro-hf/ontology/`) |
+| `test_bruno_graph.py` | 5 tests de rechazo de violaciones de schema |
+
+### Tipos de nodo
+
+| Tipo | Persistencia | Descripción |
+|------|-------------|-------------|
+| `Message` | append-only | Turno de conversación (role, content, turn_index, session_ref) |
+| `ContextMemory` | singleton por chat_id, upsert monotónico | Síntesis LLM cross-session |
+| `Pattern` | declarado | Reservado para patrones detectados |
+
+### Cómo funciona la memoria (v0.6.0 — Fase 1 activa)
+
+```
+Turno de usuario
+    │
+    ├── 1. build_system_prompt(chat_id, bruno)
+    │       └── lee ContextMemory → si synthesis_strategy="llm_qwen2.5-7b"
+    │                                  → inyecta en system prompt
+    │
+    ├── 2. infer_chat(history, system_prompt)
+    │       └── Qwen2.5-7B genera respuesta
+    │
+    ├── 3. Respuesta inline → Telegram
+    │
+    └── 4. asyncio.create_task(synthesize_context_memory(...))  ← background
+             └── llama a retro-space con meta-prompt de síntesis (≤200 tokens)
+                 → upsert ContextMemory (synthesis_strategy="llm_qwen2.5-7b")
+```
+
+La síntesis ocurre en background tras enviar la respuesta → latencia = 0 para el usuario.
+
+### API de bruno_graph.py
+
+```python
+from bruno_graph import BrunoGraph
+
+bruno = BrunoGraph(db_path="/data/bruno_graph.db", ontology_path="bruno_v1.json")
+
+# Append mensaje
+bruno.append_message(chat_id, "user", "hola", source="telegram")
+bruno.append_message(chat_id, "assistant", "hola!", source="qwen2.5-7b")
+
+# Carrusel activo (N últimos turnos)
+history = bruno.carousel(chat_id, n=20)  # → [{"role": ..., "content": ...}]
+
+# ContextMemory (singleton cross-session)
+cm = bruno.get_context_memory(chat_id)           # → dict | None
+bruno.upsert_context_memory(chat_id, content,    # → crea o actualiza
+    synthesis_strategy="llm_qwen2.5-7b")
+
+# Reset de sesión (epoch rota, turnos anteriores se conservan)
+bruno.reset_session(chat_id)
+```
+
+---
+
+## Deploy
+
+**⚠️ retro-cpu usa Dev Mode → código horneado en imagen Docker (sin git restore).**
+`api.upload_file()` NO refresca el contenedor. Para aplicar cambios: **`factory_reboot=True`**.
+
+```python
+from huggingface_hub import HfApi
+import os
+
+api = HfApi(token=os.environ["HF_TOKEN"])
+
+# 1. Subir archivo(s) modificado(s)
+for fname in ["app.py", "bruno_graph.py", "bruno_v1.json"]:
+    api.upload_file(
+        path_or_fileobj=open(f"retro-cpu/{fname}", "rb").read(),
+        path_in_repo=fname,
+        repo_id="d1d4c/retro-cpu",
+        repo_type="space",
+        commit_message=f"deploy: {fname} vX.Y.Z",
+    )
+
+# 2. Factory reboot SIEMPRE (Dev Mode requiere reconstruir imagen)
+api.restart_space("d1d4c/retro-cpu", factory_reboot=True)
+```
+
+**Secrets del Space** (configurados en HF, no en código):
+
+| Secret | Propósito |
+|--------|-----------|
+| `TELEGRAM_BOT_TOKEN` | Bot API token de @BotFather |
+| `HF_TOKEN` | Bearer auth a retro-space + retro-tts (privados) |
+| `WEBHOOK_SECRET` | Secret token del webhook de Telegram |
+| `ALLOWED_CHAT_IDS` | Allowlist de chat_ids (solo Dídac: `6622755810`) |
+
+---
+
+## SSH
+
+```bash
+ssh -i ~/.ssh/hf_space_new d1d4c-retro-cpu@ssh.hf.space
+```
+
+---
+
+## Roadmap Bruno
+
+| Fase | Estado | Descripción |
+|------|--------|-------------|
+| 0 | ✅ DONE | Chat text-only, grafo bruno/v1, persistencia bucket |
+| 1 | ✅ DONE (0.6.0) | Síntesis ContextMemory (LLM background) + inyección en prompt |
+| 1b | Pendiente | CF Worker relay → desbloquea voz in/out desde móvil |
+| 2 | Opcional | Export async unidireccional HF→casa (NUNCA sync bidireccional) |
+
+---
+
+**Owner:** HFPilot | **Proyecto:** retro-hf | **Actualizado:** 2026-06-21