kemdiCode MCP

Cognição Persistente, Cluster Bus & Magistrale, Orquestração Paralela Multi-Agente com Monitoramento ao Vivo para Assistentes de Codificação com IA

kemdiCode MCP é um servidor Model Context Protocol que estende assistentes de codificação com IA com cognição persistente, orquestração multi-agente, comunicação distribuída em cluster e compactação de contexto. 63 ferramentas em 15 categorias, apoiadas por Redis para estado entre sessões e 8 provedores de LLM para execução de IA embarcada.

Pipeline de compactação inspirado em Lorenz — Detecção de Fase via seções de Poincaré, Compressão de Órbita via deduplicação de ciclo de atrator, e pontuação de impacto de perturbação CTC — mantém a continuidade do raciocínio através dos limites da janela de contexto.

Cluster Bus & Magistrale — barramento de duas camadas (ClusterBus L3 para Redis Pub/Sub entre clusters, GlobalEventBus L1 para eventos em processo) com 18 tipos de sinal, roteamento por tags MetaRouter, pontes anti-amplificação e Magistrale de LLM para execução distribuída de prompts entre clusters (4 estratégias: primeiro-vencedor, melhor-de-n, consenso, cadeia-de-fallback).

As Nove Mentes — nove agentes cognitivos especializados (Socrático, Ontologista, Arquiteto de Sementes, Avaliador, Contrarian, Hacker, Simplificador, Pesquisador, Arquiteto), cada um um modo diferente de pensar. Inspirado em Ouroboros por Harry Munro. Carregados sob demanda, nunca pré-carregados.

741 testes em 33 arquivos de teste. Funciona com Claude Code, Cursor, Windsurf, VS Code, Zed e qualquer cliente compatível com MCP.

Instalação

bun install -g kemdicode-mcp

claude mcp add kemdicode-mcp -- kemdicode-mcp --stdio

{
  "mcpServers": {
    "kemdicode-mcp": {
      "command": "kemdicode-mcp",
      "args": ["--stdio"]
    }
  }
}

{
  "mcpServers": {
    "kemdicode-mcp": {
      "command": "kemdicode-mcp",
      "args": ["--stdio"]
    }
  }
}

{
  "mcp": {
    "servers": {
      "kemdicode-mcp": {
        "command": "kemdicode-mcp",
        "args": ["--stdio"]
      }
    }
  }
}

{
  "context_servers": {
    "kemdicode-mcp": {
      "command": {
        "path": "kemdicode-mcp",
        "args": ["--stdio"]
      }
    }
  }
}

{
  "mcpServers": {
    "kemdicode-mcp": {
      "command": "kemdicode-mcp",
      "args": ["--stdio"]
    }
  }
}

kemdicode-mcp --port 3100

# Docker (recommended)
docker run -d -p 6379:6379 redis:alpine

# macOS
brew install redis && brew services start redis

# Debian/Ubuntu
sudo apt install redis-server && sudo systemctl start redis

git clone https://github.com/kemdi-pl/kemdicode-mcp.git
cd kemdicode-mcp
bun install && bun run build && bun run start

Configuração

Provedores de LLM

O kemdiCode suporta 8 provedores de LLM com uma sintaxe unificada provider:model:thinking.

Controle de token de raciocínio:

o:o3:high                     # OpenAI reasoning effort (low/medium/high)
a:claude-sonnet-4-6:4k        # Anthropic thinking budget (4096 tokens)
g:gemini-2.5-flash:8k         # Gemini thinking budget (8192 tokens)

Endpoints personalizados (hot-reload em tempo de execução):

ai-config --action add-custom --name minimax --baseURL https://api.minimax.io/v1 --apiKey sk-...
# Then use: custom:minimax:MiniMax-M2.5

Flags de CLI

kemdicode-mcp [options]

  --stdio                 Stdio transport (subprocess mode for MCP clients)
  -m, --model <spec>      Primary AI model (provider:model:thinking)
  -f, --fallback <spec>   Fallback model on quota/error
  --port <n>              HTTP server port (default: 3100)
  --host <addr>           Bind address (default: 127.0.0.1)
  --redis-host <addr>     Redis host (default: 127.0.0.1)
  --redis-port <n>        Redis port (default: 6379)
  --no-context            Disable Redis context sharing
  --compact               Minimal output

