MCP Memory Keeper

MCP Memory Keeper - Gestión de Contexto de Claude Code

Un servidor de Model Context Protocol (MCP) que proporciona gestión de contexto persistente para asistentes de codificación de Claude AI. ¡Nunca más pierdas contexto durante la compactación! Este servidor MCP ayuda a Claude Code a mantener el contexto entre sesiones, preservando tu historial de trabajo, decisiones y progreso.

🚀 Inicio Rápido

Comienza en menos de 30 segundos:

# Add memory-keeper to Claude
claude mcp add memory-keeper npx mcp-memory-keeper

# Start a new Claude session and use it!
# Try: Analyze the current repo and save your analysis in memory-keeper

¡Eso es todo! Memory Keeper ahora está disponible en todas tus sesiones de Claude. Tu contexto se almacena en ~/mcp-data/memory-keeper/ y persiste entre sesiones.

🚀 Ejemplo Práctico de Flujo de Trabajo con Memory Keeper

Comando Personalizado + CLAUDE.md = Gestión Automática de Contexto

CLAUDE.md (ejemplo condensado)

# Project Configuration

## Development Rules

- Always use memory-keeper to track progress
- Save architectural decisions and test results
- Create checkpoints before context limits

## Quality Standards

- All tests must pass before marking complete
- Document actual vs claimed results

Ejemplo de Comando Personalizado: /my-dev-workflow

# My Development Workflow

When working on the provided project:

- Use memory-keeper with channel: <project_name>
- Save progress at every major milestone
- Document all decisions with category: "decision"
- Track implementation status with category: "progress"
- Before claiming anything is complete, save test results

## Workflow Steps

1. Initialize session with project name as channel
2. Save findings during investigation
3. Create checkpoint before major changes
4. Document what actually works vs what should work

Ejemplo de Uso

User: /my-dev-workflow authentication-service

AI: Setting up workflow for authentication-service.
[Uses memory-keeper with channel "authentication-service"]

[... AI works, automatically saving context ...]

User: "Getting close to context limit. Create checkpoint and give me a key"

AI: "Checkpoint created: authentication-service-checkpoint-20250126-143026"

[Continue working until context reset or compact manually]

User: "Restore from key: authentication-service-checkpoint-20250126-143026"

AI: "Restored! Continuing OAuth implementation. We completed the token validation, working on refresh logic..."

El Patrón:

1. El comando personalizado incluye instrucciones para usar memory-keeper
2. La IA sigue esas instrucciones automáticamente
3. Cuando notes que la conversación se está volviendo larga, TÚ le pides a Claude que guarde un checkpoint (¡como guardar tu partida antes de una pelea contra un jefe!)
4. Cuando Claude se queda sin espacio y empieza de nuevo, TÚ le dices que restaure usando la clave del checkpoint

🎯 Característica Clave: ¡Memory Keeper es un tablero compartido! Puedes:

• Continuar en la misma sesión después de un reinicio
• Iniciar una sesión completamente nueva y restaurar
• Tener múltiples sesiones de Claude ejecutándose en paralelo, todas compartiendo la misma memoria
• Una sesión puede guardar contexto que otra sesión recupera

¡Esto permite flujos de trabajo potentes, como tener una sesión de Claude haciendo investigación mientras otra implementa código, ambas compartiendo descubrimientos a través de Memory Keeper!

¿Por qué MCP Memory Keeper?

Los usuarios de Claude Code a menudo enfrentan pérdida de contexto cuando la ventana de conversación se llena. Este servidor MCP resuelve ese problema proporcionando una capa de memoria persistente para Claude AI. Ya sea que estés trabajando en refactorizaciones complejas, cambios en múltiples archivos o sesiones largas de depuración, Memory Keeper asegura que tu asistente Claude recuerde contexto importante, decisiones y progreso.

Perfecto para:

• Sesiones largas de codificación con Claude Code
• Proyectos complejos que requieren preservación de contexto
• Equipos que usan Claude AI para desarrollo colaborativo
• Desarrolladores que quieren contexto persistente entre sesiones de Claude

Características

