🧠 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.

This server cannot be installed

security - not tested

license - not tested

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Provides Claude with persistent memory and learning capabilities through 10 automatic agents that capture decisions, errors, solutions, and patterns across conversations. Features an anti-compaction system to prevent context loss and enables infinite conversation continuity.

Self-Improving Memory MCP