Referência de Ferramentas

63 ferramentas em 15 categorias. Ferramentas consolidadas usam um parâmetro action (ex.: task action=create|get|list|update|delete).

Arquitetura

Barramento de Eventos (2 Camadas)

L3  ClusterBus     Redis Pub/Sub cross-process signaling
                   18 signal types, 4 send modes (unicast/broadcast/routed/multicast)
                   HMAC auth, bloom filter dedup, backpressure, circuit breaker
    ----bridges--> hop limit 5, source prefix guard
L1  GlobalEventBus In-process async events, namespaced, max chain depth 8
                   Redis bridge for cross-session propagation

Compactação de Contexto Lorenz

Três algoritmos para manter a continuidade do raciocínio através dos limites de compactação:

1. Detecção de Fase — Análise de seção de Poincaré. Divergência de Jensen-Shannon consecutiva identifica transições de tópico. Limites de fase carregam informações máximas sobre a trajetória do raciocínio.

2. Compressão de Órbita — Detecção de ciclo de atrator de Lorenz. Matriz de similaridade de cosseno TF-IDF NxN com busca gulosa de ciclo (comprimento 2-10, mínimo 2 repetições). Retém o primeiro ciclo, remove duplicatas.

3. Impacto de Perturbação — JSD(contexto_completo, contexto_sem_item) quantifica a contribuição de cada item. Itens de alto impacto são âncoras causais que sobrevivem à compactação.

As Nove Mentes

Nove agentes cognitivos especializados, cada um um modo diferente de pensar. Inspirado em Ouroboros por Harry Munro:

Use qualquer Mente como parâmetro agent: ask-ai --agent socratic --prompt "...". Combine-as para análise multi-perspectiva: Socrático → Ontologista → Arquiteto de Sementes (progressão dialética).

Loop Agêntico

Execução autônoma de agentes com geração de sub-agentes (profundidade máxima 2, orçamento global 10), injeção de contexto de arquivo via sintaxe @path e rastreabilidade completa de ID de orquestração.

Agentes Paralelos — Lance 2-10 agentes em paralelo via agent-orchestrate --parallel. Cada um recebe um orchestrationId único, rastreado em tempo real via Redis e cache em memória. Resultados agregados via Promise.allSettled.

Monitoramento ao Vivo — Consulte o status da orquestração enquanto os agentes executam (MCP bloqueia durante chamadas de ferramenta, então use HTTP):

# List all active orchestrations
curl http://localhost:3100/orchestrations

# Get specific orchestration status
curl http://localhost:3100/orchestrations/<id>

# Or via MCP tool (when not blocked)
monitor --view orchestrations

Rastreabilidade de ID de Orquestração — Cada loop agêntico recebe um UUID. Sub-agentes referenciam o pai via parentOrchestrationId. Todos os registros de cognição (decisões, confiança, intenções, erros, críticas, transferências) carregam orchestrationId para rastreabilidade completa em hierarquias de agentes aninhadas.

Acesso a Ferramentas — Todas as ferramentas do kemdiCode estão disponíveis para agentes por padrão (somente leitura, kanban, cadeias de raciocínio — sem shell/escrita de arquivo). Use allowedTools ou blockedTools para personalizar por agente.

Modelo de Concorrência

• Isolamento por sessão via AsyncLocalStorage (propaga através de cadeias assíncronas)
• Transações Redis para mutações de estado de tarefa (MULTI/EXEC, scripts Lua)
• Locks distribuídos com SET NX PX, liberação CAS Lua, backoff de 3 tentativas

Uso no Mundo Real

As ferramentas do kemdiCode funcionam em três níveis. Aqui estão cenários práticos que um desenvolvedor encontra diariamente.

Nível 1: Ferramentas Sem Estado (sem agentes de IA)

Claude Code (ou Cursor, etc.) chama as ferramentas do kemdiCode diretamente — sem IA embarcada, apenas cognição estruturada e inteligência de código.

Cenário: "Continuo encontrando o mesmo bug de timeout do Redis em vários projetos"

# 1. Check if you've seen this before
error-pattern action=match errorType="redis-timeout"
# → Returns: "Pattern found: connection pool exhaustion under load.
#    Fix: set maxRetriesPerRequest=3, enable enableOfflineQueue=false"

