NeuralCleave Documentation
NeuralCleave is a local-first personal AI assistant gateway. One agent, connected to 32 messaging platforms simultaneously, with 3-tier memory, task-aware LLM routing, voice, and a typed plugin SDK.
32
Channel adapters
13
LLM providers
41
REST endpoints
5,064
Tests passing
v2.1
Current version
Start here
Getting Started
Install NeuralCleave, run
neuralcleave init, and have your first agent answering messages in under a minute.→
Architecture
How the gateway, agent runtime, model router, reflection engine, and memory pipeline fit together.
→
Channels
32 production-ready adapters — Telegram, Discord, WhatsApp, Slack, Teams, LINE, Bluesky, Nostr, Twitch, and 23 more.
→
LLM Providers
13 providers — Anthropic, OpenAI, Gemini, DeepSeek, Ollama, Mistral, xAI, Cohere, Moonshot, Zhipu, Qwen, ERNIE, Doubao.
→
REST API
41 documented endpoints — chat, memory, plugins, hub, orchestrator, canvas, voice, settings. Full OpenAPI via FastAPI.
→
Plugin SDK
Write typed plugins with
neuralcleave-sdk. PEP 451 entry-points, hot-reload, NeuralCleave Hub marketplace.→
Memory System
Redis (hot, TTL) → Qdrant (vector ANN) → SQLite (long-term). Session compaction, archiver, per-node isolation.
→
Voice
Whisper STT, 3-tier TTS (ElevenLabs → Kokoro → pyttsx3), OpenWakeWord, voice cloning, continuous listener.
→
Observability
13 Prometheus metrics, structured JSON logging with ContextLogger. Prometheus-compatible /api/v1/metrics endpoint.
→
Deployment
Docker, docker-compose with Redis + Qdrant, Railway, Render.
neuralcleave cloud generate writes all manifests.→
Configuration
Complete TOML reference — gateway, models, memory, voice, channels, scheduler.
ENV: secret resolution.→
Testing
5,064 tests. Running the suite, test coverage by module, writing new tests for channels and plugins.
→
Quick install
bash
# Linux / macOS
curl -fsSL https://neuralcleave.com/install.sh | bash
# Windows (PowerShell)
iwr -useb https://neuralcleave.com/install.ps1 | iex
# Or via pip directly (Python 3.12+ required)
pip install neuralcleave
neuralcleave init
neuralcleave startPython 3.12+ required. Redis and Qdrant are optional — the gateway runs without them but with reduced memory capability. See requirements.
Repository layout
| Path | Contents |
|---|---|
neuralcleave/ | Core gateway package — gateway, channels, memory, LLM router, voice, tools, canvas, hub, orchestrator, PWA |
neuralcleave-sdk/ | Plugin SDK — Plugin, Tool, ChannelAdapter ABCs; PEP 451 entry-point registration |
examples/plugins/ | Reference plugins: neuralcleave-github, neuralcleave-notion, neuralcleave-google-calendar |
frontend/ | Tauri 2.x desktop app (Rust sidecar + WebView) |
backend/ | Backend configuration and compose for standalone deploy |
scripts/ | install.sh / install.ps1 one-liner installers; bundle_backend.ps1 PyInstaller pipeline |
tests/ | 5,064 tests — unit, integration, channel, API, frontend-contract |
.github/workflows/ | CI (lint+test, SDK, plugins, Docker) + docs deploy |