• 🔄 Guardar y restaurar contexto entre sesiones de Claude Code
• 📁 Caché de contenido de archivos con detección de cambios
• 🏷️ Organizar contexto con categorías y prioridades
• 📺 Canales - Organización persistente basada en temas (derivada automáticamente de la rama de git)
• 📸 Sistema de checkpoints para instantáneas completas de contexto
• 🤖 Asistente inteligente de compactación que nunca pierde información crítica
• 🔍 Búsqueda de texto completo en todo el contexto guardado
• 🕐 Filtrado mejorado - Consultas basadas en tiempo, patrones regex, paginación
• 📊 Seguimiento de cambios - Ve qué se ha añadido, modificado o eliminado desde cualquier punto
• 💾 Exportar/importar para copias de seguridad y compartir
• 🌿 Integración con git con correlación automática de contexto
• 📊 Resumen amigable para IA con conciencia de prioridades
• 🚀 Almacenamiento rápido basado en SQLite optimizado para Claude
• 🔁 Operaciones por lotes - Guardar, actualizar o eliminar múltiples elementos atómicamente
• 🔄 Reasignación de canales - Mover elementos entre canales según patrones
• 🔗 Relaciones de contexto - Vincular elementos relacionados con relaciones tipadas
• 👁️ Monitoreo en tiempo real - Observa cambios de contexto con filtros

Instalación

Recomendado: Instalación con NPX

claude mcp add memory-keeper npx mcp-memory-keeper

Este único comando:

• ✅ Siempre usa la última versión
• ✅ Maneja todas las dependencias automáticamente
• ✅ Funciona en macOS, Linux y Windows
• ✅ Sin compilación manual ni problemas de módulos nativos

Métodos de Instalación Alternativos

npm install -g mcp-memory-keeper
claude mcp add memory-keeper mcp-memory-keeper

# 1. Clone the repository
git clone https://github.com/mkreyman/mcp-memory-keeper.git
cd mcp-memory-keeper

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Add to Claude
claude mcp add memory-keeper /absolute/path/to/mcp-memory-keeper/bin/mcp-memory-keeper

Configuración

Variables de Entorno

Almacenamiento e Instalación

• DATA_DIR - Directorio para el almacenamiento de la base de datos (predeterminado: ~/mcp-data/memory-keeper/)
• MEMORY_KEEPER_INSTALL_DIR - Directorio de instalación (predeterminado: ~/.local/mcp-servers/memory-keeper/)
• MEMORY_KEEPER_AUTO_UPDATE - Establecer a 1 para habilitar actualizaciones automáticas

Configuración del Límite de Tokens

• MCP_MAX_TOKENS - Máximo de tokens permitidos en las respuestas (predeterminado: 25000, rango: 1000-100000)
  • Ajusta esto si tu cliente MCP tiene límites diferentes
• MCP_TOKEN_SAFETY_BUFFER - Porcentaje de buffer de seguridad (predeterminado: 0.8, rango: 0.1-1.0)
  • Usa solo esta fracción del máximo de tokens para prevenir desbordamientos
• MCP_MIN_ITEMS - Mínimo de elementos a devolver incluso si se exceden los límites (predeterminado: 1, rango: 1-100)
  • Asegura que se devuelvan al menos algunos resultados
• MCP_MAX_ITEMS - Máximo de elementos permitidos por respuesta (predeterminado: 100, rango: 10-1000)
  • Límite superior para conjuntos de resultados independientemente de los límites de tokens
• MCP_CHARS_PER_TOKEN - Relación de caracteres por token (predeterminado: 3.5, rango: 2.5-5.0) [Avanzado]
  • Ajusta la precisión de la estimación de tokens para diferentes tipos de contenido
  • Valores más bajos = más conservador (más seguro pero devuelve menos elementos)
  • Valores más altos = más agresivo (devuelve más elementos pero arriesga desbordamiento)

Ejemplo de configuración para límites de tokens más estrictos:

export MCP_MAX_TOKENS=20000        # Lower max tokens
export MCP_TOKEN_SAFETY_BUFFER=0.7  # More conservative buffer
export MCP_MAX_ITEMS=50             # Fewer items per response
export MCP_CHARS_PER_TOKEN=3.0      # More conservative estimation (optional)

Perfiles de Herramientas

Por defecto, las 38 herramientas están expuestas. Para reducir la sobrecarga de contexto en tu asistente de IA, puedes activar un perfil de herramientas que limite qué herramientas están disponibles.

Uso rápido:

# Essential tools only (8 tools)
TOOL_PROFILE=minimal npx mcp-memory-keeper

# Standard workflow set (22 tools)
TOOL_PROFILE=standard npx mcp-memory-keeper

# All tools (default)
TOOL_PROFILE=full npx mcp-memory-keeper

Perfiles integrados:

Perfiles personalizados mediante archivo de configuración:

Crea ~/.mcp-memory-keeper/config.json para definir o sobrescribir perfiles:

