ContextKeeper

Fornece memória perfeita para desenvolvimento assistido por IA, capturando snapshots de contexto do projeto, permitindo busca em linguagem natural, rastreamento de evolução e inteligência de código.

GitHub

Experimente este MCPPatrocinado

Documentação

ContextKeeper 🧠

O servidor Model Context Protocol (MCP) com memória perfeita para desenvolvimento assistido por IA

O ContextKeeper revoluciona o desenvolvimento assistido por IA ao resolver o problema fundamental da perda de contexto entre sessões. Usando uma arquitetura inspirada em LSM-tree, ele mantém um histórico completo e pesquisável da evolução do seu projeto—garantindo que seu assistente de IA nunca esqueça.

🌟 Principais Recursos

📸 Captura Abrangente de Contexto

Snapshots de Desenvolvimento: Capture o estado completo do projeto, incluindo contexto git, informações do workspace e documentação
Gatilhos Automáticos: Git hooks (pre-commit, post-checkout) capturam contexto automaticamente
Arquivamento Inteligente: Compactação inspirada em LSM-tree mantém o armazenamento eficiente enquanto preserva o histórico
Rastreamento de Marcos: Marque snapshots com marcos significativos para fácil referência

🤖 Design Nativo para IA

Busca em Linguagem Natural: Pergunte "quando adicionamos autenticação?" e obtenha respostas instantâneas
Insights de Evolução: Acompanhe como os componentes evoluíram de "Planejado" para "Concluído"
Análise Sensível ao Contexto: Extração inteligente de palavras-chave e recomendações
Memória Perfeita: Seu assistente de IA lembra de tudo entre sessões

🔧 Ferramentas Model Context Protocol (MCP)

Seis ferramentas poderosas para assistentes de IA:

snapshot - Crie snapshots abrangentes de contexto
search_evolution - Busca em linguagem natural pelo histórico do projeto
track_component - Acompanhe a evolução de recursos ao longo do tempo
compare_snapshots - Compare quaisquer dois snapshots
get_status - Status do sistema com insights de compactação
get_timeline - Visão cronológica da evolução do projeto

💻 Inteligência de Código C#

Cinco ferramentas de análise de código com Roslyn:

FindSymbolDefinitions - Localize declarações de símbolos
FindSymbolReferences - Encontre todos os usos
NavigateInheritanceHierarchy - Explore relações entre tipos
SearchSymbolsByPattern - Correspondência de padrões com curingas
GetSymbolDocumentation - Extraia documentação XML

📝 Workspace do Usuário

Área de documentação flexível acessível pelo símbolo @ do Claude:

Requisitos: Armazene especificações do projeto e histórias de usuário
Design: Documente decisões e padrões arquiteturais
Instruções: Diretrizes personalizadas para o assistente de IA
Captura Automática: Arquivos do workspace incluídos em todos os snapshots

🚀 Início Rápido

Instalação

# 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

Integração com 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

📁 Arquitetura

Estrutura de Armazenamento

.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 do Snapshot

Cada snapshot captura:

Contexto Git: Branch, commit, arquivos não confirmados
Informações do Workspace: Diretório de trabalho, comandos recentes
Documentação: Todos os arquivos markdown (CLAUDE.md, README.md, etc.)
Metadados: Timestamp, tipo, marco, contexto completo como JSON

Auto-Compactação

O arquivamento automático é acionado quando:

O número de snapshots excede o limite (configurável, padrão: 20)
Existem snapshots com mais de 90 dias
Operação em segundo plano não bloqueante após a criação do snapshot

🤝 Integração MCP

Com Claude Desktop

Adicione à sua configuração do Claude Desktop (~/.claude.json):

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

Importante: Certifique-se de:

Substituir /path/to/contextkeeper pelo caminho real da sua instalação do ContextKeeper
Incluir "type": "stdio" na configuração
Manter command e args como campos separados (não os combine)

Com Outros Clientes MCP

O ContextKeeper implementa o protocolo MCP padrão e funciona com qualquer cliente compatível. O servidor fornece descoberta de ferramentas e comunicação baseada em JSON.

🛠️ Configuração

