EvoKernel MCP server

🧬 EvoKernel (evo-kernel)

Stop Repeating the Same Bug Across Coding Sessions — AST-Verified Cognitive Memory & 6-Stage Deterministic Gatekeeper, with 88.7% Lower Session-Start Token Tax and 0 External Dependencies.

The Deterministic Self-Evolving Meta-Kernel & Cognitive Context OS for AI Coding Agents
Claude Code · Cursor · Codex · Windsurf · Cline · Roo · GitHub Copilot · OpenCode · Gemini · Antigravity

English · 简体中文 · 🌐 Product Site · 🖥️ Interactive Workbench Demo · 📊 Benchmarks

What is EvoKernel? EvoKernel gives your AI coding agent cross-session AST-verified cognitive memory, visible 1-line recall receipts (🛡️ EvoKernel Recall), and a 6-stage deterministic Gatekeeper so fixed bugs stay fixed across sessions — while folding sprawling MCP tool schemas and monolithic rule files behind 5 fixed meta-primitives (-88.7% session-start token tax: 27,150 → 3,066 tok/turn, 100% KV cache hit, 0 external dependencies).

[!NOTE] Disambiguation Note: EvoKernel (evo-kernel) is an agent architecture and context engineering framework for AI coding assistants (Claude Code, Cursor, Windsurf, Codex, Gemini, etc.). It is not affiliated with academic ICML papers/benchmarks of similar naming or Linux kernel projects.

---

⚡ 30-Second Quick Start

Get started in 3 commands — zero installation required:

# 1. Instant Zero-Write X-Ray (<25ms) — scan host rules, git hotspots & memory coverage
npx -y evo-kernel score

# 2. One-Click Safe Wiring & Doctor Check — wire 10 IDEs safely with stealth mode
npx -y evo-kernel init --stealth && npx -y evo-kernel doctor
# (Preview MCP virtualization token savings safely with: npx -y evo-kernel virtualize --dry-run)

# 3. Launch EvoKernel Workbench to inspect capabilities, AST memories & 7-day recall
npx -y evo-kernel ui

💡 Node.js 18 / 20 Instant 1-Liner (No Global Node Upgrade Needed):
npx -y -p node@22 evo-kernel score
(Note: npx -p node@22 is recommended for one-off CLI diagnostics. For a persistent background MCP service, upgrade system Node to >= 22.5.0 via nvm install 22 && nvm use 22 or fnm use 22, and install globally via npm install -g evo-kernel.)
Why Node.js >= 22.5.0? EvoKernel runs purely on native node:sqlite, node:module, and node:test — providing 0 external npm dependencies and 0 supply-chain vulnerability risk.

# Clone and build from source (takes <50ms, zero npm install required)
git clone https://github.com/damonless/EvoKernel.git
cd EvoKernel
node ./scripts/build.mjs

# Wire L0 Meta-Rule Seed + Single Meta-MCP into your active coding agents
node ./dist/cli/index.js init --targets auto --stealth

# Cold-start mine your repository structure, project stacks & Git fix history
node ./dist/cli/index.js bootstrap --max-commits=50

# Run offline worktree optimization cycle
node ./dist/cli/index.js optimize --dim both -k 3

# CI / Deliverable canonical inspection (.xlsx, .docx, .pptx, .csv, .json, .md)
npx -y evo-kernel check ./README.md

# Inspect capability tree, multi-branch AST memory freshness & live MCP handshake
node ./dist/cli/index.js tree
node ./dist/cli/index.js memory verify
node ./dist/cli/index.js doctor --roi
node ./dist/cli/index.js audit --global

---

🔒 Reversibility, Team Sharing & Privacy

EvoKernel is designed from the ground up to be safe to trial, transparent to inspect, and completely reversible at any moment:

1. What evo init Touches & 1-Command Lossless Uninstall

When you run npx evo-kernel init, it touches only three isolated surfaces:

• Host Agent Rule Files: Inserts a compact (<1,100 tok), bounded English managed block between <!-- EVO:START --> and <!-- EVO:END --> markers in detected configuration files (CLAUDE.md, AGENTS.md, .cursor/rules/evo-kernel.mdc, or GEMINI.md when .gemini/ is present — avoiding duplicate root Markdown injection). Existing user rules outside these markers are untouched.
• Host MCP Configs: Registers a single stdio gateway entry for evo-kernel (leaving third-party servers untouched unless virtualized).
• Workspace .evo/ Tree: Generates local capability and episodic memory directories (.evo/rules/, .evo/skills/, .evo/memories/, .evo/tools/, .evo/.cache/).

To cleanly and completely revert your repository and agent configurations back to baseline, run:

npx -y evo-kernel virtualize --restore && npx -y evo-kernel uninstall

This restores any virtualized MCP servers to host configuration files, strips all <!-- EVO:START --> blocks cleanly, unwires registered lifecycle hooks, and removes .evo/ with zero left-behind configuration artifacts.

2. Multi-Person Team Sharing vs. --stealth Mode

• Multi-Person Team Sharing (Default evo init): Commit .evo/rules/, .evo/memories/, and .evo/tools/ to your Git repository. Every team member and coding agent immediately benefits from shared root-cause bug fixes and verified sandboxed micro-tools, while internal cache files (.evo/.cache/) are automatically gitignored.
• Personal Standalone Trial (evo init --stealth): Appends .evo/ and modified host rule files to .git/info/exclude. Git completely ignores EvoKernel files locally without touching .gitignore or creating uncommitted working tree diffs in shared repositories. Zero git pollution.

3. 100% Local-First & Zero Outbound Telemetry

EvoKernel performs 0 outbound network requests, transmits 0 analytics or telemetry, and requires 0 external cloud APIs. All SQLite FTS5 indexes and observable recall ledgers (.evo/.cache/telemetry.db) are stored 100% locally on your machine.

---

📈 50-Turn Context-Tax Analytical Model & Live Engine Micro-Benchmark (npm run benchmark)

Analytical cost/cache model across 8 standard MCP servers (github, playwright, kubernetes, docker, linear, postgres, sentry, context7 — 77 tools total) + a mature repo knowledge base (10 rules, 4 skills, 5 micro-tools, 15 debugging memories) over a 50-turn coding session with 3 mid-session capability evolutions, paired with live local engine micro-benchmarks (reproduce locally via npm run benchmark). Note on zero-prefix-invalidation condition: The 0 mid-session cache invalidation guarantee holds when new capabilities are crystallized as core: false scoped rules, skills, micro-tools, or memory entries (the default in EvoKernel), which reside in .evo/ without mutating the top-level tools/list schema or host CLAUDE.md L0 prefix.

Metric	Raw Multi-MCP + Monolithic CLAUDE.md	🧬 EvoKernel 5-Tool Meta-Gateway	Model / Live Result
Exposed Tool Schemas	77 tools (14,700 tok)	5 fixed meta-tools (1,916 tok)	-93.5% schema count (-87.0% schema tok)
Session-Start Static Prefix / Turn	27,150 tokens	3,066 tokens	-88.7% session-start token tax
Mid-Session Cache Invalidations	3 full prefix busts	0 (100% cache hit)	100% KV Cache Shield
50-Turn Cumulative Prompt Tokens	1,931,250 tokens	738,570 tokens	-61.8% total token load
50-Turn Cost (Claude Sonnet 4.5)	$1.15	$0.34	-70.4% API cost
50-Turn Cost (Claude Opus 4.5)	$5.76	$1.70	-70.4% API cost
Live Engine AST Verification Speed	Unverified text (drifts silently)	~0.32 ms / memory	<12ms batch across 36 memories¹

¹ Terminology Note: AST Anti-Drift / AST Fingerprinting utilizes Zero-Dep Lexical-Structural Skeleton Fingerprinting, which is immune to comments, code reformatting, and line-number drift without requiring external compiler dependencies.

---

⚡ Why Most "Self-Improving Agent" Setups Fail After 30 Sessions

Every developer using Claude Code, Cursor, Windsurf, Cline, Roo, Copilot, Codex, OpenCode, Gemini, or Antigravity hits five engineering walls:

1. The Slop-Pile Rule Rot (CLAUDE.md Bloat): Appending "Never do X" every time an agent makes a mistake turns your rules file into a 10,000-token contradictory junk drawer. Past ~1,500 tokens, LLM instruction-following degrades sharply (Lost-in-the-Middle).
2. Worker Grading Its Own Homework: Letting an LLM directly overwrite global skills or scripts without deterministic verification leads to broken, path-hardcoded scripts being crystallized as "permanent tools."
3. The Dynamic MCP Prompt-Cache Collapse: If "evolving MCP tools" means spawning new MCP servers or mutating the top-level tools/list schema mid-session, you invalidate the LLM's KV Prompt Cache prefix on every mutation—increasing token costs by 5–10x and requiring constant IDE restarts.
4. Third-Party MCP Sprawl: Adding 10 downstream MCP servers directly to your agent configuration dumps 50–100 tool definitions into every prompt header, diluting tool-calling accuracy and inflating baseline context costs.
5. Confounded Causation & Hallucinatory Evolution: Agents mutate rules based on spurious correlation during complex multi-step sessions without isolating whether a rule actually helped, hurt, or was contested by confounding variables.

EvoKernel solves all five with a deterministic local compiler, worktree evolution engine & routing kernel:

---

📊 Comprehensive Competitive Benchmark Matrix

Dimension	MemGPT / Letta	Aider	Direct MCP Proxies	affaan-m/ECC	AMAP-ML/SkillClaw	🧬 EvoKernel v0.3.0 (Ours)
Primary Focus	Stateful conversational agent DB	Git-centric terminal pair programmer	Pass-through MCP aggregation	Static engineering prompt library	Background LLM evolutionary agent	Deterministic self-evolving meta-kernel for coding agents
Integration Architecture	Heavy external service / Postgres / Python daemon	Standalone Python CLI replacing developer IDE	Raw JSON-RPC bridge passing all child tools	Preloaded Markdown templates	Hijacks /v1/chat reverse proxy	Parasitic Meta-MCP + <80-line Seed injected into existing IDEs
Runtime Dependencies	Heavy (Postgres, Python, vector DBs)	Python pip packages	Node / Python packages	Zero (plain markdown)	Python FastAPI daemon	0 Dependencies (Pure Node.js >= 22.5 built-ins: node:sqlite, node:module, node:test)
Prompt Cache Stability	Cache-unfriendly (frequent context shifts)	Varies per edit	Destructive (exposing all child tools busts KV prefix on every change)	High context footprint	Neutral	100% Byte-Stable: Exactly 5 immutable meta-tools exposed to host
Downstream MCP Virtualization	None	None	Dumb pass-through (50+ tools in prompt)	None	None	Zero-cache-invalidation FTS5 index + on-demand stdio JSON-RPC proxy
Verification & Gatekeeper	Model self-reflection	Git commit diffs & tests	None	Manual /learn-eval	Async LLM reviewer	6-Stage Deterministic Gatekeeper (Static Security, Lexical De-Symbol, Sandbox Exit 0, BM25, 1500-tok Cap, Anti-Confounding)
Offline Worktree Optimization	None	None	None	None	Cloud LLM evaluations	evo optimize: Isolated Git worktrees, dual inv/dom cycles, automated probe evaluation & regression rollbacks
Deliverable Inspection	None	None	None	None	None	Zero-dependency canonical parser for .xlsx, .docx, .pptx, CSV, JSON/JSONL, and Markdown
Episodic Memory & Anti-Drift	Semantic vector embeddings (hallucination prone)	Repo map only	None	None (static docs)	No AST verification	Zero-Dep Lexical-Structural Symbol Fingerprinting (Fast regex/lexical AST hash, [STALE] demotion, Topology Penetration Anchors)
Workbench & Diagnostic Scoring	Web UI with Postgres	None	None	None	Web UI	evo score (<25ms zero-write scan) & evo ui (0-dep EvoKernel Workbench, dual-mode native client, SSE live-reload, strict CSP, exportable single-file HTML)
Causal Telemetry	None	Git diff size	None	None	Win/loss counter	Causal outcomes (helped, hurt, contested) with ERR_CONFOUNDED_CAUSATION protection
Multi-Agent Harness Support	Standalone only	Standalone only	Generic MCP clients	Claude Code / Cursor only	Generic proxy	10 Native Harnesses (Claude, Cursor, Windsurf, Cline, Roo, Copilot, Codex, OpenCode, Gemini, Antigravity)
Cold-Start Gene Extraction	Empty until chat sessions accumulate	Git repo scan	Empty	Static catalog	Empty until chat history grows	evo bootstrap mines project stacks + git fixes in <10s