# 2. It's a new variant — record it
error-pattern action=record \
  errorType="redis-timeout" \
  pattern="ETIMEDOUT after 200 concurrent writes in bull queue" \
  fix="Switch from ioredis default to pooled connection with family=6 on k8s"

# 3. Track the decision
decision-journal action=record \
  question="How to handle Redis under Bull queue load?" \
  options='["connection pool","Redis Cluster","separate Redis instance"]' \
  chosen="connection pool" \
  reasoning="Cluster adds ops complexity, separate instance adds cost"

Cenário: "Planejamento de sprint — organize 15 tarefas entre 3 desenvolvedores"

# Create workspace + board
workspace action=create name="Q1 Auth Rewrite"
board action=create name="Sprint 12" workspaceId=<ws-id>

# Batch create tasks
task action=create boardId=<board-id> title="Migrate session store to Redis" priority=high labels='["backend"]'
task action=create boardId=<board-id> title="Add PKCE flow to OAuth" priority=high labels='["security"]'
task action=create boardId=<board-id> title="Write E2E tests for login" priority=medium labels='["testing"]'
# ... more tasks

# Assign and track
task action=assign taskId=<id> assignee="alice"
task action=update taskId=<id> status="in-progress"
board action=status boardId=<board-id>
# → Shows kanban: 3 todo, 2 in-progress, 1 done

Cenário: "Navegar em uma base de código desconhecida após entrar em uma equipe"

# Find where auth middleware is defined
find-definition --symbol "authMiddleware" --path "@src/"

# Find all places it's used
find-references --symbol "authMiddleware" --path "@src/"

# Search by concept, not just text
semantic-search --query "rate limiting per user" --path "@src/"

# Persist findings for next session
memory action=write name="auth-architecture" \
  content="authMiddleware in src/middleware/auth.ts, used in 14 routes. Rate limiting in src/middleware/rateLimit.ts uses sliding window with Redis MULTI."

Nível 2: Agentes de IA (execução de LLM embarcada)

O kemdiCode chama LLMs externos internamente para raciocinar, analisar e gerar. A IA do seu IDE não faz esse trabalho — os próprios agentes do kemdiCode fazem.

Cenário: "Depurar por que o tempo de resposta da API passou de 50ms para 3 segundos"

# Start structured reasoning with the plan agent
agent-orchestrate \
  --agent plan \
  --task "Analyze why GET /api/users went from 50ms to 3s. Check @src/routes/users.ts and @src/services/userService.ts for N+1 queries, missing indexes, or unnecessary joins." \
  --sessionId "debug-perf" \
  --maxIterations 10 \
  --enableCognition true

# The agent autonomously:
# 1. Reads the files via find-definition / find-references
# 2. Identifies: userService.getAll() does 3 sequential DB calls
# 3. Records in error-pattern: "N+1 query in user list endpoint"
# 4. Records in decision-journal: "Consolidate to single JOIN query"
# 5. Returns: "Root cause: 3 sequential queries per user (N+1). Fix: replace
#    with single LEFT JOIN on user_roles and user_preferences."

Cenário: "A divisão de microsserviços proposta é uma boa ideia?"

Use mind-chain — transferência sequencial Mente-a-Mente onde cada Mente constrói sobre a anterior:

# One call — 4 Minds analyze in sequence, each seeing previous outputs
mind-chain \
  --composition custom \
  --minds '["architect", "contrarian", "researcher", "simplifier"]' \
  --prompt "Evaluate splitting the monolith at @src/ into auth-service, user-service, and notification-service. We have 3 developers and 45 shared models."

# Or use a predefined composition:
mind-chain --composition adversarial \
  --prompt "Should we split the monolith into microservices? @src/"

# Full review with 6 Minds + synthesis:
mind-chain --composition full-review \
  --prompt "Architecture decision: monolith vs microservices for @src/"

A cadeia executa: Arquiteto propõe → Contrarian desafia → Pesquisador verifica fatos → Simplificador encontra o caminho pragmático → Síntese combina todas as perspectivas.

Cenário: "Obter 3 LLMs para revisar uma mudança crítica de segurança"

# Send to GPT-4o, Claude, and Gemini in parallel
multi-prompt \
  --prompt "Review this OAuth implementation for security vulnerabilities: @src/auth/oauth.ts" \
  --models '["o:gpt-4.1", "a:claude-sonnet-4-6", "g:gemini-2.5-pro"]' \
  --agent evaluator

