KERNL V2.0 - Persistent Intelligence Layer for AI. Transform Claude from stateless to persistent with 75 tools: crash recovery, semantic search, cross-project learning, system control, and 100% Desktop Commander parity.
npm install kernl-mcpTransform AI assistants from stateless to persistent, project-aware intelligence systems




Formerly "Project Mind" β Now KERNL: The authoritative system control layer for AI
---
KERNL is an MCP (Model Context Protocol) server that solves three fundamental problems with AI assistants:
β
Session Recovery - Automatic checkpoints survive crashes
β
Context Preservation - Zero bootstrap tax with automatic resume
β
Cross-Project Learning - Patterns compound across projects
β
Full System Control - Complete desktop authority (100% Desktop Commander parity)
β
Self-Documenting - Introspection and auto-generated documentation
β
Production Ready - Comprehensive testing and validation
---
typescript
// Automatic checkpoints every 5-10 tool calls
auto_checkpoint({ project: "my-app", progress: 0.5 })// Claude crashes...
// Next session automatically resumes
check_resume_needed({ project: "my-app" })
// β "You were refactoring auth (50% complete). Resume?"
`$3
Find files by meaning, not keywords
`typescript
search_semantic({
project: "my-app",
query: "authentication logic",
limit: 10
})
// β Returns JWT validation, middleware, login routes
`$3
Solutions transfer automatically
`typescript
suggest_patterns({
currentProblem: "large markdown files slow to query"
})
// β "Hybrid Source of Truth pattern (85% confidence)"
`$3
Complete desktop authority
`typescript
// Interactive Python REPL
sys_start_process({ command: "python3 -i" })
sys_interact_with_process({ pid: 1234, input: "import pandas" })// PDF generation
sys_write_pdf({ path: "report.pdf", content: "# Report..." })
// File operations anywhere
sys_copy_path({ source: "D:/file.txt", dest: "C:/backup/" })
`$3
Auto-generated documentation
`typescript
sys_generate_docs({
format: 'markdown',
output: 'D:/TOOLS.md'
})
// β 75 tools documented automatically
`---
π What's Included (75 Tools)
$3
Survive crashes and preserve context
- check_resume_needed - Detect incomplete work
- auto_checkpoint - Automatic progress saves
- mark_complete - Clear resume state
- get_session_state - Manual state check
- save_session_state - Manual checkpoint$3
Multi-tenant project registry
- pm_register_project - Register projects
- pm_list_projects - List all projects
- pm_get_project - Get project details$3
Format-aware file operations
- pm_read_file - Read (Excel/PDF/Images/Text)
- pm_write_file - Write with format detection
- pm_search_files - Find files in projects
- pm_batch_read - Read multiple files
- pm_list_files - List directory contents
- pm_get_file_info - Get metadata + line counts$3
AI-powered semantic capabilities
- search_semantic - Find by meaning (ONNX embeddings)
- suggest_patterns - Cross-project solutions
- pm_index_files - Index for semantic search$3
Epic tracking and project status
- query_backlog - List EPICs with filtering
- add_epic - Create new EPICs
- complete_epic - Mark EPICs done
- get_project_status - Project overview$3
Smart commits with auto-generated messages
- smart_commit - Conventional commit generation
- session_package - Package session for commit$3
Progressive research with citations
- research_progressive - Streaming research
- search_research - Search history$3
Export Claude.ai conversation history
- chrome_export_status - Check Chrome readiness
- chrome_export_setup - Setup instructions
- chrome_export_conversations - Export conversations$3
Interactive REPL and process management
- sys_start_process - Start with smart detection
- sys_interact_with_process - Send input
- sys_read_process_output - Read output
- sys_list_sessions - List active sessions
- sys_list_processes - List system processes
- sys_kill_process - Terminate process
- sys_force_terminate - Force terminate session$3
Background search with streaming
- sys_start_search - Start background search
- sys_get_more_search_results - Paginate results
- sys_stop_search - Stop search
- sys_list_searches - List active searches$3
Low-level file system operations
- sys_copy_path - Copy files/directories
- sys_delete_path - Delete files/directories
- sys_path_exists - Fast existence check
- sys_move_path - Move/rename
- sys_create_directory - Create directories$3
System configuration and introspection
- sys_get_config - Get KERNL configuration
- sys_set_config_value - Update configuration
- sys_get_usage_stats - Tool usage analytics
- sys_get_tool_info - Tool discovery$3
Automated validation and monitoring
- sys_run_tests - Run test suites
- sys_validate_tools - Validate tool definitions
- sys_check_health - System health check
- sys_benchmark - Performance benchmarks$3
Documentation and export
- sys_export_tools - Export tool registry (JSON)
- sys_generate_docs - Auto-generate docs
- sys_get_version - Version information$3
Revolutionary desktop control
- sys_edit_block - Surgical file editing
- sys_write_pdf - PDF generation/modification
- sys_copy_file_user_to_claude - Bridge filesystems$3
Long-running operations with progress tracking
- Job creation, monitoring, and management
- Progress tracking and status updates
- Background indexing and research
- Session state persistenceTotal: 75 tools across 17 categories
---
π Quick Start
$3
- Node.js 18+ (for MCP server)
- Claude Desktop app
- Windows, macOS, or Linux$3
#### Option 1: NPM (Recommended)
`bash
npm install -g kernl-mcp
`#### Option 2: From Source
`bash
git clone https://github.com/yourusername/kernl-mcp.git
cd kernl-mcp
npm install
npm run build
`$3
Add to your Claude Desktop configuration:
Windows:
%APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json`json
{
"mcpServers": {
"kernl": {
"command": "node",
"args": [
"C:/Users/YourName/AppData/Roaming/npm/node_modules/kernl-mcp/dist/index.js"
]
}
}
}
`For source installation, use your local path:
`json
{
"mcpServers": {
"kernl": {
"command": "node",
"args": [
"D:/Project Mind/kernl-mcp/dist/index.js"
]
}
}
}
`$3
1. Restart Claude Desktop
2. Test connection:
`
Check if KERNL is connected
`Claude should confirm connection and show available tools.
3. Get version:
`
Use sys_get_version to show KERNL version
`Should return version 5.0.0 (V2.0).
---
π Core Workflows
$3
`typescript
// 1. Register your project
pm_register_project({
id: "my-app",
name: "My Application",
path: "C:/Projects/my-app"
})// 2. Index files for semantic search
pm_index_files({ project: "my-app" })
// 3. Check project status
get_project_status({ project: "my-app" })
`$3
`typescript
// At start of EVERY session
check_resume_needed({ project: "my-app" })
// β If resume needed, shows prompt// During work - checkpoint every 5-10 tool calls
auto_checkpoint({
project: "my-app",
operation: "Building feature X",
progress: 0.6,
currentStep: "Implementing Y",
decisions: ["Use approach Z"],
nextSteps: ["Add tests", "Update docs"],
activeFiles: ["src/feature.ts"]
})
// When task complete
mark_complete({
project: "my-app",
summary: "Feature X complete with tests"
})
`$3
`typescript
// Find files by meaning
search_semantic({
project: "my-app",
query: "database connection setup",
topN: 5
})// Get patterns from other projects
suggest_patterns({
currentProblem: "need connection pooling"
})
`$3
`typescript
// Start Python REPL for data analysis
sys_start_process({ command: "python3 -i", timeout_ms: 30000 })// Load data
sys_interact_with_process({
pid: 1234,
input: "import pandas as pd; df = pd.read_csv('data.csv')"
})
// Analyze
sys_interact_with_process({
pid: 1234,
input: "print(df.describe())"
})
// Read results
sys_read_process_output({ pid: 1234, timeout_ms: 5000 })
`$3
`typescript
// Generate complete tool documentation
sys_generate_docs({
format: 'markdown',
output: 'D:/docs/TOOLS.md',
includeExamples: true
})// Export tool registry
sys_export_tools({
format: 'full',
output: 'D:/tools.json'
})
// Check system health
sys_check_health({ quick: false })
`---
π― Use Cases
$3
Problem: Multi-hour refactoring exceeds Claude's timeoutSolution:
`typescript
// Claude automatically checkpoints every 5-10 operations
// If crash occurs, next session resumes exactly where left off
check_resume_needed({ project: "my-app" })
// β "Refactoring auth system (75% complete). Resume?"
`$3
Problem: Need to find "how did I solve X in other project?"Solution:
`typescript
suggest_patterns({
currentProblem: "implementing rate limiting"
})
// β Returns rate limiting patterns from all projects
`$3
Problem: Need to analyze CSV with pandasSolution:
`typescript
// Start Python REPL
sys_start_process({ command: "python3 -i" })// Interactive analysis
sys_interact_with_process({
pid: 1234,
input: "import pandas as pd; df = pd.read_csv('sales.csv')"
})
// β Full pandas workflow with persistent REPL
`$3
Problem: Need to work with files across filesystemsSolution:
`typescript
// Copy from user's computer to Claude's computer
sys_copy_file_user_to_claude({
path: "D:/user-data/large-file.xlsx"
})// Process in Claude's environment
// Copy results back via sys_copy_path
`$3
Problem: Need to validate system healthSolution:
`typescript
// Run comprehensive tests
sys_run_tests({ category: 'all', verbose: true })// Validate all tools
sys_validate_tools({ verbose: true })
// Check system health
sys_check_health({ quick: false })
// Run benchmarks
sys_benchmark({ operation: 'all', iterations: 100 })
`---
ποΈ Architecture
$3
#### Layer 1: Persistence
Foundation for crash recovery
- SQLite database for state
- Session management
- File indexing
- Pattern storage
- Research history
#### Layer 2: System Control
Complete desktop authority
- File operations
- Process management
- Search capabilities
- System integration
#### Layer 3: Intelligence
AI-powered features
- Semantic search (ONNX)
- Pattern recognition
- Smart commits
- Auto-documentation
$3
Database: SQLite with WAL mode
Embeddings: ONNX Runtime (local, no API calls)
Search: Background execution with pagination
Processes: Smart REPL detection and management
Testing: Comprehensive validation suite
---
π Performance
$3
`
Database Write: 400 ops/sec
Database Read: 800 ops/sec
Semantic Search: <500ms (10,000 files)
File Operations: <100ms
Process Launch: <50ms
Health Check: <20ms (cached)
`$3
- Projects: 50+ simultaneous
- Files: 100,000+ per project
- Patterns: 1,000+ with clustering
- Processes: Unlimited concurrent
- Search Results: Streaming pagination---
π§ͺ Testing
`bash
Run all tests
npm testRun test suite via tool
sys_run_tests({ category: 'all', verbose: true })Validate tool definitions
sys_validate_tools({ verbose: true })Check system health
sys_check_health({ quick: false })Run performance benchmarks
sys_benchmark({ operation: 'all', iterations: 100 })
`$3
- smoke - Quick validation (2 tests)
- database - SQLite operations
- filesystem - File operations
- tools - Tool handlers
- config - Configuration
- integration - End-to-end---
π§ Configuration
$3
`typescript
{
fileScanning: {
enabled: true,
mode: "auto", // "manual" | "auto" | "watcher"
excludes: ["/node_modules/", "/.git/"]
},
git: {
enabled: true,
autoCommit: false
},
features: {
semanticSearch: true,
crashRecovery: true,
crossProjectLearning: true
},
limits: {
maxFileSize: 10485760, // 10MB
maxSearchResults: 100
}
}
`$3
`typescript
// Get current config
sys_get_config()// Update config
sys_set_config_value({
key: 'features.semanticSearch',
value: true
})
// Get usage statistics
sys_get_usage_stats()
`---
π Documentation
$3
- V2_COMPLETE.md - Complete V2.0 overview (824 lines)
- TOOL_REFERENCE.md - All 75 tools with examples
- CHANGELOG.md - Version history
- Phase Completion Docs - Detailed phase documentation$3
Use sys_generate_docs to create:
- Markdown documentation
- HTML documentation
- JSON tool registry export---
π Troubleshooting
$3
Problem: Claude doesn't see KERNL toolsSolutions:
1. Verify Node.js:
node --version (need 18+)
2. Check config path in claude_desktop_config.json
3. Rebuild: npm run build
4. Check logs: %APPDATA%\Claude\logs\mcp.log
5. Restart Claude Desktop completely$3
Problem: check_resume_needed returns falseSolutions:
1. Verify checkpoint was saved: Check database
2. Ensure mark_complete wasn't called early
3. Check database path:
sys_get_config()$3
Problem: Slow semantic searchSolutions:
1. Check index status:
pm_index_status({ project })
2. Reindex: pm_index_files({ project, reindex: true })
3. Run benchmark: sys_benchmark({ operation: 'all' })
4. Check health: sys_check_health()---
πΊοΈ Roadmap
$3
- β
75 tools across 17 categories
- β
100% Desktop Commander parity
- β
Self-documenting system
- β
Comprehensive testing
- β
Revolutionary features$3
- [ ] Web UI for project management
- [ ] Real-time file watching
- [ ] Enhanced pattern visualization
- [ ] Additional format support$3
- [ ] Multi-platform support (ChatGPT, Gemini)
- [ ] Cloud sync for session state
- [ ] Team collaboration features
- [ ] Advanced analytics$3
- [ ] Distributed pattern learning
- [ ] Enterprise features (SSO, audit)
- [ ] Advanced security
- [ ] Plugin ecosystem---
π€ Contributing
We welcome contributions! Areas of interest:
- Additional file format support
- New intelligence features
- Performance optimizations
- Platform integrations
- Documentation improvements
See CONTRIBUTING.md for guidelines.
---
π License
MIT License - see LICENSE
---
π Acknowledgments
Built with:
- Model Context Protocol - AI integration framework
- TypeScript - Type-safe development
- SQLite - Embedded database
- ONNX Runtime - Local AI inference
Inspired by:
- Desktop Commander - System control patterns
- The need for truly persistent AI intelligence
- Developers who believe AI should remember
---
π Support
- Documentation: docs/
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Tool Reference: TOOL_REFERENCE.md
---
π Star the Project
If KERNL helps you, consider starring the repo! β
---
KERNL V2.0 - Transforming AI from stateless to persistent intelligence
Made with β€οΈ by developers who refuse to accept the 8-minute death
`
From: Stateless AI Assistant
To: Persistent Intelligence Layer
Status: COMPLETE β
``