Self-Improving Memory MCP

# 🛡️ Sistema Anti-Compactación La característica más innovadora del sistema: **conversaciones infinitas sin pérdida de contexto**. --- ## 📋 Contenidos 1. [El Problema](#el-problema) 2. [Nuestra Solución](#nuestra-solución) 3. [Cómo Funciona](#cómo-funciona) 4. [Uso del Sistema](#uso-del-sistema) 5. [Ejemplos Prácticos](#ejemplos-prácticos) 6. [Detalles Técnicos](#detalles-técnicos) --- ## El Problema ### Limitaciones de Claude **Claude tiene un límite de contexto:** - **200,000 tokens** máximo por conversación - ~150,000 palabras - ~750 páginas de texto **¿Qué pasa al alcanzar el límite?** Claude tiene un mecanismo llamado **"autocompact"**: 1. Detecta que estás cerca del límite (80-90%) 2. **Automáticamente elimina mensajes antiguos** 3. Intenta preservar mensajes recientes 4. **PROBLEMA:** Se pierde información importante ### Ejemplo del Problema ``` Conversación larga trabajando en un proyecto: Tokens: 0k → 50k → 100k → 150k → 170k → 190k ▲ │ Autocompact se activa ANTES (170k tokens): ✅ Todas las decisiones arquitectónicas ✅ Todos los errores y soluciones ✅ Todas las preferencias del usuario ✅ Todo el historial de trabajo DESPUÉS (120k tokens): ❌ Decisiones antiguas eliminadas ❌ Errores/soluciones perdidos ❌ Contexto fragmentado ❌ Claude "olvida" información crítica Resultado: → Repite preguntas ya respondidas → Re-hace decisiones ya tomadas → Repite errores ya resueltos → Pierde track del progreso ``` ### Impacto en Proyectos Reales **Sin anti-compactación:** - 📉 Conversaciones limitadas a ~3-4 horas de trabajo - 🔄 Constante repetición de contexto - ❌ Pérdida de decisiones arquitectónicas - 😤 Frustración del usuario **Con anti-compactación:** - ✅ Conversaciones ilimitadas - ✅ Zero pérdida de información - ✅ Contexto perfecto siempre - 😊 Experiencia fluida --- ## Nuestra Solución ### Filosofía > **"No dejamos que autocompact elimine nada. Nosotros controlamos el contexto."** ### Estrategia en 3 Partes ``` ┌─────────────────────────────────────────────────────┐ │ 1. MONITOREO PROACTIVO │ │ • Vigilamos tokens constantemente │ │ • Detectamos ANTES de que autocompact se active │ │ • Umbral: 80% (160k/200k tokens) │ └─────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ 2. CHECKPOINT COMPLETO │ │ • Guardamos TODA la información en memoria │ │ • No solo resumen, sino estado completo │ │ • Incluye: decisiones, código, progreso, contexto │ └─────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ 3. RECUPERACIÓN PERFECTA │ │ • Nueva conversación carga checkpoint │ │ • Restaura 100% del estado │ │ • Continúa sin pérdida │ └─────────────────────────────────────────────────────┘ ``` ### Resultado **Conversaciones infinitas:** - Sesión 1: 0k → 170k tokens → Checkpoint - Sesión 2: 0k → 170k tokens → Checkpoint - Sesión 3: 0k → 170k tokens → Checkpoint - ... infinitas sesiones sin pérdida de información --- ## Cómo Funciona ### Componentes del Sistema #### 1. Token Monitoring (Automático) Claude monitorea automáticamente el uso de tokens: ``` Claude recibe en cada mensaje: <budget:token_budget>200000</budget:token_budget> Y ve su uso actual: Token usage: 165432/200000; 34568 remaining Cálculo: 165432 / 200000 = 82.7% Trigger: if (usage > 80%) { activar Pre-Compact Interceptor Agent } ``` **Triggers de monitoreo:** - ✅ Porcentaje de tokens > 80% (160k) - ✅ Número de mensajes > 40 - ✅ Antes de operaciones grandes - ✅ Comando manual `/checkpoint` #### 2. Pre-Compact Interceptor Agent **Ubicación:** `.claude/agents/pre-compact-interceptor.md` **Responsabilidad:** Guardar estado COMPLETO antes de pérdida **Proceso:** ```javascript // Pseudo-código del agente async function preCompactInterceptor() { // 1. Alertar usuario console.log('🚨 Context checkpoint triggered (165k/200k tokens)'); // 2. Recopilar información exhaustiva const checkpoint = { metadata: { timestamp: new Date().toISOString(), tokenCount: '165k/200k', messageCount: 45, reason: 'auto-triggered at 82.5%' }, currentWork: { task: 'Implementing MFA authentication', progress: '70% complete', currentFile: 'src/services/mfa.service.js', currentLine: 67, nextStep: 'Implement SMS 2FA with Twilio' }, completed: [ '✅ JWT authentication system', '✅ TOTP 2FA implementation', '✅ Email verification flow', '✅ 45 passing tests' ], pending: [ '⏳ SMS 2FA integration', '⏳ Backup codes generation', '⏳ Admin panel for user management' ], decisions: [ { what: 'Use speakeasy for TOTP', why: 'More secure than otplib', when: '2025-10-07 10:30', confidence: 0.9 }, { what: 'Use Twilio for SMS', why: 'Better deliverability than alternatives', when: '2025-10-07 11:15', confidence: 0.8 } ], approaches: { successful: [ 'JWT refresh token rotation worked well', 'TOTP validation with time window = 1' ], failed: [ 'Tried email OTP first - delivery too slow', 'Tried Google Authenticator URI - format issues' ] }, userPreferences: [ 'Prefer security over convenience', 'Use async/await over callbacks', 'Comprehensive error handling required' ], filesModified: [ 'src/controllers/auth.controller.js (lines 1-120)', 'src/services/token.service.js (complete rewrite)', 'src/services/mfa.service.js (lines 1-67, incomplete)', 'tests/auth.test.js (45 tests added)' ], blockers: [], criticalInfo: [ 'Twilio credentials in .env.example', 'TOTP secret must be 32 chars base32', 'Token expiration set to 7 days per user preference' ] }; // 3. Guardar en memoria como session-snapshot await memory.create_entities([{ name: `session-checkpoint-${Date.now()}`, entityType: 'session-snapshot', observations: [ `METADATA: ${JSON.stringify(checkpoint.metadata)}`, `CURRENT WORK: ${JSON.stringify(checkpoint.currentWork)}`, `COMPLETED: ${checkpoint.completed.join('\n')}`, `PENDING: ${checkpoint.pending.join('\n')}`, `DECISIONS: ${JSON.stringify(checkpoint.decisions)}`, `APPROACHES: ${JSON.stringify(checkpoint.approaches)}`, `USER PREFERENCES: ${checkpoint.userPreferences.join('\n')}`, `FILES MODIFIED: ${checkpoint.filesModified.join('\n')}`, `CRITICAL INFO: ${checkpoint.criticalInfo.join('\n')}`, `STATUS: in-progress` ] }]); // 4. Generar continuation summary para el usuario const summary = generateContinuationSummary(checkpoint); // 5. Instruir al usuario console.log(summary); console.log('\n📝 INSTRUCTIONS:'); console.log('1. Copy the summary above'); console.log('2. Start a NEW conversation in Claude Desktop'); console.log('3. Paste the summary'); console.log('4. Say "continue from checkpoint"'); console.log('5. I will restore everything and continue exactly where we left off'); } ``` #### 3. Context Recovery Agent **Ubicación:** `.claude/agents/context-recovery.md` **Responsabilidad:** Restaurar estado completo en nueva conversación **Proceso:** ```javascript // Pseudo-código del agente async function contextRecoveryAgent() { // 1. Detectar trigger const userMessage = getCurrentMessage(); if ( userMessage.includes('continue from checkpoint') || userMessage.includes('Checkpoint ID:') || isNewConversation() ) { // 2. Buscar checkpoints recientes const recentCheckpoints = await memory.search_nodes({ query: 'session-snapshot status:in-progress', filters: { type: 'session-snapshot', createdWithin: '24 hours' } }); if (recentCheckpoints.length === 0) { return; // No hay checkpoints para recuperar } // 3. Seleccionar checkpoint más reciente const checkpoint = recentCheckpoints[0]; // 4. Parsear observaciones const state = parseCheckpoint(checkpoint); // 5. Presentar resumen al usuario console.log('💡 Checkpoint encontrado y recuperado\n'); console.log('📋 CONTEXT LOADED'); console.log('═'.repeat(50)); console.log(`Task: ${state.currentWork.task}`); console.log(`Progress: ${state.currentWork.progress}`); console.log(`Last updated: ${formatTimestamp(state.metadata.timestamp)}\n`); console.log('COMPLETED:'); state.completed.forEach(item => console.log(item)); console.log('\nPENDING:'); state.pending.forEach(item => console.log(item)); console.log(`\nNEXT STEP:`); console.log(`→ ${state.currentWork.nextStep}`); console.log(` File: ${state.currentWork.currentFile}:${state.currentWork.currentLine}`); console.log('\nKEY DECISIONS:'); state.decisions.forEach(d => { console.log(`- ${d.what} (${d.why})`); }); console.log('\n✅ Context fully restored. Ready to continue!\n'); // 6. Actualizar status del checkpoint await memory.add_observations({ entityName: checkpoint.name, contents: [ `STATUS: resumed`, `RESUMED AT: ${new Date().toISOString()}` ] }); // 7. Aplicar contexto internamente // Claude ahora tiene TODO el contexto en su "mente" // No necesita que usuario re-explique nada applyContextToClaude(state); } } ``` ### Diagrama de Flujo Completo ``` ┌──────────────────────────────────────────────────────────────┐ │ CONVERSACIÓN LARGA (0k → 170k tokens) │ └────────────────────┬─────────────────────────────────────────┘ │ ▼ ┌─────────────────────┐ │ Token Monitor │ │ Detecta: 170k/200k │ │ = 85% (> umbral) │ └─────────┬───────────┘ │ ▼ ┌─────────────────────────┐ │ Pre-Compact Interceptor │ │ • Recopila estado │ │ • Guarda en memoria │ │ • Genera summary │ └─────────┬───────────────┘ │ ▼ ┌─────────────────────────┐ │ Usuario recibe summary │ │ 📋 Continuation summary │ │ "Copia y pega en │ │ nueva conversación" │ └─────────┬───────────────┘ │ ▼ ┌─────────────────────────┐ │ NUEVA CONVERSACIÓN │ │ (tokens: 0k) │ └─────────┬───────────────┘ │ ▼ ┌─────────────────────────┐ │ Usuario pega summary │ │ "continue from │ │ checkpoint" │ └─────────┬───────────────┘ │ ▼ ┌─────────────────────────┐ │ Context Recovery Agent │ │ • Busca checkpoint │ │ • Carga estado │ │ • Restaura contexto │ └─────────┬───────────────┘ │ ▼ ┌─────────────────────────┐ │ Claude con TODO el │ │ contexto restaurado │ │ Continúa desde línea 67 │ └─────────────────────────┘ │ ▼ ┌─────────────────────────┐ │ CONVERSACIÓN CONTINÚA │ │ (0k → 170k → checkpoint)│ └─────────────────────────┘ │ ▼ [LOOP] ``` --- ## Uso del Sistema ### Método 1: Automático (Recomendado) **No requiere acción del usuario. Todo es automático.** ``` 1. Trabajas normalmente con Claude 2. Claude monitorea tokens en background 3. A 80% (160k), checkpoint se activa automáticamente 4. Claude te muestra continuation summary 5. Copias el summary 6. Abres nueva conversación 7. Pegas el summary 8. Claude recupera todo y continúa ``` ### Método 2: Manual con `/checkpoint` **Útil para:** - Antes de tomar un break - Antes de trabajar en algo arriesgado - Cuando sientas que la conversación está larga - Puntos naturales de pausa ```bash # En la conversación actual /checkpoint # Claude guarda estado y genera summary # Tu copias y pegas en nueva conversación ``` ### Método 3: Proactivo (Context Recovery) **Context Recovery Agent busca automáticamente checkpoints recientes:** ``` # Nueva conversación (cualquier día) Usuario: "hey" → Context Recovery busca checkpoints < 24h Si encuentra: Claude: "💡 Encontré checkpoint de ayer sobre MFA authentication. ¿Quieres continuar desde ahí?" Usuario: "sí" → Claude carga todo y continúa ``` --- ## Ejemplos Prácticos ### Ejemplo 1: Desarrollo de Feature Complejo ``` ═══════════════════════════════════════════════════════════ SESIÓN 1 - Lunes 10:00 AM (0k → 170k tokens) ═══════════════════════════════════════════════════════════ Usuario: "Implementa sistema de pagos con Stripe" [4 horas de trabajo] → JWT authentication: ✅ → Stripe integration: ✅ → Webhook handling: ✅ → Tests: 30 passing ✅ → Next: Refund logic Tokens: 170k/200k (85%) 🚨 Claude: "Context checkpoint triggered" 📋 CONTINUATION SUMMARY Checkpoint ID: session-checkpoint-2025-10-07-14-00 TRABAJANDO EN: Sistema de pagos con Stripe Última actualización: 2025-10-07 14:00 COMPLETADO: ✅ Stripe API integration ✅ Payment intent creation ✅ Webhook endpoint (/webhooks/stripe) ✅ Webhook signature verification ✅ Payment success/failure handling ✅ 30 tests passing PENDIENTE: ⏳ Refund logic implementation ⏳ Dispute handling ⏳ Subscription management ⏳ Invoice generation NEXT STEP: Implementar refund endpoint en src/controllers/payment.controller.js:89 Stripe refund API docs: https://stripe.com/docs/api/refunds DECISIONES CLAVE: - Use Stripe checkout (not custom form) - mejor UX - Webhooks con idempotency keys - prevenir duplicados - Store payment IDs en DB - para auditoría FILES IN PROGRESS: - src/controllers/payment.controller.js (línea 89) ═══════════════════════════════════════════════════════════ SESIÓN 2 - Lunes 15:00 PM (Nueva conversación) ═══════════════════════════════════════════════════════════ Usuario: [pega summary] "continuar desde checkpoint" Claude: "💡 Checkpoint recuperado Task: Sistema de pagos con Stripe Progress: 60% completado Continuemos con refund logic en src/controllers/payment.controller.js:89 ¿Procedemos?" Usuario: "sí" → Claude continúa EXACTAMENTE desde línea 89 → Implementa refunds → Sigue con disputes → ... sin perder NADA del contexto [3 horas más de trabajo] Tokens: 160k/200k (80%) 🚨 Otro checkpoint... ═══════════════════════════════════════════════════════════ SESIÓN 3 - Martes 09:00 AM ═══════════════════════════════════════════════════════════ [Recupera checkpoint de ayer] [Continúa con subscriptions] [Sistema completo al final del día] RESULTADO: ✅ Feature complejo implementado en 3 sesiones ✅ ZERO pérdida de información ✅ ZERO repetición de contexto ✅ Experiencia fluida y continua ``` ### Ejemplo 2: Bug Complejo con Múltiples Iteraciones ``` SESIÓN 1: Investigando bug de memory leak... Tokens: 170k → Checkpoint SESIÓN 2: Probando solución 1... falló Probando solución 2... falló Tokens: 165k → Checkpoint SESIÓN 3: Solución 3 funcionó! Context recovery recuerda: - Solución 1 falló porque X - Solución 2 falló porque Y - Solución 3 funcionó porque Z → Captura en memoria para futuro → Nunca repetir enfoques fallidos ``` ### Ejemplo 3: Proyecto Multi-Semana ``` SEMANA 1: → 10 sesiones de trabajo → 10 checkpoints guardados → Todo el conocimiento en memoria SEMANA 2: → Context Recovery carga checkpoints automáticamente → Claude recuerda TODO de semana 1 → Continúa sin problemas SEMANA 4: → Proyecto completo → 40+ sesiones → ZERO información perdida → Conocimiento completo capturado ``` --- ## Detalles Técnicos ### Estructura del Checkpoint **Entity Type:** `session-snapshot` **Observations Structure:** ```javascript { name: "session-checkpoint-1696700000000", entityType: "session-snapshot", observations: [ // METADATA "METADATA: {\"timestamp\":\"2025-10-07T14:00:00Z\",\"tokenCount\":\"170k/200k\",\"messageCount\":45,\"reason\":\"auto\"}", // CURRENT STATE "CURRENT WORK: {\"task\":\"...\",\"progress\":\"...\",\"file\":\"...\",\"line\":67}", // COMPLETED ITEMS "COMPLETED: [\"✅ Item 1\",\"✅ Item 2\",...]", // PENDING ITEMS "PENDING: [\"⏳ Item 1\",\"⏳ Item 2\",...]", // DECISIONS (con reasoning completo) "DECISIONS: [{\"what\":\"...\",\"why\":\"...\",\"when\":\"...\"}]", // APPROACHES (successful + failed) "APPROACHES: {\"successful\":[...],\"failed\":[...]}", // USER PREFERENCES "USER PREFERENCES: [\"Prefer X\",\"Avoid Y\",...]", // FILES MODIFIED "FILES MODIFIED: [\"path/to/file.js (lines X-Y)\",...]", // BLOCKERS "BLOCKERS: [\"Need API key\",...]", // CRITICAL INFO "CRITICAL INFO: [\"Important fact 1\",...]", // STATUS "STATUS: in-progress" ] } ``` ### Status Lifecycle ``` created → in-progress → [checkpointed] → paused ↓ resumed → completed ↓ abandoned (optional) ``` ### Recovery Priority Si hay múltiples checkpoints: ```javascript // Prioridad de recuperación 1. Status === 'in-progress' (más reciente) 2. Status === 'paused' (más reciente) 3. Status === 'resumed' (más reciente) // Ignorar - Status === 'completed' - Status === 'abandoned' - Older than 7 days (configurable) ``` ### Performance **Checkpoint creation time:** - Recolectar información: ~100-200ms - Guardar en memoria: ~300-500ms - **Total: <1 segundo** **Recovery time:** - Buscar checkpoint: ~200ms - Cargar observaciones: ~100ms - Parsear y aplicar: ~200ms - **Total: <1 segundo** **Impact:** - ✅ Imperceptible para el usuario - ✅ No bloquea workflow - ✅ Seamless experience --- ## FAQ **¿Qué pasa si olvido copiar el continuation summary?** No problem. Context Recovery busca checkpoints automáticamente. Solo di "continuar desde checkpoint" en nueva conversación. **¿Puedo tener múltiples checkpoints?** Sí. El sistema mantiene todos los checkpoints. Context Recovery selecciona el más reciente relevante. **¿Los checkpoints caducan?** Por defecto, se mantienen indefinidamente. Puedes marcarlos como "completed" o "abandoned" manualmente. **¿Qué pasa si el checkpoint falla?** Error se loggea. Conversación continúa. Puedes hacer `/checkpoint` manual después. **¿Cuánto espacio ocupan los checkpoints?** Cada checkpoint: ~5-10KB de texto. 100 checkpoints = ~500KB-1MB. Insignificante. **¿Puedo editar un checkpoint?** Sí, usando herramientas de memoria (`add_observations`, `delete_observations`). **¿Puedo exportar checkpoints?** Sí. Usa `/memory-export` para generar Markdown con todos los checkpoints. **¿Funciona con otros proyectos?** Sí. Cada proyecto tiene su propio `.claude-memory/`, sus propios checkpoints. --- ## Mejores Prácticas ### ✅ DO: 1. **Confía en el sistema automático** - No fuerces checkpoints manualmente sin razón - El monitoreo a 80% es óptimo 2. **Usa `/checkpoint` en puntos naturales** - Antes de breaks largos - Después de completar milestones - Antes de trabajo arriesgado 3. **Copia el continuation summary completo** - Incluye el Checkpoint ID - No edites el formato 4. **Di "continuar desde checkpoint" explícitamente** - Ayuda a Context Recovery a detectar intención ### ❌ DON'T: 1. **No fuerces checkpoints cada 5 minutos** - Overhead innecesario - Confunde el sistema 2. **No ignores el continuation summary** - Sin él, recovery es más difícil 3. **No edites manualmente los checkpoints** - A menos que sepas lo que haces --- ## Comparación con Alternativas ### Opción 1: Sin Sistema ``` ❌ Conversaciones limitadas (3-4 horas) ❌ Autocompact elimina información ❌ Constantemente repitiendo contexto ❌ Pérdida de decisiones ``` ### Opción 2: Manual Context Copy-Paste ``` ⚠️ Usuario debe recordar copiar contexto ⚠️ Fácil olvidar información importante ⚠️ Formato inconsistente ⚠️ No hay búsqueda semántica ``` ### Opción 3: Nuestro Sistema Anti-Compactación ``` ✅ Totalmente automático ✅ Guardado exhaustivo del estado ✅ Recuperación perfecta ✅ Búsqueda semántica de checkpoints ✅ Conversaciones infinitas ✅ Zero pérdida de información ``` --- ## Roadmap Futuro Ver [ROADMAP.md](../ROADMAP.md) para mejoras planeadas: - **Auto-recovery sin continuation summary** - Sistema detecta nueva conversación - Pregunta si continuar desde último checkpoint - **Checkpoint diffing** - Ver qué cambió entre checkpoints - Visualización de progreso - **Checkpoint branching** - Crear branches desde checkpoints - Experimentar con diferentes approaches - **Cloud sync** (opcional) - Sync checkpoints entre dispositivos - Backup automático --- **El conocimiento nunca se pierde. Las conversaciones nunca terminan. Claude nunca olvida. 🧠**