MCP Memory Keeper

MCP Memory Keeper - Gerenciamento de Contexto do Claude Code

Um servidor Model Context Protocol (MCP) que fornece gerenciamento persistente de contexto para assistentes de codificação Claude AI. Nunca mais perca contexto durante a compactação! Este servidor MCP ajuda o Claude Code a manter o contexto entre sessões, preservando seu histórico de trabalho, decisões e progresso.

🚀 Início Rápido

Comece em 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

Pronto! O Memory Keeper agora está disponível em todas as suas sessões do Claude. Seu contexto é armazenado em ~/mcp-data/memory-keeper/ e persiste entre sessões.

🚀 Exemplo Prático de Fluxo de Trabalho com Memory Keeper

Comando Personalizado + CLAUDE.md = Gerenciamento Automático de Contexto

CLAUDE.md (exemplo 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

Exemplo 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

Exemplo 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..."

O Padrão:

1. O comando personalizado inclui instruções para usar o memory-keeper
2. A IA segue essas instruções automaticamente
3. Quando você notar que a conversa está ficando longa, VOCÊ pede ao Claude para salvar um checkpoint (como salvar seu jogo antes de uma luta contra o chefe!)
4. Quando o Claude ficar sem espaço e começar do zero, VOCÊ diz a ele para restaurar usando a chave do checkpoint

🎯 Recurso Principal: O Memory Keeper é um quadro compartilhado! Você pode:

• Continuar na mesma sessão após o reset
• Iniciar uma sessão completamente nova e restaurar
• Ter várias sessões do Claude rodando em paralelo, todas compartilhando a mesma memória
• Uma sessão pode salvar contexto que outra sessão recupera

Isso permite fluxos de trabalho poderosos, como ter uma sessão do Claude fazendo pesquisa enquanto outra implementa código, ambas compartilhando descobertas através do Memory Keeper!

Por que o MCP Memory Keeper?

Usuários do Claude Code frequentemente enfrentam perda de contexto quando a janela de conversa se enche. Este servidor MCP resolve esse problema fornecendo uma camada de memória persistente para o Claude AI. Esteja você trabalhando em refatorações complexas, alterações em vários arquivos ou longas sessões de depuração, o Memory Keeper garante que seu assistente Claude se lembre de contexto importante, decisões e progresso.

Perfeito para:

• Sessões longas de codificação com Claude Code
• Projetos complexos que exigem preservação de contexto
• Equipes usando Claude AI para desenvolvimento colaborativo
• Desenvolvedores que querem contexto persistente entre sessões do Claude

Recursos

• 🔄 Salvar e restaurar contexto entre sessões do Claude Code
• 📁 Cache de conteúdo de arquivos com detecção de alterações
• 🏷️ Organize contexto com categorias e prioridades
• 📺 Canais - Organização persistente baseada em tópicos (derivada automaticamente do branch git)
• 📸 Sistema de checkpoint para snapshots completos de contexto
• 🤖 Assistente inteligente de compactação que nunca perde informações críticas
• 🔍 Busca de texto completo em todo o contexto salvo
• 🕐 Filtragem aprimorada - Consultas baseadas em tempo, padrões regex, paginação
• 📊 Rastreamento de alterações - Veja o que foi adicionado, modificado ou excluído desde qualquer ponto
• 💾 Exportação/importação para backup e compartilhamento
• 🌿 Integração com Git com correlação automática de contexto
• 📊 Resumo amigável para IA com consciência de prioridade
• 🚀 Armazenamento rápido baseado em SQLite otimizado para Claude
• 🔁 Operações em lote - Salvar, atualizar ou excluir vários itens atomicamente
• 🔄 Reatribuição de canais - Mover itens entre canais com base em padrões
• 🔗 Relacionamentos de contexto - Vincular itens relacionados com relacionamentos tipados
• 👁️ Monitoramento em tempo real - Observe alterações de contexto com filtros

Instalação

Recomendado: Instalação via NPX

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

Este único comando:

• ✅ Sempre usa a versão mais recente
• ✅ Gerencia todas as dependências automaticamente
• ✅ Funciona em macOS, Linux e Windows
• ✅ Sem compilação manual ou problemas com módulos nativos

Métodos Alternativos de Instalação

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

Configuração

Variáveis de Ambiente

Armazenamento e Instalação

• DATA_DIR - Diretório para armazenamento do banco de dados (padrão: ~/mcp-data/memory-keeper/)
• MEMORY_KEEPER_INSTALL_DIR - Diretório de instalação (padrão: ~/.local/mcp-servers/memory-keeper/)
• MEMORY_KEEPER_AUTO_UPDATE - Defina como 1 para habilitar atualizações automáticas

Configuração de Limite de Tokens

• MCP_MAX_TOKENS - Máximo de tokens permitidos nas respostas (padrão: 25000, intervalo: 1000-100000)
  • Ajuste isso se seu cliente MCP tiver limites diferentes
• MCP_TOKEN_SAFETY_BUFFER - Porcentagem de buffer de segurança (padrão: 0.8, intervalo: 0.1-1.0)
  • Usa apenas essa fração do máximo de tokens para evitar estouros
• MCP_MIN_ITEMS - Mínimo de itens a retornar mesmo se exceder os limites (padrão: 1, intervalo: 1-100)
  • Garante que pelo menos alguns resultados sejam retornados
• MCP_MAX_ITEMS - Máximo de itens permitidos por resposta (padrão: 100, intervalo: 10-1000)
  • Limite superior para conjuntos de resultados, independentemente dos limites de tokens
• MCP_CHARS_PER_TOKEN - Proporção de caracteres por token (padrão: 3.5, intervalo: 2.5-5.0) [Avançado]
  • Ajusta a precisão da estimativa de tokens para diferentes tipos de conteúdo
  • Valores mais baixos = mais conservador (mais seguro, mas retorna menos itens)
  • Valores mais altos = mais agressivo (retorna mais itens, mas arrisca estouro)

Exemplo de configuração para limites de tokens mais rígidos:

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)

