KERNL MCP - Persistent Intelligence Layer

Transform AI assistants from stateless to persistent, project-aware intelligence systems

![License: MIT](LICENSE)
![Version](package.json)
![V2.0](docs/V2_COMPLETE.md)
![Tools](docs/TOOL_REFERENCE.md)

Formerly "Project Mind" — Now KERNL: The authoritative system control layer for AI

---

🎯 What is KERNL?

KERNL is an MCP (Model Context Protocol) server that solves three fundamental problems with AI assistants:

$3

1. The 8-Minute Death 💀 - Operations >8 minutes cause crashes and total context loss
2. The Bootstrap Tax 🔄 - Starting fresh every session wastes time re-explaining context
3. Isolated Learning 🏝️ - Knowledge doesn't transfer between projects

$3

KERNL V2.0 - A persistent intelligence layer with 75 specialized tools:

✅ 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

---

⭐ V2.0 Revolutionary Features

$3

No more 8-minute death!
``

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 persistence
Total: 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.jsonmacOS:~/Library/Application Support/Claude/claude_desktop_config.jsonLinux:~/.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 timeout

Solution:`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 pandas

Solution:`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 filesystems

Solution:`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 health

Solution:`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 test
Run 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 tools

Solutions: 1. Verify Node.js:node --version(need 18+) 2. Check config path in claude_desktop_config.json 3. Rebuild:npm run build4. Check logs:%APPDATA%\Claude\logs\mcp.log5. Restart Claude Desktop completely

`$3`


Problem: check_resume_needed returns false

Solutions: 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 search

Solutions: 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 ✅``

KERNL MCP - Persistent Intelligence Layer

Transform AI assistants from stateless to persistent, project-aware intelligence systems

![License: MIT](LICENSE)
![Version](package.json)
![V2.0](docs/V2_COMPLETE.md)
![Tools](docs/TOOL_REFERENCE.md)

Formerly "Project Mind" — Now KERNL: The authoritative system control layer for AI

---

🎯 What is KERNL?

KERNL is an MCP (Model Context Protocol) server that solves three fundamental problems with AI assistants:

$3

KERNL V2.0 - A persistent intelligence layer with 75 specialized tools:

---

⭐ V2.0 Revolutionary Features

$3

No more 8-minute death!
``

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 persistence
Total: 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.jsonmacOS:~/Library/Application Support/Claude/claude_desktop_config.jsonLinux:~/.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 timeout

`$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 pandas

Solution:`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 filesystems

Solution:`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 health

Solution:`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`

---

`📊 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 test
Run 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 tools

`$3`


Problem: check_resume_needed returns false

Solutions: 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 search

---

`🗺️ 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 ✅``