{
  "profiles": {
    "my_workflow": [
      "context_session_start",
      "context_save",
      "context_get",
      "context_search",
      "context_checkpoint",
      "context_restore_checkpoint",
      "context_diff",
      "context_timeline"
    ]
  }
}

Luego actívalo: TOOL_PROFILE=my_workflow npx mcp-memory-keeper

Los perfiles del archivo de configuración tienen prioridad sobre los integrados con el mismo nombre.

Precedencia de resolución de perfiles:

Variables de entorno:

Nota: La resolución de perfiles ocurre una vez al iniciar el servidor. Los cambios en la variable de entorno o en el archivo de configuración surten efecto en el próximo reinicio del servidor.

Configuración de Claude Code / Claude Desktop:

{
  "mcpServers": {
    "memory-keeper": {
      "command": "npx",
      "args": ["mcp-memory-keeper"],
      "env": {
        "TOOL_PROFILE": "minimal"
      }
    }
  }
}

Consulta examples/config.json para ver un ejemplo completo de archivo de configuración.

Claude Code (CLI)

Ámbitos de Configuración

Elige dónde guardar la configuración:

# Project-specific (default) - only for you in this project
claude mcp add memory-keeper npx mcp-memory-keeper

# Shared with team via .mcp.json
claude mcp add --scope project memory-keeper npx mcp-memory-keeper

# Available across all your projects
claude mcp add --scope user memory-keeper npx mcp-memory-keeper

Verificar Configuración

# List all configured servers
claude mcp list

# Get details for Memory Keeper
claude mcp get memory-keeper

Aplicación Claude Desktop

1. Abre la configuración de Claude Desktop
2. Navega a "Developer" → "Model Context Protocol"
3. Haz clic en "Add MCP Server"
4. Añade la siguiente configuración:

{
  "mcpServers": {
    "memory-keeper": {
      "command": "npx",
      "args": ["mcp-memory-keeper"]
    }
  }
}

¡Eso es todo! No se necesitan rutas: npx maneja todo automáticamente.

Verificar Instalación

Para Claude Code:

1. Reinicia Claude Code o inicia una nueva sesión
2. Las herramientas de Memory Keeper deberían estar disponibles automáticamente
3. Prueba con: mcp_memory_save({ key: "test", value: "Hello Memory Keeper!" })
4. Si no funciona, verifica el estado del servidor:

   claude mcp list  # Should show memory-keeper as "running"
   

Para Claude Desktop:

1. Reinicia Claude Desktop después de añadir la configuración
2. En una nueva conversación, las herramientas de Memory Keeper deberían estar disponibles
3. Prueba con el mismo comando de arriba

Solución de Problemas

Si Memory Keeper no funciona:

# Remove and re-add the server
claude mcp remove memory-keeper
claude mcp add memory-keeper npx mcp-memory-keeper

# Check logs for errors
# The server output will appear in Claude Code's output panel

Actualizar a la Última Versión

Con el método de instalación mediante npx, ¡obtienes automáticamente la última versión cada vez! No se necesitan actualizaciones manuales.

Si estás usando el método de instalación global:

# Update to latest version
npm update -g mcp-memory-keeper

# Start a new Claude session
# The updated features will be available immediately

Nota: No necesitas reconfigurar el servidor MCP en Claude después de actualizar. ¡Solo inicia una nueva sesión!

Uso

Gestión de Sesiones

// Start a new session
mcp_context_session_start({
  name: 'Feature Development',
  description: 'Working on user authentication',
});

// Start a session with project directory for git tracking
mcp_context_session_start({
  name: 'Feature Development',
  description: 'Working on user authentication',
  projectDir: '/path/to/your/project',
});

// Start a session with a default channel
mcp_context_session_start({
  name: 'Feature Development',
  description: 'Working on user authentication',
  projectDir: '/path/to/your/project',
  defaultChannel: 'auth-feature', // Will auto-derive from git branch if not specified
});

// Set project directory for current session
mcp_context_set_project_dir({
  projectDir: '/path/to/your/project',
});

// List recent sessions
mcp_context_session_list({ limit: 5 });

// Continue from a previous session
mcp_context_session_start({
  name: 'Feature Dev Continued',
  continueFrom: 'previous-session-id',
});

Trabajar con Canales (NUEVO en v0.10.0)

Los canales proporcionan organización persistente basada en temas que sobrevive a fallos y reinicios de sesión:

// Channels are auto-derived from git branch (if projectDir is set)
// Branch "feature/auth-system" becomes channel "feature-auth-system" (20 chars max)

