🧠 Self-Improving Memory System

Sistema de memoria auto-evolutivo para Claude Code CLI. Captura automáticamente decisiones, errores, soluciones y patrones, evaluando confianza, evitando repetir trabajo y errores. Nunca pierde contexto gracias al sistema anti-compactación.

💡 Para Claude Code CLI únicamente - No compatible con Claude Desktop

---

🚀 Quick Start

Super Easy Install (2 minutes)

# Install globally
npm install -g @pytt0n/self-improving-memory-mcp

# Navigate to your project
cd /path/to/your/project

# Run installer
memory-install

# Reload Claude Code - Done! 🎉

That's it! The memory system is now active in your project.

Clean install by default: No files are copied to your project. The plugin runs from node_modules. Want to customize? Run memory-install --custom to copy files to .claude-mcp/ for editing.

⚠️ Requiere Claude Code CLI: Este plugin funciona exclusivamente con Claude Code (CLI), no con Claude Desktop.

✅ Sin Colisiones con Otras Configuraciones

El instalador preserva automáticamente tus configuraciones MCP existentes:

• ✅ Fusiona en vez de sobrescribir
• ✅ Nombre único del servidor: self-improving-memory
• ✅ Backup automático antes de modificar
• ✅ Compatible con otros plugins MCP

Si ya tienes mcp.json con otros servidores, el instalador:

1. Crea backup con timestamp
2. Preserva todos los mcpServers existentes
3. Agrega solo el servidor de memoria
4. Pregunta antes de actualizar si ya existe

📖 Quick Install Guide | Full Installation Guide

---

✨ Características Principales

🤖 10 Agentes Automáticos

Sistema proactivo que aprende y optimiza sin intervención manual:

Agente	Cuándo se Activa	Qué Hace
💬 User Intent Capture	Al recibir requests	Captura qué quiere el usuario
🔍 Pattern Recognition	Antes de tareas	Busca conocimiento previo
❌ Error Detection	Al ocurrir errores	Registra errores en memoria
✅ Solution Capture	Al resolver problemas	Guarda soluciones exitosas
📋 Decision Tracker	Al tomar decisiones	Recuerda el por qué
🎨 Style Preferences	Después de escribir código	Aprende tu estilo
💾 Session Context	Al interrumpir trabajo	Preserva el progreso
🚨 Pre-Compact Interceptor	A 80% de contexto	Evita pérdida automática
💡 Context Recovery	Al iniciar conversación	Recupera estado completo
🎯 Confidence Evaluator	Después de aplicar conocimiento	Ajusta calidad

📖 Ver documentación completa de agentes

---

🛡️ Sistema Anti-Compactación

Problema resuelto: Claude tiene límite de 200k tokens. Al alcanzarlo, autocompact elimina información.

Nuestra solución:

• ⚡ Monitoreo automático de tokens (checkpoint a 80%)
• 💾 Guardado completo del estado antes de pérdida
• 🔄 Recuperación perfecta en nueva conversación
• ✅ Resultado: Conversaciones infinitas sin pérdida de contexto

📖 Cómo funciona el sistema anti-compactación

---

🗂️ 17 Tipos de Entidades

El sistema captura conocimiento estructurado en 17 tipos:

Proyecto & Código:

• project, component, dependency

Aprendizaje:

• error, solution, pattern, insight, decision

Usuario:

• user-intent, user-preference, requirement

Estilo:

• style-rule, architectural-pattern, tool-preference

Sesiones:

• session-snapshot, continuation-point, work-in-progress

---

🎯 ¿Por Qué Usar Este Sistema?

Problema	Solución
❌ Repetir trabajo	✅ Pattern Recognition busca automáticamente conocimiento previo
❌ Repetir errores	✅ Error Detection + Solution Capture crean base de soluciones
❌ Perder contexto	✅ Anti-compaction system preserva 100% del estado
❌ Olvidar decisiones	✅ Decision Tracker registra el razonamiento completo
❌ No aprender preferencias	✅ Style Preferences + User Intent aprenden tu forma de trabajar
❌ Interrupciones costosas	✅ Session Context permite retomar exactamente donde dejaste

