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

📖 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?

💻 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

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