Arquivo de Configuração (`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"]
  }
}

Variáveis de Ambiente

CONTEXTKEEPER_PROFILE - Substituir perfil auto-detectado
CONTEXTKEEPER_DEBUG - Habilitar log de depuração

📊 Desempenho e Benchmarks

Métricas Native AOT

Tempo de Inicialização: ~12ms (vs ~200ms JIT)
Tamanho do Binário: 41MB executável autônomo (inclui Roslyn)
Uso de Memória: 18MB típico (redução de 78% vs JIT)
Velocidade de Busca: <100ms para 1000+ snapshots

Benchmarks de Operação

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

Eficiência de Armazenamento

Snapshots brutos: 100MB → Compactados: 28MB (redução de 72%)
Taxa de deduplicação: 85% para snapshots semelhantes
Compressão: Gzip alcançando proporção de 3:1

🧪 Desenvolvimento

Pré-requisitos

.NET 9.0 SDK
Visual Studio 2022 ou VS Code com extensão C#

Compilação a partir do Código Fonte

# 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

Testes

O projeto inclui uma suíte de testes abrangente com 98 testes cobrindo:

Funcionalidade principal (snapshots, busca, rastreamento de evolução)
Motor de compactação e otimização de armazenamento
Implementação do protocolo MCP
Integração com análise de código Roslyn
Cenários de integração

Execute os testes com:

# Run all tests
dotnet test

# Run with detailed output
dotnet test --verbosity detailed

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

Estrutura do Projeto

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

🎯 Demonstração Rápida

Exemplo: "Quando adicionamos autenticação?"

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

Exemplo: Acompanhar Evolução de Recursos

$ 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

🏗️ Mergulho Técnico

Arquitetura Inspirada em LSM-Tree

O ContextKeeper implementa uma abordagem Log-Structured Merge-tree para armazenamento eficiente:

Caminho de Escrita: Novos snapshots são anexados à camada ativa (escritas O(1))
Compactação: Merge em segundo plano reduz o armazenamento em 70%
Caminho de Leitura: Busca binária entre snapshots ordenados (O(log n))
Memória: Bloom filters para verificações rápidas de existência

Compilação Native AOT

Aproveitando o Native AOT do .NET 9 para desempenho em produção:

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

Implementação do Protocolo MCP

Servidor completo do Model Context Protocol com:

Camada de transporte JSON-RPC 2.0
Descoberta e introspecção de ferramentas
Respostas em streaming para grandes conjuntos de dados
Tratamento de erros conforme especificação MCP

Mergulho Profundo na Integração Roslyn

Capacidades avançadas de análise 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 que ContextKeeper?

O Problema

Assistentes de IA perdem contexto entre sessões, forçando desenvolvedores a explicar repetidamente o histórico do projeto, decisões arquiteturais e detalhes de implementação.

A Solução

O ContextKeeper mantém um histórico completo e pesquisável da evolução do seu projeto. Seu assistente de IA pode acessar instantaneamente:

Quando e por que recursos foram adicionados
Como os componentes evoluíram ao longo do tempo
Contexto completo de qualquer ponto no histórico
Documentação pesquisável em linguagem natural

Impacto no Mundo Real

Originalmente extraído do CodeCartographerAI, o ContextKeeper provou seu valor em produção:

Redução de 80% na re-explicação de contexto
Consultas históricas quase instantâneas (<100ms para 1000+ snapshots)
Recordação perfeita ao longo de meses de desenvolvimento
Integração perfeita com assistentes de IA

Exemplo Concreto: Depurando Problema em Produção

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

🗺️ Roadmap

Curto Prazo

Interface visual de linha do tempo (web UI)
Recuperação de contexto (restaurar estado completo de desenvolvimento)
Extensão para VS Code
Resumos aprimorados de IA

Futuro

Sincronização de equipe
Exportação para Confluence/Notion
Porta TypeScript para adoção mais ampla
Painel de métricas

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, leia nosso Guia de Contribuição para detalhes sobre nosso código de conduta e o processo para envio de pull requests.

Fluxo de Trabalho de Desenvolvimento

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

📄 Licença

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

🙏 Agradecimentos

Construído com a especificação Model Context Protocol
Alimentado por Roslyn para análise de código C#
Inspirado na arquitetura de armazenamento LSM-tree
Originalmente extraído do CodeCartographerAI

📞 Suporte

Issues: GitHub Issues
Discussões: GitHub Discussions
Documentação: Wiki

ContextKeeper - Nunca perca contexto novamente 🧠✨