Skip to main content

​
Overview

NeuralCleave is a Python process (the gateway) with an optional Next.js dashboard. The gateway owns the full pipeline from incoming message to outgoing reply.

​
Components

​
Gateway (Python / FastAPI)

The gateway exposes a REST API at http://localhost:7432/api/v1 and a WebSocket at ws://localhost:7432/ws. It orchestrates:
  • Channel adapters — one background task per enabled channel
  • Session manager — per-session state, history, and memory retrieval
  • LLM provider — interchangeable adapter (OpenAI, Anthropic, Ollama, …)
  • Tool chain runner — executes up to N skill/tool calls per pipeline run
  • Voice pipeline — STT → LLM → TTS, all in-process

​
Memory

Vector-embedded conversation store. Uses sentence-transformers for embedding and cosine similarity (or FAISS) for retrieval. Stored in a local SQLite file.

​
Skills

Python files loaded from ~/.neuralcleave/skills/. Hot-reloaded without restart. Can be written by the agent itself.

​
MCP server

An optional Model Context Protocol stdio server (neuralcleave.mcp.server) exposes all registered tools over JSON-RPC 2.0, allowing external clients (Claude Desktop, Cursor, etc.) to call NeuralCleave tools.

​
Exec approval

A gate that intercepts ShellTool calls and requires explicit user approval via POST /api/v1/approvals/{id}/approve before execution. Prevents unattended destructive shell commands.

​
Data flow — single message

​
Configuration files

​
Process model

NeuralCleave runs as a single Python process. Each channel adapter is an asyncio background task. The LLM provider call is await-based, so the gateway handles concurrent conversations without threads.

​
Tauri desktop app

The dashboard can be packaged as a Tauri desktop app (Windows/macOS/Linux). The Tauri shell spawns the Python gateway as a sidecar process and serves the Next.js frontend from a local file server.