elsabro 2.3.0 → 3.7.0

package/references/memory-system.md

@@ -0,0 +1,683 @@
+---
+name: memory-system
+description: Sistema de memoria multi-nivel inspirado en CrewAI
+version: 1.0.0
+---
+
+# ELSABRO Multi-Level Memory System
+
+## Vision General
+
+El sistema de memoria multi-nivel permite a ELSABRO mantener contexto a través de sesiones, aprender de errores, y mejorar continuamente. Inspirado en CrewAI's memory architecture.
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│                       MEMORY ARCHITECTURE                               │
+├────────────────────────────────────────────────────────────────────────┤
+│                                                                        │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐    │
+│  │   SHORT-TERM     │  │    LONG-TERM     │  │     ENTITY       │    │
+│  │    MEMORY        │  │     MEMORY       │  │     MEMORY       │    │
+│  ├──────────────────┤  ├──────────────────┤  ├──────────────────┤    │
+│  │ • Sesión actual  │  │ • patterns.md    │  │ • Archivos       │    │
+│  │ • Conversación   │  │ • mistakes.md    │  │ • Funciones      │    │
+│  │ • Decisiones     │  │ • preferences    │  │ • Componentes    │    │
+│  │ • Contexto temp  │  │ • learnings      │  │ • Dependencies   │    │
+│  └──────────────────┘  └──────────────────┘  └──────────────────┘    │
+│           │                    │                      │               │
+│           └────────────────────┼──────────────────────┘               │
+│                                ▼                                       │
+│                    ┌──────────────────────┐                           │
+│                    │   CONTEXTUAL MEMORY  │                           │
+│                    │   (RAG + Embeddings) │                           │
+│                    ├──────────────────────┤                           │
+│                    │ • Semantic search    │                           │
+│                    │ • Related context    │                           │
+│                    │ • Auto-retrieval     │                           │
+│                    └──────────────────────┘                           │
+│                                                                        │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Tipos de Memoria
+
+### 1. Short-Term Memory (Sesión)
+
+**Propósito**: Mantener contexto dentro de una sesión de trabajo.
+
+**Duración**: Mientras dure la sesión (se guarda en checkpoint al pausar).
+
+**Contenido**:
+- Conversación actual con el usuario
+- Decisiones tomadas en esta sesión
+- Archivos leídos/modificados
+- Errores encontrados y resueltos
+- Estado de tareas en progreso
+
+```json
+{
+  "shortTerm": {
+    "sessionId": "ses_abc123",
+    "startedAt": "2024-01-20T15:00:00Z",
+    "conversation": [
+      {"role": "user", "content": "Quiero agregar auth", "at": "..."},
+      {"role": "assistant", "action": "planned", "at": "..."}
+    ],
+    "decisions": [
+      {
+        "question": "¿Qué librería de auth usar?",
+        "decision": "NextAuth.js",
+        "reasoning": "Mejor integración con Next.js, soporte OAuth",
+        "alternatives": ["Auth0", "Clerk", "Custom JWT"],
+        "decidedAt": "2024-01-20T15:05:00Z"
+      }
+    ],
+    "filesAccessed": [
+      {"path": "src/app/layout.tsx", "action": "read", "at": "..."},
+      {"path": "src/app/api/auth/[...nextauth]/route.ts", "action": "created", "at": "..."}
+    ],
+    "currentContext": {
+      "activeTask": "Implementar login",
+      "activePhase": "implementation",
+      "focusArea": "authentication"
+    }
+  }
+}
+```
+
+### 2. Long-Term Memory (Persistente)
+
+**Propósito**: Aprendizajes que persisten entre sesiones.
+
+**Duración**: Permanente (hasta que el usuario los borre).
+
+**Contenido**:
+- Patrones preferidos del proyecto/usuario
+- Errores cometidos y cómo evitarlos
+- Preferencias de estilo de código
+- Decisiones arquitectónicas importantes
+
+**Archivos**:
+- `.planning/patterns.md` - Patrones a seguir
+- `.planning/mistakes.md` - Errores a evitar
+- `.planning/preferences.json` - Preferencias del usuario
+- `.planning/learnings.json` - Aprendizajes acumulados
+
+```json
+{
+  "longTerm": {
+    "patterns": [
+      {
+        "id": "pat_001",
+        "name": "Error Handling Pattern",
+        "description": "Siempre usar try-catch con tipos específicos",
+        "example": "try { ... } catch (error) { if (error instanceof AuthError) ... }",
+        "context": ["typescript", "error-handling"],
+        "createdAt": "2024-01-15T10:00:00Z",
+        "usageCount": 12
+      }
+    ],
+    "mistakes": [
+      {
+        "id": "mis_001",
+        "description": "No usar 'any' en TypeScript",
+        "correction": "Definir tipos específicos o usar 'unknown'",
+        "severity": "high",
+        "occurrences": 3,
+        "lastOccurrence": "2024-01-18T14:30:00Z"
+      }
+    ],
+    "preferences": {
+      "codeStyle": {
+        "semicolons": false,
+        "quotes": "single",
+        "indentation": 2,
+        "maxLineLength": 100
+      },
+      "architecture": {
+        "preferredPatterns": ["repository", "service-layer"],
+        "avoidPatterns": ["singleton-abuse", "god-objects"]
+      },
+      "testing": {
+        "framework": "vitest",
+        "coverage": 80,
+        "style": "describe-it"
+      }
+    },
+    "learnings": [
+      {
+        "id": "learn_001",
+        "trigger": "User correction",
+        "original": "Usé fetch sin error handling",
+        "learned": "Siempre envolver fetch en try-catch con timeout",
+        "confidence": 0.95,
+        "applications": 8
+      }
+    ]
+  }
+}
+```
+
+### 3. Entity Memory (Codebase)
+
+**Propósito**: Conocimiento sobre entidades específicas del código.
+
+**Duración**: Se actualiza cuando cambia el código.
+
+**Contenido**:
+- Información sobre archivos importantes
+- Funciones/componentes y sus responsabilidades
+- Dependencias y relaciones
+- Historial de cambios
+
+```json
+{
+  "entityMemory": {
+    "files": {
+      "src/components/Auth/LoginForm.tsx": {
+        "type": "component",
+        "purpose": "Formulario de login con email/password",
+        "dependencies": ["@/lib/auth", "@/components/ui/Button"],
+        "exports": ["LoginForm", "LoginFormProps"],
+        "lastModified": "2024-01-20T15:30:00Z",
+        "modifiedBy": ["elsabro-executor"],
+        "complexity": "medium",
+        "testCoverage": 85,
+        "notes": ["Usa react-hook-form", "Validación con zod"]
+      }
+    },
+    "functions": {
+      "validateCredentials": {
+        "file": "src/lib/auth/validators.ts",
+        "signature": "(email: string, password: string) => Promise<User | null>",
+        "purpose": "Valida credenciales contra la base de datos",
+        "sideEffects": ["database-read"],
+        "calledBy": ["LoginForm", "API route"],
+        "calls": ["prisma.user.findUnique", "bcrypt.compare"]
+      }
+    },
+    "components": {
+      "LoginForm": {
+        "file": "src/components/Auth/LoginForm.tsx",
+        "props": ["onSuccess", "onError", "redirectUrl"],
+        "state": ["isLoading", "error"],
+        "hooks": ["useForm", "useAuth"],
+        "children": ["Button", "Input", "ErrorMessage"]
+      }
+    },
+    "relationships": {
+      "authentication": {
+        "entry": "src/app/api/auth/[...nextauth]/route.ts",
+        "components": ["LoginForm", "RegisterForm", "ForgotPassword"],
+        "services": ["AuthService", "EmailService"],
+        "database": ["User", "Session", "Account"]
+      }
+    }
+  }
+}
+```
+
+### 4. Contextual Memory (RAG)
+
+**Propósito**: Recuperación semántica de contexto relevante.
+
+**Duración**: Índice persistente, actualizado incrementalmente.
+
+**Contenido**:
+- Embeddings del codebase
+- Documentación indexada
+- Historial de conversaciones relevantes
+- Decisiones arquitectónicas
+
+```json
+{
+  "contextualMemory": {
+    "index": {
+      "provider": "pinecone",
+      "namespace": "project-my-app",
+      "dimensions": 1536,
+      "lastUpdated": "2024-01-20T16:00:00Z",
+      "documentCount": 245
+    },
+    "sources": [
+      {
+        "type": "codebase",
+        "path": "src/",
+        "indexed": 180,
+        "lastIndexed": "2024-01-20T15:55:00Z"
+      },
+      {
+        "type": "documentation",
+        "path": "docs/",
+        "indexed": 35,
+        "lastIndexed": "2024-01-19T10:00:00Z"
+      },
+      {
+        "type": "conversations",
+        "count": 30,
+        "lastIndexed": "2024-01-20T16:00:00Z"
+      }
+    ],
+    "recentQueries": [
+      {
+        "query": "authentication flow",
+        "results": ["src/lib/auth/index.ts", "docs/auth.md"],
+        "at": "2024-01-20T15:45:00Z"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## API del Sistema de Memoria
+
+### MemoryManager
+
+```javascript
+/**
+ * MemoryManager
+ * Gestiona los 4 niveles de memoria de ELSABRO
+ */
+class MemoryManager {
+  constructor(projectPath = '.planning') {
+    this.projectPath = projectPath;
+    this.shortTerm = new ShortTermMemory();
+    this.longTerm = new LongTermMemory(projectPath);
+    this.entity = new EntityMemory(projectPath);
+    this.contextual = new ContextualMemory(projectPath);
+  }
+
+  // ==================== Short-Term ====================
+
+  /**
+   * Registra una decisión en la sesión actual
+   */
+  async recordDecision(decision) {
+    return this.shortTerm.addDecision({
+      question: decision.question,
+      decision: decision.answer,
+      reasoning: decision.reasoning,
+      alternatives: decision.alternatives || [],
+      decidedAt: new Date().toISOString()
+    });
+  }
+
+  /**
+   * Registra acceso a archivo
+   */
+  async recordFileAccess(filePath, action) {
+    return this.shortTerm.addFileAccess({
+      path: filePath,
+      action, // 'read' | 'created' | 'modified' | 'deleted'
+      at: new Date().toISOString()
+    });
+  }
+
+  /**
+   * Obtiene contexto de la sesión actual
+   */
+  async getSessionContext() {
+    return this.shortTerm.getContext();
+  }
+
+  // ==================== Long-Term ====================
+
+  /**
+   * Aprende un nuevo patrón
+   */
+  async learnPattern(pattern) {
+    // Verificar si ya existe similar
+    const existing = await this.longTerm.findSimilarPattern(pattern);
+
+    if (existing) {
+      return this.longTerm.reinforcePattern(existing.id);
+    }
+
+    return this.longTerm.addPattern({
+      name: pattern.name,
+      description: pattern.description,
+      example: pattern.example,
+      context: pattern.context || [],
+      usageCount: 1
+    });
+  }
+
+  /**
+   * Registra un error para no repetirlo
+   */
+  async learnFromMistake(mistake) {
+    const existing = await this.longTerm.findSimilarMistake(mistake);
+
+    if (existing) {
+      return this.longTerm.incrementMistakeOccurrence(existing.id);
+    }
+
+    return this.longTerm.addMistake({
+      description: mistake.description,
+      correction: mistake.correction,
+      severity: mistake.severity || 'medium',
+      context: mistake.context || []
+    });
+  }
+
+  /**
+   * Obtiene patrones relevantes para contexto actual
+   */
+  async getRelevantPatterns(context) {
+    return this.longTerm.queryPatterns(context);
+  }
+
+  /**
+   * Obtiene errores a evitar para contexto actual
+   */
+  async getMistakesToAvoid(context) {
+    return this.longTerm.queryMistakes(context);
+  }
+
+  // ==================== Entity ====================
+
+  /**
+   * Actualiza información de un archivo
+   */
+  async updateFileEntity(filePath, info) {
+    return this.entity.updateFile(filePath, {
+      ...info,
+      lastModified: new Date().toISOString()
+    });
+  }
+
+  /**
+   * Obtiene información de un archivo
+   */
+  async getFileInfo(filePath) {
+    return this.entity.getFile(filePath);
+  }
+
+  /**
+   * Obtiene relaciones de una entidad
+   */
+  async getRelationships(entityName) {
+    return this.entity.getRelationships(entityName);
+  }
+
+  /**
+   * Mapea el codebase completo
+   */
+  async mapCodebase(rootPath) {
+    return this.entity.scanAndIndex(rootPath);
+  }
+
+  // ==================== Contextual ====================
+
+  /**
+   * Busca contexto relevante semánticamente
+   */
+  async searchContext(query, options = {}) {
+    const { limit = 5, threshold = 0.7 } = options;
+
+    return this.contextual.search(query, {
+      limit,
+      threshold,
+      sources: ['codebase', 'documentation', 'conversations']
+    });
+  }
+
+  /**
+   * Indexa nuevo contenido
+   */
+  async indexContent(content, metadata) {
+    return this.contextual.index(content, metadata);
+  }
+
+  /**
+   * Re-indexa el codebase
+   */
+  async reindexCodebase() {
+    return this.contextual.reindex('codebase');
+  }
+
+  // ==================== Cross-Memory ====================
+
+  /**
+   * Obtiene todo el contexto relevante para una tarea
+   */
+  async getFullContext(task) {
+    const [patterns, mistakes, entities, contextual] = await Promise.all([
+      this.getRelevantPatterns(task.context),
+      this.getMistakesToAvoid(task.context),
+      this.entity.getRelevantEntities(task.files || []),
+      this.searchContext(task.description)
+    ]);
+
+    return {
+      patterns,
+      mistakes,
+      entities,
+      relatedContent: contextual,
+      sessionContext: await this.getSessionContext()
+    };
+  }
+
+  /**
+   * Guarda estado de memoria para checkpoint
+   */
+  async saveToCheckpoint() {
+    return {
+      shortTerm: await this.shortTerm.serialize(),
+      longTermSummary: await this.longTerm.getSummary(),
+      entitySummary: await this.entity.getSummary()
+    };
+  }
+
+  /**
+   * Restaura estado de memoria desde checkpoint
+   */
+  async restoreFromCheckpoint(data) {
+    await this.shortTerm.deserialize(data.shortTerm);
+    // Long-term y entity se cargan desde archivos
+  }
+}
+```
+
+---
+
+## Integración con Agentes
+
+### Antes de Ejecutar Agente
+
+```javascript
+async function prepareAgentContext(agent, task) {
+  const memory = new MemoryManager();
+
+  // Obtener contexto completo
+  const context = await memory.getFullContext(task);
+
+  // Inyectar en prompt del agente
+  return `
+## Contexto de Memoria
+
+### Patrones a Seguir
+${context.patterns.map(p => `- ${p.name}: ${p.description}`).join('\n')}
+
+### Errores a Evitar
+${context.mistakes.map(m => `- ⚠️ ${m.description} → ${m.correction}`).join('\n')}
+
+### Archivos Relevantes
+${context.entities.map(e => `- ${e.path}: ${e.purpose}`).join('\n')}
+
+### Contexto Adicional
+${context.relatedContent.map(c => `- ${c.source}: ${c.summary}`).join('\n')}
+
+## Tarea
+${task.description}
+  `;
+}
+```
+
+### Después de Ejecutar Agente
+
+```javascript
+async function processAgentResult(agent, result) {
+  const memory = new MemoryManager();
+
+  // Registrar archivos modificados
+  for (const file of result.filesModified) {
+    await memory.recordFileAccess(file.path, 'modified');
+    await memory.updateFileEntity(file.path, {
+      modifiedBy: [agent],
+      purpose: file.purpose
+    });
+  }
+
+  // Aprender de decisiones
+  for (const decision of result.decisions) {
+    await memory.recordDecision(decision);
+
+    // Si es un patrón reutilizable, guardarlo
+    if (decision.isPattern) {
+      await memory.learnPattern({
+        name: decision.patternName,
+        description: decision.reasoning,
+        example: decision.implementation
+      });
+    }
+  }
+
+  // Aprender de errores corregidos
+  for (const error of result.errorsFixed) {
+    await memory.learnFromMistake({
+      description: error.original,
+      correction: error.fix,
+      severity: error.severity
+    });
+  }
+}
+```
+
+---
+
+## Comandos de Usuario
+
+### /elsabro:memory
+
+```bash
+/elsabro:memory show            # Ver estado de memoria
+/elsabro:memory patterns        # Ver patrones aprendidos
+/elsabro:memory mistakes        # Ver errores a evitar
+/elsabro:memory search <query>  # Buscar en memoria contextual
+/elsabro:memory forget <id>     # Olvidar un item específico
+/elsabro:memory export          # Exportar memoria a JSON
+/elsabro:memory import <file>   # Importar memoria desde JSON
+/elsabro:memory reindex         # Re-indexar memoria contextual
+```
+
+---
+
+## Archivos de Memoria
+
+### Estructura de Directorios
+
+```
+.planning/
+├── memory/
+│   ├── short-term/
+│   │   └── session-{id}.json      # Estado de sesión actual
+│   ├── long-term/
+│   │   ├── patterns.json          # Patrones aprendidos
+│   │   ├── mistakes.json          # Errores a evitar
+│   │   ├── preferences.json       # Preferencias del usuario
+│   │   └── learnings.json         # Aprendizajes acumulados
+│   ├── entity/
+│   │   ├── files.json             # Info de archivos
+│   │   ├── functions.json         # Info de funciones
+│   │   ├── components.json        # Info de componentes
+│   │   └── relationships.json     # Relaciones entre entidades
+│   └── contextual/
+│       ├── index.json             # Metadata del índice
+│       └── embeddings/            # Embeddings locales (opcional)
+├── patterns.md                    # Versión legible de patterns
+├── mistakes.md                    # Versión legible de mistakes
+└── CLAUDE.md                      # Resumen para Claude
+```
+
+---
+
+## Triggers de Aprendizaje
+
+### Detección Automática
+
+El sistema detecta oportunidades de aprendizaje:
+
+| Trigger | Acción |
+|---------|--------|
+| Usuario corrige código | Aprender patrón/error |
+| Usuario dice "siempre usa X" | Guardar preferencia |
+| Mismo error 3+ veces | Elevar severidad |
+| Patrón usado 5+ veces | Marcar como establecido |
+| Usuario elogia resultado | Reforzar patrón |
+
+### Frases de Trigger
+
+```javascript
+const LEARNING_TRIGGERS = {
+  pattern: [
+    /siempre (usa|haz|prefiero)/i,
+    /en este proyecto (usamos|preferimos)/i,
+    /la convención es/i,
+    /mejor así/i
+  ],
+  mistake: [
+    /no,? (hazlo|así no)/i,
+    /eso está mal/i,
+    /nunca (uses|hagas)/i,
+    /evita/i
+  ],
+  preference: [
+    /prefiero/i,
+    /me gusta más/i,
+    /usa .* en vez de/i
+  ]
+};
+```
+
+---
+
+## Configuración
+
+### .planning/memory-config.json
+
+```json
+{
+  "memory": {
+    "shortTerm": {
+      "maxConversationLength": 50,
+      "maxDecisions": 100,
+      "persistOnPause": true
+    },
+    "longTerm": {
+      "maxPatterns": 200,
+      "maxMistakes": 100,
+      "autoLearn": true,
+      "confirmBeforeLearn": false,
+      "decayEnabled": false
+    },
+    "entity": {
+      "autoScan": true,
+      "scanInterval": "on-change",
+      "includePatterns": ["src/**/*", "lib/**/*"],
+      "excludePatterns": ["node_modules/**", "dist/**"]
+    },
+    "contextual": {
+      "provider": "local",
+      "embeddingModel": "text-embedding-3-small",
+      "chunkSize": 500,
+      "chunkOverlap": 50,
+      "autoReindex": true
+    }
+  }
+}
+```