---

💻 Tres Formas de Usar el Sistema

1. MCP Tools (Automático desde Claude)

Los agentes funcionan automáticamente. No requieres hacer nada.

Claude detecta tu request → Agentes se activan → Aprendizaje automático

2. Slash Commands (Comandos Rápidos)

/memory-search "authentication"
/memory-stats
/checkpoint
/mh  # Menú de ayuda interactivo

📖 Lista completa de comandos

3. CLI (Terminal)

memory-cli stats
memory-cli search "postgresql"
memory-cli list error
memory-cli export

---

📊 Ejemplo de Workflow

1. 💬 Usuario: "Implementa autenticación JWT"
   → User Intent Capture registra el objetivo

2. 🔍 Claude ejecuta Pattern Recognition
   → Encuentra decisión previa: "Usar bcrypt para passwords"

3. 🛠️ Claude implementa código
   → Style Preferences aprende patrones de código

4. ❌ Error: "bcrypt not installed"
   → Error Detection captura el error

5. ✅ Claude lo resuelve: npm install bcrypt
   → Solution Capture vincula solución al error

6. 📋 Decisión: "JWT expiration: 7 days"
   → Decision Tracker registra la decisión + razones

7. 🚨 Contexto al 85% → Pre-Compact Interceptor
   → Checkpoint automático, resumen generado

8. 💡 Nueva conversación
   → Context Recovery carga todo automáticamente
   → Continúa sin pérdida de información

---

🏗️ Arquitectura

┌─────────────────────────────────────────────────┐
│  3 Interfaces de Acceso                         │
│  • MCP Tools  • Slash Commands  • CLI           │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────┐
│  MCP Server (index.js)                          │
│  • API Layer                                    │
│  • 17 herramientas MCP                          │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────┐
│  KnowledgeStore (lógica de negocio)             │
│  • Gestión de entidades y relaciones            │
│  • Sistema de confianza                         │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────┐
│  VectorStore (vector-store.js)                  │
│  • LanceDB - Base de datos vectorial            │
│  • Transformers.js - Embeddings (384D)          │
│  • Búsqueda semántica                           │
└─────────────────────────────────────────────────┘

📖 Arquitectura detallada

---

📦 Estructura del Proyecto

En tu proyecto (después de instalar):

tu-proyecto/
├── tu-codigo/                  # Tu código existente
├── .gitignore                  # Actualizado automáticamente
└── .claude-memory/             # Base de datos vectorial (auto-creada)
    └── vectors/
        └── lancedb/

Modo clean (default): CERO archivos del plugin en tu proyecto. Todo funciona desde node_modules.

Modo custom (--custom): Agrega .claude-mcp/ con agentes editables.

Estructura del package NPM:

@pytt0n/self-improving-memory-mcp/
├── index.js                    # MCP Server (~400 líneas)
├── memory-cli.js               # CLI Tool (~300 líneas)
├── bin/install.js              # Instalador interactivo
│
├── .claude/                    # Archivos de configuración
│   ├── CLAUDE.md              # Instrucciones para Claude
│   ├── agents/                # 10 agentes automáticos
│   └── commands/              # Slash commands
│
├── src/                        # Código fuente modular
│   ├── knowledge-store.js
│   ├── vector-store.js
│   └── utils/
│
├── docs/                       # Documentación completa
└── tests/                      # 263 tests (>85% coverage)

Nota: Mantenemos archivos <500 líneas siguiendo principios SOLID y organización modular.

---

🔧 Stack Tecnológico

Tecnología	Versión	Propósito
LanceDB	v0.22.1	Base de datos vectorial persistente
Transformers.js	v2.17.2	Embeddings semánticos (all-MiniLM-L6-v2)
MCP SDK	latest	Protocol comunicación con Claude Desktop
Node.js	v18+	Runtime (ES Modules)

---

📖 Documentación Completa