// Save to a specific channel
mcp_context_save({
  key: 'auth_design',
  value: 'Using JWT with refresh tokens',
  category: 'decision',
  priority: 'high',
  channel: 'auth-feature', // Explicitly set channel
});

// Get items from a specific channel
mcp_context_get({ channel: 'auth-feature' });

// Get items across all channels (default behavior)
mcp_context_get({ category: 'task' });

// Channels persist across sessions - perfect for:
// - Multi-branch development
// - Feature-specific context
// - Team collaboration on different topics

Almacenamiento Mejorado de Contexto

// Save with categories and priorities
mcp_context_save({
  key: 'current_task',
  value: 'Implement OAuth integration',
  category: 'task',
  priority: 'high',
});

// Save decisions
mcp_context_save({
  key: 'auth_strategy',
  value: 'Using JWT tokens with 24h expiry',
  category: 'decision',
  priority: 'high',
});

// Save progress notes
mcp_context_save({
  key: 'progress_auth',
  value: 'Completed user model, working on token generation',
  category: 'progress',
  priority: 'normal',
});

// Retrieve by category
mcp_context_get({ category: 'task' });

// Retrieve specific item
mcp_context_get({ key: 'current_task' });

// Get context from specific session
mcp_context_get({
  sessionId: 'session-id-here',
  category: 'decision',
});

// Enhanced filtering (NEW in v0.10.0)
mcp_context_get({
  category: 'task',
  priorities: ['high', 'normal'],
  includeMetadata: true, // Get timestamps, size info
  sort: 'created_desc', // created_asc/desc, updated_asc/desc, priority
  limit: 10, // Pagination
  offset: 0,
});

// Time-based queries (NEW in v0.10.0)
mcp_context_get({
  createdAfter: '2025-01-20T00:00:00Z',
  createdBefore: '2025-01-26T23:59:59Z',
  includeMetadata: true,
});

// Pattern matching (NEW in v0.10.0)
mcp_context_get({
  keyPattern: 'auth_.*', // Regex to match keys
  category: 'decision',
});

Caché de Archivos

// Cache file content for change detection
mcp_context_cache_file({
  filePath: '/src/auth/user.model.ts',
  content: fileContent,
});

// Check if file has changed
mcp_context_file_changed({
  filePath: '/src/auth/user.model.ts',
  currentContent: newFileContent,
});

// Get current session status
mcp_context_status();

Ejemplo Completo de Flujo de Trabajo

// 1. Start a new session
mcp_context_session_start({
  name: 'Settings Refactor',
  description: 'Refactoring settings module for better performance',
});

// 2. Save high-priority task
mcp_context_save({
  key: 'main_task',
  value: 'Refactor Settings.Context to use behaviors',
  category: 'task',
  priority: 'high',
});

// 3. Cache important files
mcp_context_cache_file({
  filePath: 'lib/settings/context.ex',
  content: originalFileContent,
});

// 4. Save decisions as you work
mcp_context_save({
  key: 'architecture_decision',
  value: 'Split settings into read/write modules',
  category: 'decision',
  priority: 'high',
});

// 5. Track progress
mcp_context_save({
  key: 'progress_1',
  value: 'Completed behavior definition, 5 modules remaining',
  category: 'progress',
  priority: 'normal',
});

// 6. Before context window fills up
mcp_context_status(); // Check what's saved

// 7. After Claude Code restart
mcp_context_get({ category: 'task', priority: 'high' }); // Get high priority tasks
mcp_context_get({ key: 'architecture_decision' }); // Get specific decisions
mcp_context_file_changed({ filePath: 'lib/settings/context.ex' }); // Check for changes

Checkpoints (Fase 2)

Crea instantáneas con nombre de todo tu contexto que se pueden restaurar más tarde:

// Create a checkpoint before major changes
mcp_context_checkpoint({
  name: 'before-refactor',
  description: 'State before major settings refactor',
  includeFiles: true, // Include cached files
  includeGitStatus: true, // Capture git status
});

// Continue working...
// If something goes wrong, restore from checkpoint
mcp_context_restore_checkpoint({
  name: 'before-refactor',
  restoreFiles: true, // Restore cached files too
});

// Or restore the latest checkpoint
mcp_context_restore_checkpoint({});

Resumen de Contexto (Fase 2)

Obtén resúmenes amigables para IA de tu contexto guardado:

// Get a summary of all context
mcp_context_summarize();