Perfis de Ferramentas

Por padrão, todas as 38 ferramentas são expostas. Para reduzir a sobrecarga de contexto no seu assistente de IA, você pode ativar um perfil de ferramentas que limita quais ferramentas estão disponíveis.

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

Perfis integrados:

Perfis personalizados via arquivo de configuração:

Crie ~/.mcp-memory-keeper/config.json para definir ou substituir perfis:

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

Em seguida, ative-o: TOOL_PROFILE=my_workflow npx mcp-memory-keeper

Perfis de arquivo de configuração têm precedência sobre os padrões integrados com o mesmo nome.

Precedência de resolução de perfil:

Variáveis de ambiente:

Nota: A resolução do perfil ocorre uma vez na inicialização do servidor. Alterações na variável de ambiente ou no arquivo de configuração entram em vigor no próximo reinício do servidor.

Configuração do Claude Code / Claude Desktop:

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

Consulte examples/config.json para um exemplo completo de arquivo de configuração.

Claude Code (CLI)

Escopos de Configuração

Escolha onde salvar a configuração:

# 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 Configuração

# List all configured servers
claude mcp list

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

Aplicativo Claude Desktop

1. Abra as configurações do Claude Desktop
2. Navegue até "Developer" → "Model Context Protocol"
3. Clique em "Add MCP Server"
4. Adicione a seguinte configuração:

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

Pronto! Nenhum caminho necessário - o npx lida com tudo automaticamente.

Verificar Instalação

Para Claude Code:

1. Reinicie o Claude Code ou inicie uma nova sessão
2. As ferramentas do Memory Keeper devem estar disponíveis automaticamente
3. Teste com: mcp_memory_save({ key: "test", value: "Hello Memory Keeper!" })
4. Se não estiver funcionando, verifique o status do servidor:

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

Para Claude Desktop:

1. Reinicie o Claude Desktop após adicionar a configuração
2. Em uma nova conversa, as ferramentas do Memory Keeper devem estar disponíveis
3. Teste com o mesmo comando acima

Solução de Problemas

Se o Memory Keeper não estiver funcionando:

# 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

Atualizando para a Versão Mais Recente

Com o método de instalação via npx, você obtém automaticamente a versão mais recente sempre! Nenhuma atualização manual é necessária.

Se você estiver usando o método de instalação global:

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

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

Nota: Você não precisa reconfigurar o servidor MCP no Claude após a atualização. Basta iniciar uma nova sessão!

Uso

Gerenciamento de Sessão

// 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',
});

Trabalhando com Canais (NOVO na v0.10.0)

Os canais fornecem organização persistente baseada em tópicos que sobrevive a falhas e reinícios de sessão:

// 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

Armazenamento Aprimorado 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',
});

Cache de Arquivos

// 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();