---

🧠 Core Architecture & Deep Technical Reference

EvoKernel exposes 5 immutable meta-tools (evo_search, evo_inspect, evo_run, evo_propose, evo_compact) over stdio for 100% KV prompt-cache retention, backed by offline Git worktree optimization, zero-dependency deliverable inspection, causal outcome attribution, and 10-host configuration adapters.

5 Immutable Meta-Tools (stdio JSON-RPC 2.0)

Meta-Tool	Tier	Purpose
evo_search	L0	FTS5 BM25 search across Rules, Skills, Micro-Tools, Virtualized External Tools, and Memories. Performs live Stage-2 AST fingerprint verification and demotes [STALE] memories automatically.
evo_inspect	L1 / L2	Progressive disclosure loader. Delivers Symptom/Root-Cause/Solution triads, JSON Schemas for virtualized external tools, and Topology Penetration Anchors (live line spans, callers, and negative dead-ends).
evo_run	Execution	Executes local sandboxed Micro-Tools (.mjs, .py, .ps1, .sh) or proxies calls to downstream MCP servers via McpProxyManager.
evo_propose	Evolution	Submits a candidate Rule, Skill, Micro-Tool, or Memory through the 6-Stage Deterministic Gatekeeper (Static Security, Lexical De-Symbol, Sandbox Dry-Run, BM25 Deduplication, Token Budget Cap, Anti-Confounding).
evo_compact	GC	Atomically merges fragmented rules or archives [STALE] memories into .evo/archive/ to keep core token consumption under the 1,500-token limit.

Downstream MCP Proxy Virtualization (evo virtualize)

Host Coding Agent (Claude / Cursor / Copilot / etc.)
                  │
                  ▼ Fixed 5-Tool stdio Interface (100% Byte-Stable KV Cache)
         ╔════════════════════════════════════════════════════╗
         ║               EvoKernel Meta-MCP                   ║
         ║  evo_search · evo_inspect · evo_run · propose · compact
         ╚════════════════════════════════════════════════════╝
                  │                      │
        FTS5 BM25 Search          Proxy Execution (`evo_run`)
                  ▼                      ▼
        ┌────────────────────┐   ┌─────────────────────────────┐
        │ capability_fts     │   │ McpProxyManager (Pool)      │
        │ ext__postgres__... │   └──────────────┬──────────────┘
        │ ext__github__...   │                  │ stdio JSON-RPC
        └────────────────────┘                  ▼
                                 ┌─────────────────────────────┐
                                 │ Downstream MCP Servers      │
                                 │ postgres · github · docker  │
                                 └─────────────────────────────┘

evo virtualize --dry-run   # Preview token savings without modifying files
evo virtualize             # Fold third-party stdio MCPs into EvoKernel's dynamic proxy
evo virtualize --restore   # Losslessly restore virtualized MCP servers back to host configs

Universal Hook Router (evo hook <event>)

evo hook post-tool --tool Edit --file src/core/storage.ts   # Track mutations, >=10 diagnostic reads & scoped rules
evo hook stop                                               # Emit crystallization & anti-poisoning dirty alerts
evo hook pre-commit                                         # Block leaked caches or >1,500-token core budget
evo hook mark-recovery                                      # Record recovery telemetry after command failures

# Run offline optimization across both Invariant and Domain dimensions
evo optimize --dim both -k 3