// Get summary of specific categories
mcp_context_summarize({
  categories: ['task', 'decision'],
  maxLength: 2000,
});

// Summarize a specific session
mcp_context_summarize({
  sessionId: 'session-id-here',
  categories: ['progress'],
});

Ejemplo de salida de resumen:

# Context Summary

## High Priority Items

- **main_task**: Refactor Settings.Context to use behaviors
- **critical_bug**: Fix memory leak in subscription handler

## Task

- implement_auth: Add OAuth2 authentication flow
- update_tests: Update test suite for new API

## Decision

- architecture_decision: Split settings into read/write modules
- db_choice: Use PostgreSQL for better JSON support

Operaciones por Lotes

Realiza múltiples operaciones atómicamente:

// Save multiple items at once
mcp_context_batch_save({
  items: [
    { key: 'config_api_url', value: 'https://api.example.com', category: 'note' },
    { key: 'config_timeout', value: '30000', category: 'note' },
    { key: 'config_retries', value: '3', category: 'note' },
  ],
});

// Update multiple items
mcp_context_batch_update({
  updates: [
    { key: 'task_1', priority: 'high' },
    { key: 'task_2', priority: 'high' },
    { key: 'task_3', value: 'Updated task description' },
  ],
});

// Delete by pattern
mcp_context_batch_delete({
  keyPattern: 'temp_*',
  dryRun: true, // Preview first
});

Gestión de Canales

Reorganiza elementos de contexto entre canales:

// Move items to a new channel
mcp_context_reassign_channel({
  keyPattern: 'auth_*',
  toChannel: 'feature-authentication',
});

// Move from one channel to another
mcp_context_reassign_channel({
  fromChannel: 'sprint-14',
  toChannel: 'sprint-15',
  category: 'task',
  priorities: ['high'],
});

Relaciones de Contexto

Construye un grafo de elementos relacionados:

// Link related items
mcp_context_link({
  sourceKey: 'epic_user_management',
  targetKey: 'task_create_user_api',
  relationship: 'contains',
});

// Find related items
mcp_context_get_related({
  key: 'epic_user_management',
  relationship: 'contains',
  depth: 2,
});

Monitoreo en Tiempo Real

Observa cambios de contexto:

// Create a watcher
const watcher = await mcp_context_watch({
  action: 'create',
  filters: {
    categories: ['task'],
    priorities: ['high'],
  },
});

// Poll for changes
const changes = await mcp_context_watch({
  action: 'poll',
  watcherId: watcher.watcherId,
});

Compactación Inteligente (Fase 3)

Nunca pierdas contexto crítico cuando la ventana de Claude se llene:

// Before context window fills
mcp_context_prepare_compaction();

// This automatically:
// - Creates a checkpoint
// - Identifies high-priority items
// - Captures unfinished tasks
// - Saves all decisions
// - Generates a summary
// - Prepares restoration instructions

Integración con Git (Fase 3)

Rastrea cambios de git en tu directorio de proyecto y guarda contexto con los commits:

// First, set your project directory (if not done during session start)
mcp_context_set_project_dir({
  projectDir: '/path/to/your/project',
});

// Commit with auto-save
mcp_context_git_commit({
  message: 'feat: Add user authentication',
  autoSave: true, // Creates checkpoint with commit
});

// Context is automatically linked to the commit
// Note: If no project directory is set, you'll see a helpful message
// explaining how to enable git tracking for your project

Búsqueda de Contexto (Fase 3)

Encuentra cualquier cosa en tu contexto guardado:

// Search in keys and values
mcp_context_search({ query: 'authentication' });

// Search only in keys
mcp_context_search({
  query: 'config',
  searchIn: ['key'],
});

// Search in specific session
mcp_context_search({
  query: 'bug',
  sessionId: 'session-id',
});

Exportar/Importar (Fase 3)

Comparte contexto o haz una copia de seguridad de tu trabajo:

// Export current session — writes into the exports directory
// (<DATA_DIR>/exports/, overridable via MEMORY_KEEPER_EXPORT_DIR)
mcp_context_export(); // Creates memory-keeper-export-xxx.json

// Export specific session
mcp_context_export({
  sessionId: 'session-id',
  format: 'json',
});

// Import from a file inside the exports directory.
// A bare filename resolves against that directory; the absolute path
// returned by context_export also works.
mcp_context_import({
  filePath: 'memory-keeper-export-xxx.json',
});

// Merge into current session
mcp_context_import({
  filePath: 'backup.json',
  merge: true,
});

