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

This is the beginning of the README. Read the rest at the original. Read the full README ↗