ContextKeeper

Proporciona memoria perfecta para el desarrollo asistido por IA al capturar instantáneas del contexto del proyecto, permitiendo búsqueda en lenguaje natural, seguimiento de evolución e inteligencia de código.

GitHub

Prueba este MCPPatrocinado

Documentación

ContextKeeper 🧠

El servidor del Protocolo de Contexto de Modelo (MCP) con memoria perfecta para desarrollo asistido por IA

ContextKeeper revoluciona el desarrollo asistido por IA al resolver el problema fundamental de la pérdida de contexto entre sesiones. Utilizando una arquitectura inspirada en LSM-tree, mantiene un historial completo y buscable de la evolución de tu proyecto, asegurando que tu asistente de IA nunca olvide.

🌟 Características Clave

📸 Captura Integral de Contexto

Instantáneas de Desarrollo: Captura el estado completo del proyecto, incluyendo contexto de git, información del espacio de trabajo y documentación
Disparadores Automáticos: Los hooks de Git (pre-commit, post-checkout) capturan contexto automáticamente
Archivado Inteligente: La compactación inspirada en LSM-tree mantiene el almacenamiento eficiente mientras preserva el historial
Seguimiento de Hitos: Etiqueta instantáneas con hitos significativos para referencia fácil

🤖 Diseño Nativo para IA

Búsqueda en Lenguaje Natural: Pregunta "¿cuándo agregamos autenticación?" y obtén respuestas instantáneas
Perspectivas de Evolución: Rastrea cómo evolucionaron los componentes de "Planificado" a "Completado"
Análisis Consciente del Contexto: Extracción inteligente de palabras clave y recomendaciones
Memoria Perfecta: Tu asistente de IA recuerda todo entre sesiones

🔧 Herramientas del Protocolo de Contexto de Modelo (MCP)

Seis herramientas poderosas para asistentes de IA:

snapshot - Crea instantáneas de contexto integrales
search_evolution - Búsqueda en lenguaje natural a través del historial del proyecto
track_component - Sigue la evolución de funciones a lo largo del tiempo
compare_snapshots - Compara dos instantáneas
get_status - Estado del sistema con perspectivas de compactación
get_timeline - Vista cronológica de la evolución del proyecto

💻 Inteligencia de Código C#

Cinco herramientas de análisis de código impulsadas por Roslyn:

FindSymbolDefinitions - Localiza declaraciones de símbolos
FindSymbolReferences - Encuentra todos los usos
NavigateInheritanceHierarchy - Explora relaciones de tipos
SearchSymbolsByPattern - Coincidencia de patrones con comodines
GetSymbolDocumentation - Extrae documentación XML

📝 Espacio de Trabajo del Usuario

Área de documentación flexible accesible mediante el símbolo @ de Claude:

Requisitos: Almacena especificaciones del proyecto e historias de usuario
Diseño: Documenta decisiones arquitectónicas y patrones
Instrucciones: Directrices personalizadas para el asistente de IA
Captura Automática: Los archivos del espacio de trabajo se incluyen en todas las instantáneas

🚀 Inicio Rápido

Instalación

# Clone the repository
git clone https://github.com/chasecuppdev/contextkeeper-mcp.git
cd contextkeeper-mcp

# Build the project
dotnet build

# Run as MCP server
dotnet run --project src/ContextKeeper

Uso Básico

# Initialize ContextKeeper in your project
dotnet run --project src/ContextKeeper -- init

# Create a manual snapshot
dotnet run --project src/ContextKeeper -- snapshot "feature-complete"

# Search project history
dotnet run --project src/ContextKeeper -- search "authentication"

# Check system status
dotnet run --project src/ContextKeeper -- check

Integración con Git

# Install git hooks for automatic capture
dotnet run --project src/ContextKeeper -- init --git-hooks

# Now snapshots are created automatically on:
# - Pre-commit: Captures state before committing
# - Post-checkout: Captures state after branch switches

📁 Arquitectura

Estructura de Almacenamiento

.contextkeeper/
├── snapshots/          # Active snapshots
│   ├── SNAPSHOT_2025-06-24_manual_feature-complete.md
│   └── SNAPSHOT_2025-06-24_git-commit_abc123.md
└── archived/           # Compacted history
    └── ARCHIVED_2024-01-01_2024-03-31_COMPACTED.md

context-workspace/      # User-accessible workspace (visible in Claude's @)
├── workspace/          # Your custom documentation
│   ├── requirements/   # Project requirements
│   ├── design/        # Design decisions
│   └── instructions/  # AI instructions
└── project-history/   # ContextKeeper development docs

Formato de Instantánea

Cada instantánea captura:

Contexto de Git: Rama, commit, archivos sin confirmar
Información del Espacio de Trabajo: Directorio de trabajo, comandos recientes
Documentación: Todos los archivos markdown (CLAUDE.md, README.md, etc.)
Metadatos: Marca de tiempo, tipo, hito, contexto completo como JSON

Auto-Compactación

El archivado automático se activa cuando:

El número de instantáneas supera el umbral (configurable, predeterminado: 20)
Existen instantáneas con más de 90 días de antigüedad
Operación en segundo plano no bloqueante después de la creación de instantáneas

🤝 Integración MCP

Con Claude Desktop

Agrega a tu configuración de Claude Desktop (~/.claude.json):

{
  "mcpServers": {
    "contextkeeper": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/contextkeeper/src/ContextKeeper"],
      "env": {}
    }
  }
}

Importante: Asegúrate de:

Reemplazar /path/to/contextkeeper con la ruta real a tu instalación de ContextKeeper
Incluir "type": "stdio" en la configuración
Mantener command y args como campos separados (no los combines)

Con Otros Clientes MCP

ContextKeeper implementa el protocolo MCP estándar y funciona con cualquier cliente compatible. El servidor proporciona descubrimiento de herramientas y comunicación basada en JSON.

🛠️ Configuración

Archivo de Configuración (`contextkeeper.config.json`)

{
  "version": "2.0",
  "paths": {
    "history": ".contextkeeper",
    "snapshots": ".contextkeeper/snapshots",
    "archived": ".contextkeeper/archived",
    "userWorkspace": "context-workspace/workspace"
  },
  "snapshot": {
    "dateFormat": "yyyy-MM-dd",
    "filenamePattern": "SNAPSHOT_{date}_{type}_{milestone}.md",
    "autoCapture": true,
    "autoCaptureIntervalMinutes": 30
  },
  "compaction": {
    "threshold": 20,
    "maxAgeInDays": 90,
    "autoCompact": true
  },
  "contextTracking": {
    "trackOpenFiles": true,
    "trackGitState": true,
    "trackRecentCommands": true,
    "documentationFiles": ["*.md"],
    "ignorePatterns": ["node_modules", "bin", "obj", ".git"]
  }
}

Variables de Entorno

CONTEXTKEEPER_PROFILE - Sobrescribe el perfil auto-detectado
CONTEXTKEEPER_DEBUG - Habilita el registro de depuración

📊 Rendimiento y Benchmarks

Métricas de AOT Nativo

Tiempo de Inicio: ~12ms (vs ~200ms JIT)
Tamaño del Binario: Ejecutable independiente de 41MB (incluye Roslyn)
Uso de Memoria: 18MB típico (reducción del 78% vs JIT)
Velocidad de Búsqueda: <100ms para 1000+ instantáneas

Benchmarks de Operaciones

Snapshot Creation:     8ms   (10,000 lines)
Search (1000 docs):   45ms   (full-text)
Compaction (100MB):  280ms   (70% size reduction)
Symbol Search:        12ms   (50K symbols)

Eficiencia de Almacenamiento

Instantáneas crudas: 100MB → Compactadas: 28MB (reducción del 72%)
Tasa de deduplicación: 85% para instantáneas similares
Compresión: Gzip logrando una relación de 3:1

🧪 Desarrollo

Requisitos Previos

SDK de .NET 9.0
Visual Studio 2022 o VS Code con extensión de C#

Compilación desde el Código Fuente

# Clone repository
git clone https://github.com/chasecuppdev/contextkeeper-mcp.git
cd contextkeeper-mcp

# Restore dependencies
dotnet restore

# Build
dotnet build

# Run tests
dotnet test

# Build Native AOT (requires platform-specific SDK)
dotnet publish -c Release -r linux-x64 -p:PublishAot=true

Pruebas

El proyecto incluye un conjunto de pruebas integral con 98 pruebas que cubren:

Funcionalidad principal (instantáneas, búsqueda, seguimiento de evolución)
Motor de compactación y optimización de almacenamiento
Implementación del protocolo MCP
Integración de análisis de código Roslyn
Escenarios de integración

Ejecuta las pruebas con:

# Run all tests
dotnet test

# Run with detailed output
dotnet test --verbosity detailed

# Run specific test category
dotnet test --filter "Category=Integration"

Estructura del Proyecto

contextkeeper-mcp/
├── src/
│   └── ContextKeeper/
│       ├── Config/          # Configuration management
│       ├── Core/            # Core services
│       ├── Protocol/        # MCP implementation
│       ├── CodeAnalysis/    # Roslyn integration
│       └── Utils/           # Utilities
├── tests/
│   └── ContextKeeper.Tests/ # Comprehensive test suite
└── docs/                    # Additional documentation

🎯 Demo Rápida

Ejemplo: "¿Cuándo agregamos autenticación?"

$ dotnet run -- search "authentication"