Nota de seguridad: Por seguridad, context_import solo lee archivos dentro del directorio de exportaciones propiedad del servidor (<DATA_DIR>/exports/, o MEMORY_KEEPER_EXPORT_DIR si está establecido). Las rutas absolutas fuera de ese directorio y el recorrido ../ se rechazan, por lo que la herramienta no puede ser dirigida a archivos arbitrarios en el disco. Coloca cualquier archivo que quieras importar en ese directorio primero. Apunta MEMORY_KEEPER_EXPORT_DIR a un directorio dedicado — no a una carpeta de inicio o a un árbol que contenga secretos — ya que cualquier archivo JSON dentro de él se vuelve importable. (Antes de este cambio, las exportaciones se escribían en el directorio temporal del sistema operativo; las exportaciones existentes allí deben moverse al directorio de exportaciones para poder reimportarse.)

Grafo de Conocimiento (Fase 4)

Extrae automáticamente entidades y relaciones de tu contexto:

// Analyze context to build knowledge graph
mcp_context_analyze();

// Or analyze specific categories
mcp_context_analyze({
  categories: ['task', 'decision'],
});

// Find related entities
mcp_context_find_related({
  key: 'AuthService',
  maxDepth: 2,
});

// Generate visualization data
mcp_context_visualize({
  type: 'graph',
});

// Timeline view
mcp_context_visualize({
  type: 'timeline',
});

// Category/priority heatmap
mcp_context_visualize({
  type: 'heatmap',
});

Búsqueda Semántica (Fase 4.2)

Encuentra contexto usando consultas en lenguaje natural:

// Search with natural language
mcp_context_semantic_search({
  query: 'how are we handling user authentication?',
  topK: 5,
});

// Find the most relevant security decisions
mcp_context_semantic_search({
  query: 'security concerns and decisions',
  minSimilarity: 0.5,
});

// Search with specific similarity threshold
mcp_context_semantic_search({
  query: 'database performance optimization',
  topK: 10,
  minSimilarity: 0.3,
});

Sistema Multi-Agente (Fase 4.3)

Delega tareas complejas de análisis a agentes especializados:

// Analyze patterns in your context
mcp_context_delegate({
  taskType: 'analyze',
  input: {
    analysisType: 'patterns',
    categories: ['task', 'decision'],
  },
});

// Get comprehensive analysis
mcp_context_delegate({
  taskType: 'analyze',
  input: {
    analysisType: 'comprehensive',
  },
});

// Analyze relationships between entities
mcp_context_delegate({
  taskType: 'analyze',
  input: {
    analysisType: 'relationships',
    maxDepth: 3,
  },
});

// Create intelligent summaries
mcp_context_delegate({
  taskType: 'synthesize',
  input: {
    synthesisType: 'summary',
    maxLength: 1000,
  },
});

// Get actionable recommendations
mcp_context_delegate({
  taskType: 'synthesize',
  input: {
    synthesisType: 'recommendations',
    analysisResults: {}, // Can pass previous analysis results
  },
});

// Chain multiple agent tasks
mcp_context_delegate({
  chain: true,
  taskType: ['analyze', 'synthesize'],
  input: [{ analysisType: 'comprehensive' }, { synthesisType: 'recommendations' }],
});

Tipos de Agentes:

• Agente Analizador: Detecta patrones, analiza relaciones, rastrea tendencias
• Agente Sintetizador: Crea resúmenes, fusiona conocimientos, genera recomendaciones

Ramificación y Fusión de Sesiones (Fase 4.4)

Explora alternativas sin perder tu trabajo original:

// Create a branch to try something new
mcp_context_branch_session({
  branchName: 'experimental-refactor',
  copyDepth: 'shallow', // Only copy high-priority items
});

// Or create a full copy
mcp_context_branch_session({
  branchName: 'feature-complete-copy',
  copyDepth: 'deep', // Copy everything
});

// Later, merge changes back
mcp_context_merge_sessions({
  sourceSessionId: 'branch-session-id',
  conflictResolution: 'keep_newest', // or "keep_current", "keep_source"
});

Entradas de Diario (Fase 4.4)

Registra tus pensamientos y progreso con entradas de diario con marca de tiempo:

// Add a journal entry
mcp_context_journal_entry({
  entry: 'Completed the authentication module. Tests are passing!',
  tags: ['milestone', 'authentication'],
  mood: 'accomplished',
});

// Entries are included in timeline views
mcp_context_timeline({
  groupBy: 'day',
});

Línea de Tiempo y Seguimiento de Actividad (Fase 4.4)