• 📘 Instalación - Configuración paso a paso
• 🤖 Agentes - Los 10 agentes automáticos
• 🏗️ Arquitectura - Diseño del sistema
• 🛡️ Anti-Compactación - Sistema de preservación de contexto
• ⚡ Comandos - Slash commands y CLI
• 🔌 API Reference - Herramientas MCP
• ✅ Mejores Prácticas - Cómo usar eficientemente

---

🗺️ Roadmap

Ver ROADMAP.md para el plan completo de mejoras futuras.

Próximas prioridades:

• 🧪 Framework de testing completo
• 📊 Dashboard de visualización de conocimiento
• 🔄 Auto-refactoring de código duplicado
• 🌐 API REST para integración externa
• 📈 Métricas de performance y optimización

---

🔧 Actualizaciones Recientes

v2.0.1 (2025-10-07): Documentación Completa + Correcciones

✅ Documentación al 100%:

• 📝 CHANGELOG.md: Guía completa de migración v1.x → v2.0
• ⚡ docs/PERFORMANCE.md: Benchmarks reales (263 tests, métricas detalladas)
• 🔧 docs/INSTALLATION.md: Paths de configuración corregidos
• 📖 docs/COMMANDS.md: Reorganizado (MCP Tools / CLI / Slash Commands)
• ✅ docs/API.md: 17/17 herramientas documentadas

🐛 Correcciones:

• Fixed Claude Desktop config paths (macOS/Linux/Windows)
• Slash commands /checkpoint y /memory-help documentados
• Tool count corregido en README y QUICK-INSTALL

📊 Estado:

• Calidad de documentación: 100% ✅
• Listo para publicación profesional

📖 Ver CHANGELOG completo

---

2025-10-07: Corrección Crítica del Sistema Anti-Compactación

Problema identificado: El sistema de interceptación de autocompact no se activaba automáticamente.

Causa: Las instrucciones en .claude/CLAUDE.md eran pasivas ("Monitor token usage") en lugar de activas con triggers explícitos.

Solución implementada:

1. ✅ Header visual obligatorio al inicio de CLAUDE.md:

   ⚠️ CHECK CONTEXT USAGE FIRST - MANDATORY ⚠️
   If >= 160k tokens (80%): STOP and launch Pre-Compact Interceptor
   

2. ✅ Protocolo de monitoreo explícito con 3 pasos:

   • Step 1: Check on EVERY response
   • Step 2: Checkpoint Protocol (STOP → save → present summary)
   • Step 3: Recovery (auto-load in new conversation)

3. ✅ Reglas de trigger sin excepciones:

   • Tokens >= 160k (80%): TRIGGER
   • Messages >= 40: TRIGGER
   • Before large ops: Estimate & TRIGGER

4. ✅ Context Recovery más proactivo:

   • Se activa en TODAS las conversaciones nuevas (primeros 1-2 mensajes)
   • Búsqueda automática de checkpoints < 24 horas
   • Presenta opción de recuperación sin que usuario pregunte

5. ✅ Documentación de testing completa:

   • Nuevo archivo: docs/CHECKPOINT-TESTING.md
   • 6 escenarios de prueba detallados
   • Guía de troubleshooting
   • Métricas de éxito

Impacto: CRÍTICO - Este es el mecanismo que previene pérdida de información en conversaciones largas. Sin esto, el sistema pierde contexto cuando autocompact se activa (~200k tokens).

Estado: ✅ CORREGIDO

📖 Ver guía completa de testing 📖 Ver detalles técnicos en PROGRESS.md

---

🤝 Contribuir

¿Ideas para mejorar el sistema?

1. Revisa el ROADMAP.md
2. Abre un issue con tu propuesta
3. Las contribuciones son bienvenidas

Principios del proyecto:

• ✅ Archivos <500 líneas (SOLID cuando necesario)
• ✅ Documentación clara con referencias
• ✅ Tests para funcionalidad crítica
• ✅ Auto-aprendizaje automático, no manual

---

📄 Licencia

MIT

---

🧠 El conocimiento de tu proyecto ahora tiene memoria perpetua. Claude nunca olvida.