Found 3 matches across history:
📅 2025-06-15: First mention in requirements (Status: Planned)
📅 2025-06-18: Implementation started (Status: In Progress)
📅 2025-06-22: Completed with JWT integration (Status: Completed)

Ejemplo: Seguimiento de Evolución de Funciones

$ dotnet run -- evolution "payment system"

Evolution Timeline:
└── 2025-06-10: Initial design discussion
    └── 2025-06-15: API specification defined
        └── 2025-06-20: Stripe integration chosen
            └── 2025-06-25: Production deployment

🏗️ Inmersión Técnica Profunda

Arquitectura Inspirada en LSM-Tree

ContextKeeper implementa un enfoque de árbol de fusión estructurado por registros para almacenamiento eficiente:

Ruta de Escritura: Las nuevas instantáneas se agregan a la capa activa (escrituras O(1))
Compactación: La fusión en segundo plano reduce el almacenamiento en un 70%
Ruta de Lectura: Búsqueda binaria entre instantáneas ordenadas (O(log n))
Memoria: Filtros Bloom para verificaciones rápidas de existencia

Compilación AOT Nativa

Aprovechando el AOT nativo de .NET 9 para rendimiento en producción:

# Compile to native binary (41MB with Roslyn included)
dotnet publish -c Release -r linux-x64 -p:PublishAot=true

# Startup comparison:
# JIT: ~200ms | AOT: ~12ms (16x faster)
# Memory: 85MB → 18MB (78% reduction)

Implementación del Protocolo MCP

Servidor completo del Protocolo de Contexto de Modelo con:

Capa de transporte JSON-RPC 2.0
Descubrimiento e introspección de herramientas
Respuestas en streaming para grandes conjuntos de datos
Manejo de errores según la especificación MCP

Inmersión Profunda en la Integración de Roslyn

Capacidades avanzadas de análisis de código C#:

// Example: Find all implementations of IRepository
var implementations = await FindSymbolReferences("IRepository");
// Returns: UserRepository, ProductRepository, OrderRepository

// Navigate inheritance hierarchy
var hierarchy = await NavigateInheritance("BaseController");
// Returns full inheritance tree with 15 derived controllers

🤔 ¿Por qué ContextKeeper?

El Problema

Los asistentes de IA pierden contexto entre sesiones, obligando a los desarrolladores a explicar repetidamente el historial del proyecto, las decisiones arquitectónicas y los detalles de implementación.

La Solución

ContextKeeper mantiene un historial completo y buscable de la evolución de tu proyecto. Tu asistente de IA puede acceder instantáneamente a:

Cuándo y por qué se agregaron funciones
Cómo evolucionaron los componentes a lo largo del tiempo
Contexto completo desde cualquier punto del historial
Documentación buscable en lenguaje natural

Impacto en el Mundo Real

Extraído originalmente de CodeCartographerAI, ContextKeeper ha demostrado su valor en producción:

Reducción del 80% en la re-explicación de contexto
Consultas históricas casi instantáneas (<100ms para 1000+ instantáneas)
Recuerdo perfecto a lo largo de meses de desarrollo
Integración perfecta con asistentes de IA

Ejemplo Concreto: Depuración de un Problema de Producción

Developer: "When did we change the user authentication flow?"
AI (using ContextKeeper): "According to the history:
- June 15: Original OAuth2 implementation
- June 22: Added 2FA support (commit abc123)
- June 28: Switched to JWT tokens (security audit)
The JWT change on June 28 might be related to your production issue."

🗺️ Hoja de Ruta

Corto Plazo

Interfaz de línea de tiempo visual (interfaz web)
Recuperación de contexto (restaurar estado completo de desarrollo)
Extensión de VS Code
Resúmenes de IA mejorados

Futuro

Sincronización de equipos
Exportación a Confluence/Notion
Port a TypeScript para adopción más amplia
Panel de métricas

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lee nuestra Guía de Contribución para detalles sobre nuestro código de conducta y el proceso para enviar solicitudes de extracción.

Flujo de Trabajo de Desarrollo

Haz un fork del repositorio
Crea tu rama de funciones (git checkout -b feature/AmazingFeature)
Confirma tus cambios (git commit -m 'Add some AmazingFeature')
Empuja a la rama (git push origin feature/AmazingFeature)
Abre una Solicitud de Extracción

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

Construido con la especificación del Protocolo de Contexto de Modelo
Impulsado por Roslyn para análisis de código C#
Inspirado en la arquitectura de almacenamiento LSM-tree
Extraído originalmente de CodeCartographerAI

📞 Soporte

Problemas: Problemas de GitHub
Discusiones: Discusiones de GitHub
Documentación: Wiki

ContextKeeper - Nunca pierdas el contexto de nuevo 🧠✨