🧠 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? Runmemory-install --customto 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:
- Crea backup con timestamp
- Preserva todos los
mcpServersexistentes - Agrega solo el servidor de memoria
- 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
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 │
└─────────────────────────────────────────────────┘
📦 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
/checkpointy/memory-helpdocumentados - Tool count corregido en README y QUICK-INSTALL
📊 Estado:
- Calidad de documentación: 100% ✅
- Listo para publicación profesional
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:
-
✅ Header visual obligatorio al inicio de CLAUDE.md:
⚠️ CHECK CONTEXT USAGE FIRST - MANDATORY ⚠️ If >= 160k tokens (80%): STOP and launch Pre-Compact Interceptor -
✅ 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)
-
✅ Reglas de trigger sin excepciones:
- Tokens >= 160k (80%): TRIGGER
- Messages >= 40: TRIGGER
- Before large ops: Estimate & TRIGGER
-
✅ 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
-
✅ Documentación de testing completa:
- Nuevo archivo:
docs/CHECKPOINT-TESTING.md - 6 escenarios de prueba detallados
- Guía de troubleshooting
- Métricas de éxito
- Nuevo archivo:
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?
- Revisa el ROADMAP.md
- Abre un issue con tu propuesta
- 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.