Kemdicode Mcp

持久认知、集群总线与 Magistrale：为 AI 编码助手提供并行多 Agent 编排与实时监控

kemdiCode MCP 是一个 Model Context Protocol 服务，可为 AI 编码助手扩展持久认知、多 Agent 编排、分布式集群通信和上下文压缩功能。它提供涵盖 15 个类别的 63 个工具，由 Redis 支持跨会话状态，并通过 8 个大模型提供商执行内嵌 AI 任务。

受 Lorenz 启发的压缩流水线——通过庞加莱截面进行阶段检测、通过吸引子周期去重进行轨道压缩，并利用 CTC 扰动影响评分，在上下文窗口边界之间保持推理连续性。

集群总线与 Magistrale——双层总线（用于集群间 Redis Pub/Sub 的 ClusterBus L3，以及用于进程内事件的 GlobalEventBus L1），包含 18 种信号类型、基于标签的 MetaRouter 路由、反放大桥接机制，以及用于跨集群分布式提示词执行的 LLM Magistrale（4 种策略：先到先得、择优选取、共识、回退链）。

九位思维者——九个专业认知 Agent（苏格拉底式思考者、本体论专家、种子架构师、评估者、唱反调者、黑客、简化者、研究员、架构师），各自代表一种不同的思维模式。灵感来自 Harry Munro 的 Ouroboros。按需加载，从不预加载。

741 个测试，分布在 33 个测试文件中。兼容 Claude Code、Cursor、Windsurf、VS Code、Zed 及任何兼容 MCP 的客户端。

安装

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

配置

LLM 提供商

kemdiCode 支持 8 个 LLM 提供商，并采用统一的 provider:model:thinking 语法。

思考令牌控制：

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)

自定义端点（运行时热重载）：

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

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

工具参考

涵盖 15 个类别的 63 个工具。整合型工具使用 action 参数（例如，task action=create|get|list|update|delete）。

架构

事件总线（两层）

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

Lorenz 上下文压缩

使用三种算法，在压缩边界前后保持推理连贯性：

1. 阶段检测 — Poincare 截面分析。通过连续的 Jensen-Shannon 散度识别主题转换。阶段边界包含有关推理轨迹的最多信息。

2. 轨道压缩 — Lorenz 吸引子周期检测。使用 NxN TF-IDF 余弦相似度矩阵和贪心周期搜索（长度 2-10，至少重复 2 次）。保留第一个周期，剪除重复项。

3. 扰动影响 — 通过 JSD(full_context, context_without_item) 量化每个条目的贡献。高影响条目是能在压缩后保留的因果锚点。

九种思维模式

九个专用认知 Agent，各自代表一种不同的思维模式。灵感来自 Harry Munro 的 Ouroboros：

任何一种思维模式都可用作 agent 参数：ask-ai --agent socratic --prompt "..."。也可组合使用，实现多视角分析：苏格拉底式 → 本体论式 → 种子架构师（辩证式推进）。

Agentic Loop

自主 Agent 执行，支持启动子 Agent（最大深度为 2，全局预算为 10）、通过 @path 语法注入文件上下文，并可完整追踪编排 ID。

并行 Agent — 通过 agent-orchestrate --parallel 并行启动 2-10 个 Agent。每个 Agent 都会获得唯一的 orchestrationId，并通过 Redis 和内存缓存实时追踪。使用 Promise.allSettled 汇总结果。

实时监控 — 在 Agent 运行期间查询编排状态（MCP 会在工具调用期间阻塞，因此请使用 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

编排 ID 可追踪性 — 每个 Agentic Loop 都会获得一个 UUID。子 Agent 通过 parentOrchestrationId 引用父级。所有认知记录（决策、置信度、意图、错误、评议、交接）都带有 orchestrationId，以便完整追踪嵌套 Agent 层级。

工具访问 — Agent 默认可以使用所有 kemdiCode 工具（只读、kanban、思维链 — 不包含 shell 或文件写入）。使用 allowedTools 或 blockedTools 为每个 Agent 自定义工具。

并发模型

• 通过 AsyncLocalStorage 实现会话级隔离（在异步链中传播）
• 使用 Redis 事务修改任务状态（MULTI/EXEC、Lua 脚本）
• 使用 SET NX PX 实现分布式锁，通过 Lua CAS 释放，并进行 3 次退避重试

实际应用

kemdiCode 工具适用于三个层级。以下是开发者每天都会遇到的实际场景。

层级 1：无状态工具（无 AI Agent）

Claude Code（或 Cursor 等）直接调用 kemdiCode 工具 — 不包含内嵌 AI，仅提供结构化认知和代码智能。

场景：“我在不同项目中总是遇到相同的 Redis 超时错误”

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

场景：“Sprint 规划 — 在 3 名开发者之间安排 15 项任务”

# 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

场景：“加入团队后熟悉陌生的代码库”

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

层级 2：AI Agent（内嵌大模型执行）

kemdiCode 内部调用外部大模型进行推理、分析和生成。这些工作不会由 IDE 中的 AI 完成 — 而是由 kemdiCode 自带的 Agent 完成。

场景：“排查 API 响应时间为何从 50ms 增至 3 秒”

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

场景：“我们提出的微服务拆分方案是否可行？”

使用 mind-chain — 依次进行 Mind 到 Mind 的交接，每个 Mind 都在前一个的基础上继续：

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

链式流程：架构师提出方案 → 反方提出质疑 → 研究员核实事实 → 简化者找出务实方案 → 综合者整合所有观点。

场景：“让 3 个大模型评审一项关键安全变更”

# 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

层级 3：集群总线与 Magistrale（分布式大模型编排）

多个大模型节点通过 Redis Pub/Sub 进行通信。需要更广泛的上下文时，可将同一个问题分发给多个具有不同专长的模型。

场景：“设计速率限制器 — 获取 3 个模型给出的最佳答案”

# 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

场景：“架构决策 — 需要达成共识，而非只听取一种意见”

# 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

场景：“生产事故 — 需要尽可能快速地获得答案”

# 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

场景：“深入分析代码 — 让集群启动各自的 Agent”

# 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

开发

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

添加工具

1. 在 src/tools/<category>/ 中创建文件
2. 定义 Zod 架构，并为每个字段添加 .describe()
3. 实现 UnifiedTool 接口
4. 通过 src/tools/index.ts 中的 registerLazyTool() 注册
5. 在 src/tools/annotations-map.ts 中添加注释

文档

• 技术白皮书（PDF） — Lorenz 紧凑化、Nine Minds、Poincare 相位检测、轨道压缩、39 条参考文献（LaTeX 源文件）
• 架构概览
• 总线架构
• 示例 — 集成模式与工作流

许可证

GNU 通用公共许可证 v3.0

作者

Dawid Irzyk — [email protected] — Kemdi Sp. z o.o.