Visualiza tus patrones de trabajo a lo largo del tiempo:

// Get activity timeline
mcp_context_timeline({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  groupBy: 'day', // or "hour", "week"
});

// Enhanced timeline (NEW in v0.10.0)
mcp_context_timeline({
  groupBy: 'hour',
  includeItems: true, // Show actual items, not just counts
  categories: ['task', 'progress'], // Filter by categories
  relativeTime: true, // Show "2 hours ago" format
  itemsPerPeriod: 10, // Limit items shown per time period
});

// Shows:
// - Context items created per day/hour
// - Category distribution over time
// - Journal entries with moods and tags
// - Actual item details when includeItems: true

Compresión Progresiva (Fase 4.4)

Ahorra espacio comprimiendo inteligentemente el contexto antiguo:

// Compress items older than 30 days
mcp_context_compress({
  olderThan: '2024-01-01',
  preserveCategories: ['decision', 'critical'], // Keep these
  targetSize: 1000, // Target size in KB (optional)
});

// Compression summary shows:
// - Items compressed
// - Space saved
// - Compression ratio
// - Categories affected

Integración entre herramientas (Fase 4.4)

Seguimiento de eventos de otras herramientas MCP:

// Record events from other tools
mcp_context_integrate_tool({
  toolName: 'code-analyzer',
  eventType: 'security-scan-complete',
  data: {
    vulnerabilities: 0,
    filesScanned: 150,
    important: true, // Creates high-priority context item
  },
});

Documentación

• Ejemplos de inicio rápido - Escenarios y flujos de trabajo del mundo real
• Referencia de API - Documentación completa de herramientas con todos los parámetros y ejemplos
• Libro de recetas - Patrones comunes y mejores prácticas para el desarrollo diario
• Guía de solución de problemas - Problemas comunes y soluciones
• Resumen de arquitectura - Diseño del sistema y detalles técnicos
• Guía de contribución - Cómo contribuir al proyecto
• Registro de cambios - Historial de versiones y notas de lanzamiento

Desarrollo

Ejecución en modo de desarrollo

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run with auto-reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

Estructura del proyecto

mcp-memory-keeper/
├── src/
│   ├── index.ts           # Main MCP server implementation
│   ├── utils/             # Utility modules
│   │   ├── database.ts    # Database management
│   │   ├── validation.ts  # Input validation
│   │   ├── git.ts         # Git operations
│   │   ├── knowledge-graph.ts # Knowledge graph management
│   │   ├── vector-store.ts    # Vector embeddings
│   │   └── agents.ts      # Multi-agent system
│   └── __tests__/         # Test files
├── dist/                  # Compiled JavaScript (generated)
├── context.db             # SQLite database (auto-created)
├── EXAMPLES.md            # Quick start examples
├── TROUBLESHOOTING.md     # Common issues and solutions
├── package.json           # Project configuration
├── tsconfig.json          # TypeScript configuration
├── jest.config.js         # Test configuration
└── README.md              # This file

Pruebas

El proyecto incluye una cobertura de pruebas exhaustiva:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

# Run specific test file
npm test -- summarization.test.ts

Categorías de pruebas:

• Pruebas unitarias: Validación de entrada, operaciones de base de datos, integración con git
• Pruebas de integración: Flujos de trabajo completos de herramientas, escenarios de error, casos límite
• Cobertura: Cobertura del 97%+ en módulos críticos

Estado de las funciones

Funciones actuales (v0.10.0)

• ✅ Gestión de sesiones: Crear, listar y continuar sesiones con soporte de ramificación
• ✅ Canales: Organización persistente basada en temas (derivada automáticamente de la rama de git)
• ✅ Almacenamiento de contexto: Guardar/recuperar contexto con categorías (tarea, decisión, progreso, nota) y prioridades
• ✅ Filtrado mejorado: Consultas basadas en tiempo, patrones regex, ordenación, paginación
• ✅ Caché de archivos: Seguimiento de cambios de archivos con hash SHA-256
• ✅ Puntos de control: Crear y restaurar instantáneas completas de contexto
• ✅ Compactación inteligente: Nunca pierdas contexto crítico al alcanzar límites
• ✅ Integración con Git: Guardado automático de contexto en commits con seguimiento de ramas
• ✅ Búsqueda: Búsqueda de texto completo en todo el contexto guardado
• ✅ Exportar/Importar: Copia de seguridad y uso compartido de contexto como JSON
• ✅ Almacenamiento SQLite: Almacenamiento de datos persistente y confiable con modo WAL
• ✅ Grafo de conocimiento: Extracción automática de entidades y relaciones del contexto
• ✅ Visualización: Generar datos de grafos, líneas de tiempo y mapas de calor para exploración de contexto
• ✅ Búsqueda semántica: Búsqueda en lenguaje natural mediante incrustaciones vectoriales ligeras
• ✅ Sistema multiagente: Análisis inteligente con agentes especializados de análisis y síntesis
• ✅ Ramificación de sesiones: Crear ramas para explorar alternativas sin perder el contexto original
• ✅ Fusión de sesiones: Fusionar ramas de nuevo con opciones de resolución de conflictos
• ✅ Entradas de diario: Entradas con marca de tiempo, etiquetas y seguimiento de estado de ánimo
• ✅ Línea de tiempo mejorada: Patrones de actividad con detalles de elementos y tiempo relativo
• ✅ Compresión progresiva: Comprimir inteligentemente el contexto antiguo para ahorrar espacio
• ✅ Integración entre herramientas: Seguimiento de eventos de otras herramientas MCP

