🧠 Self-Improving Memory System

npm version License: MIT Node.js GitHub Stars

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:

Crea backup con timestamp
Preserva todos los mcpServers existentes
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

📖 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 ( 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:

✅ 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

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.

Self-Improving Memory MCP