# Or use CEO-and-Board consensus
consensus-prompt \
  --prompt "Is this PKCE implementation correct and secure? @src/auth/pkce.ts" \
  --boardModels '["o:gpt-4.1", "g:gemini-2.5-pro", "d:deepseek-v3"]' \
  --ceoModel "a:claude-sonnet-4-6"
# → Board votes + CEO synthesizes a final verdict with reasoning

Nível 3: Cluster Bus & Magistrale (orquestração distribuída de LLM)

Múltiplos nós de LLM se comunicam via Redis Pub/Sub. Use isso quando precisar de contexto mais amplo — despachando a mesma pergunta para vários modelos com especializações diferentes.

Cenário: "Projetar um limitador de taxa — obter a melhor resposta de 3 modelos"

# Dispatch to all registered clusters, pick the best response
cluster-bus-magistrale \
  --prompt "Design a distributed rate limiter for a REST API with 10K req/s. Must handle multi-region, be Redis-backed, and support per-user and per-IP limits. Include TypeScript implementation." \
  --strategy "best-of-n"

# Magistrale:
# 1. Sends the prompt to Cluster A (GPT-4.1), Cluster B (Claude), Cluster C (Gemini)
# 2. Each cluster runs PassController (multi-pass refinement)
# 3. Scores responses: quality 0.45, detail 0.25, relevance 0.15, latency -0.15
# 4. Returns the highest-scoring implementation

Cenário: "Decisão de arquitetura — preciso de consenso, não apenas uma opinião"

# Require agreement between models
cluster-bus-magistrale \
  --prompt "For a real-time collaboration feature (like Google Docs), should we use CRDTs, OT, or a simpler last-write-wins approach? Team has 2 backend devs, deadline is 6 weeks." \
  --strategy "consensus"

# Consensus strategy:
# 1. All clusters generate independent responses
# 2. TF-IDF cosine similarity scoring between responses (threshold 0.3)
# 3. If agreement: returns consensus answer
# 4. If disagreement: returns all positions with similarity scores

Cenário: "Incidente de produção — preciso da resposta mais rápida possível"

# First model to respond wins
cluster-bus-magistrale \
  --prompt "Our PostgreSQL replication lag jumped to 30s. WAL sender is active, network is fine. What should we check first?" \
  --strategy "first-wins"

# Returns in ~1s from whichever model responds fastest

Cenário: "Análise profunda de código — deixe os clusters gerarem seus próprios agentes"

# Each cluster spawns an autonomous agent with tool access
cluster-bus-magistrale \
  --prompt "Find potential race conditions in the authentication module" \
  --strategy "first-wins" \
  --orchestrate true \
  --orchestrateAgent "plan" \
  --orchestrateMaxIterations 8 \
  --orchestrateAllowedTools '["find-definition", "find-references", "semantic-search"]'

# Orchestration:
# 1. Magistrale dispatches to clusters with orchestrate payload
# 2. Each cluster spawns a full agentic loop (not just an LLM call)
# 3. Agent reasons, calls tools (find-definition, semantic-search), iterates
# 4. Returns structured analysis with tool call evidence

Desenvolvimento

bun install                    # Install dependencies
bun run build                  # Compile TypeScript
bun run dev                    # Hot reload
bun run test                   # Run 741 tests
bun run typecheck              # Type check
bun run lint                   # ESLint
bun run format                 # Prettier

Adicionando Ferramentas

1. Crie um arquivo em src/tools/<category>/
2. Defina o esquema Zod com .describe() por campo
3. Implemente a interface UnifiedTool
4. Registre via registerLazyTool() em src/tools/index.ts
5. Adicione anotação em src/tools/annotations-map.ts

Documentação

• Whitepaper Técnico (PDF) — Compactação Lorenz, Nove Mentes, detecção de fase de Poincaré, compressão de órbita, 39 referências (fonte LaTeX)
• Visão Geral da Arquitetura
• Arquitetura do Barramento
• Exemplos — Padrões de integração e fluxos de trabalho

Licença

GNU General Public License v3.0

Autor

Dawid Irzyk — dawid@kemdi.pl — Kemdi Sp. z o.o.