Exemplo Completo de Fluxo de Trabalho

// 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)

Crie snapshots nomeados de todo o seu contexto que podem ser restaurados posteriormente:

// 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({});

Resumo de Contexto (Fase 2)

Obtenha resumos amigáveis para IA do seu contexto salvo:

// 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'],
});

Exemplo de saída de resumo:

# 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

Operações em Lote

Execute múltiplas operações atomicamente:

// 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
});

Gerenciamento de Canais

Reorganize itens de contexto entre canais:

// 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'],
});

Relacionamentos de Contexto

Construa um grafo de itens 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,
});

Monitoramento em Tempo Real

Observe alterações 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,
});

Compactação Inteligente (Fase 3)

Nunca perca contexto crítico quando a janela do Claude se encher:

// 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

Integração com Git (Fase 3)

Rastreie alterações git no diretório do seu projeto e salve contexto com 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

Busca de Contexto (Fase 3)

Encontre qualquer coisa no seu contexto salvo:

// 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',
});

Exportação/Importação (Fase 3)

Compartilhe contexto ou faça backup do seu trabalho:

// 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 segurança: Por segurança, context_import só lê arquivos dentro do diretório de exportações de propriedade do servidor (<DATA_DIR>/exports/, ou MEMORY_KEEPER_EXPORT_DIR se definido). Caminhos absolutos fora desse diretório e travessia de ../ são rejeitados, então a ferramenta não pode ser direcionada para arquivos arbitrários no disco. Coloque qualquer arquivo que queira importar nesse diretório primeiro. Aponte MEMORY_KEEPER_EXPORT_DIR para um diretório dedicado — não para uma pasta pessoal ou uma árvore contendo segredos — já que qualquer arquivo JSON dentro dele se torna importável. (Antes desta alteração, as exportações eram gravadas no diretório temporário do SO; as exportações existentes lá devem ser movidas para o diretório de exportações para serem reimportadas.)

Grafo de Conhecimento (Fase 4)

Extraia automaticamente entidades e relacionamentos do seu 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',
});

Busca Semântica (Fase 4.2)

Encontre contexto usando consultas em linguagem 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)

Delegue tarefas complexas de análise 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 Analisador: Detecta padrões, analisa relacionamentos, rastreia tendências
• Agente Sintetizador: Cria resumos, combina insights, gera recomendações

Ramificação e Mesclagem de Sessão (Fase 4.4)

Explore alternativas sem perder seu trabalho 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 Diário (Fase 4.4)

Acompanhe seus pensamentos e progresso com entradas de diário com carimbo de data/hora:

// 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',
});

Linha do Tempo e Rastreamento de Atividade (Fase 4.4)

Visualize seus padrões de trabalho ao longo do tempo:

// 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

Compressão Progressiva (Fase 4.4)

Economize espaço comprimindo inteligentemente o contexto antigo:

// 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

Integração entre Ferramentas (Fase 4.4)

Rastreie eventos de outras ferramentas 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
  },
});

Documentação

• Exemplos de Início Rápido - Cenários e fluxos de trabalho do mundo real
• Referência da API - Documentação completa da ferramenta com todos os parâmetros e exemplos
• Livro de Receitas - Padrões comuns e melhores práticas para o desenvolvimento diário
• Guia de Solução de Problemas - Problemas comuns e soluções
• Visão Geral da Arquitetura - Design do sistema e detalhes técnicos
• Guia de Contribuição - Como contribuir para o projeto
• Changelog - Histórico de versões e notas de lançamento

Desenvolvimento

Executando em Modo de Desenvolvimento

# 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

Estrutura do Projeto

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

Testes

O projeto inclui cobertura abrangente de testes:

# 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

Categorias de teste:

• Testes Unitários: Validação de entrada, operações de banco de dados, integração com git
• Testes de Integração: Fluxos de trabalho completos da ferramenta, cenários de erro, casos extremos
• Cobertura: 97%+ de cobertura nos módulos críticos

Status dos Recursos

Recursos Atuais (v0.10.0)