Hoja de ruta

Fase 4: Funciones avanzadas (en desarrollo)

• 🚧 Grafo de conocimiento: Seguimiento de entidades y relaciones para la comprensión del código
• 🚧 Búsqueda vectorial: Búsqueda semántica mediante lenguaje natural
• 📋 Procesamiento multiagente: Análisis y síntesis inteligentes
• 📋 Contexto sensible al tiempo: Vistas de línea de tiempo y entradas de diario

Fase 5: Documentación y pulido

• ✅ Ejemplos: Escenarios completos de inicio rápido
• ✅ Solución de problemas: Problemas comunes y soluciones
• 🚧 Recetas: Patrones y flujos de trabajo comunes
• 📋 Tutoriales en video: Guías visuales para funciones clave

Mejoras futuras

• Interfaz web para explorar el historial de contexto
• Funciones de colaboración multiusuario/equipo
• Sincronización y uso compartido en la nube
• Integración con otros asistentes de IA
• Análisis avanzados y perspectivas
• Plantillas de contexto personalizadas
• Políticas de retención automáticas

Actualización

Cambio de ruta de la base de datos (v0.12.x+)

Antes de esta versión, el servidor resolvía context.db en relación con el directorio de trabajo actual del proceso. La base de datos ahora se encuentra en una ruta absoluta:

• Predeterminado: ~/mcp-data/memory-keeper/context.db
• Personalizado: establece DATA_DIR=/your/path — el servidor usará $DATA_DIR/context.db

Si tienes datos existentes en un context.db en tu antiguo directorio de trabajo, muévelos a la nueva ubicación antes de reiniciar el servidor:

mkdir -p ~/mcp-data/memory-keeper
cp /path/to/old/context.db ~/mcp-data/memory-keeper/context.db

Si DATA_DIR está configurado, usa esa ruta como destino en lugar de ~/mcp-data/memory-keeper/.

El servidor imprimirá una advertencia en stderr si detecta un context.db en el directorio actual que difiere del directorio de datos configurado, incluyendo el comando exacto cp para ejecutar.

Cambio en el comando de instalación desde el código fuente

Si registraste memory-keeper usando node dist/index.js directamente, actualiza tu configuración de MCP para usar el envoltorio bin en su lugar:

# remove the old entry
claude mcp remove memory-keeper

# add the updated entry
claude mcp add memory-keeper /absolute/path/to/mcp-memory-keeper/bin/mcp-memory-keeper

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una solicitud de extracción (Pull Request).

1. Haz un fork del repositorio
2. Crea tu rama de características (git checkout -b feature/AmazingFeature)
3. Realiza un commit de tus cambios (git commit -m 'Add some AmazingFeature')
4. Sube los cambios a la rama (git push origin feature/AmazingFeature)
5. Abre una solicitud de extracción (Pull Request)

Licencia

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

Autor

Mark Kreyman

Agradecimientos

• Construido para la comunidad de Claude Code
• Inspirado por la necesidad de una mejor gestión del contexto en sesiones de codificación con IA
• Gracias a Anthropic por el protocolo MCP

Soporte

Si encuentras algún problema o tienes preguntas:

• Abre un problema en GitHub
• Consulta la documentación de MCP
• Únete a las discusiones de la comunidad de Claude Code

Palabras clave

Claude Code context management, MCP server, Claude AI memory, persistent context, Model Context Protocol, Claude assistant memory, AI coding context, Claude Code MCP, context preservation, Claude AI tools