• ✅ Gerenciamento de Sessões: Criar, listar e continuar sessões com suporte a ramificações
• ✅ Canais: Organização persistente baseada em tópicos (derivada automaticamente do branch git)
• ✅ Armazenamento de Contexto: Salvar/recuperar contexto com categorias (tarefa, decisão, progresso, nota) e prioridades
• ✅ Filtragem Aprimorada: Consultas baseadas em tempo, padrões regex, ordenação, paginação
• ✅ Cache de Arquivos: Rastrear alterações de arquivos com hash SHA-256
• ✅ Checkpoints: Criar e restaurar snapshots completos de contexto
• ✅ Compactação Inteligente: Nunca perca contexto crítico ao atingir limites
• ✅ Integração com Git: Salvar contexto automaticamente em commits com rastreamento de branch
• ✅ Busca: Busca de texto completo em todo o contexto salvo
• ✅ Exportar/Importar: Backup e compartilhamento de contexto como JSON
• ✅ Armazenamento SQLite: Armazenamento de dados persistente e confiável com modo WAL
• ✅ Grafo de Conhecimento: Extração automática de entidades e relacionamentos do contexto
• ✅ Visualização: Gerar dados de grafo, linha do tempo e mapa de calor para exploração de contexto
• ✅ Busca Semântica: Busca em linguagem natural usando embeddings vetoriais leves
• ✅ Sistema Multi-Agente: Análise inteligente com agentes especializados de análise e síntese
• ✅ Ramificação de Sessões: Criar ramificações para explorar alternativas sem perder o contexto original
• ✅ Mesclagem de Sessões: Mesclar ramificações de volta com opções de resolução de conflitos
• ✅ Entradas de Diário: Entradas com carimbo de tempo, tags e rastreamento de humor
• ✅ Linha do Tempo Aprimorada: Padrões de atividade com detalhes de itens e tempo relativo
• ✅ Compressão Progressiva: Comprimir inteligentemente contexto antigo para economizar espaço
• ✅ Integração entre Ferramentas: Rastrear eventos de outras ferramentas MCP

Roteiro

Fase 4: Recursos Avançados (Em Desenvolvimento)

• 🚧 Grafo de Conhecimento: Rastreamento de relações entre entidades para compreensão de código
• 🚧 Busca Vetorial: Busca semântica usando linguagem natural
• 📋 Processamento Multi-Agente: Análise e síntese inteligentes
• 📋 Contexto Sensível ao Tempo: Visualizações de linha do tempo e entradas de diário

Fase 5: Documentação e Polimento

• ✅ Exemplos: Cenários abrangentes de início rápido
• ✅ Solução de Problemas: Problemas comuns e soluções
• 🚧 Receitas: Padrões e fluxos de trabalho comuns
• 📋 Tutoriais em Vídeo: Guias visuais para recursos principais

Melhorias Futuras

• Interface web para navegar pelo histórico de contexto
• Recursos de colaboração multiusuário/equipe
• Sincronização e compartilhamento em nuvem
• Integração com outros assistentes de IA
• Análises avançadas e insights
• Modelos de contexto personalizados
• Políticas automáticas de retenção

Atualização

Alteração do caminho do banco de dados (v0.12.x+)

Antes desta versão, o servidor resolvia context.db em relação ao diretório de trabalho atual do processo. O banco de dados agora fica em um caminho absoluto:

• Padrão: ~/mcp-data/memory-keeper/context.db
• Personalizado: defina DATA_DIR=/your/path — o servidor usará $DATA_DIR/context.db

Se você tiver dados existentes em um context.db no seu antigo diretório de trabalho, mova-os para o novo local antes de reiniciar o servidor:

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

Se DATA_DIR estiver definido, use esse caminho como destino em vez de ~/mcp-data/memory-keeper/.

O servidor exibirá um aviso em stderr se detectar um context.db no diretório atual que difira do diretório de dados configurado, incluindo o comando exato cp a ser executado.

Alteração do comando de instalação a partir do código-fonte

Se você registrou o memory-keeper usando node dist/index.js diretamente, atualize sua configuração MCP para usar o wrapper bin em vez disso:

# 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

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

1. Faça um fork do repositório
2. Crie sua branch de recurso (git checkout -b feature/AmazingFeature)
3. Faça commit das suas alterações (git commit -m 'Add some AmazingFeature')
4. Envie para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Autor

Mark Kreyman

Agradecimentos

• Construído para a comunidade Claude Code
• Inspirado pela necessidade de melhor gerenciamento de contexto em sessões de codificação com IA
• Agradecimentos à Anthropic pelo protocolo MCP

Suporte

Se você encontrar problemas ou tiver dúvidas:

• Abra uma issue no GitHub
• Consulte a documentação do MCP
• Participe das discussões da comunidade Claude Code

Palavras-chave

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