대부분의 AI 어시스턴트(AI assistants)는 당신에게 자신들에게로 이동할 것을 요구합니다. 새로운 앱, 새로운 구독, 새로운 인터페이스 말이죠. 당신의 대화는 그들의 클라우드(cloud)에 저장되고, 당신의 통합(integrations)은 그들의 스토어를 거치며, 결제를 중단하는 순간 그 모든 것이 사라집니다.

저는 다른 것을 원했습니다. 내 머신(machine)에서 실행되며, 내가 이미 사용 중인 모든 메시징 플랫폼(messaging platform)에 연결되고, 내가 말한 모든 것을 기억하며, 요청을 적절한 모델(model)로 자동으로 라우팅(routing)하고, 내가 선택하지 않은 곳으로는 절대 내 데이터를 보내지 않는 단 하나의 에이전트(agent) 말입니다.

그것이 바로 NeuralCleave입니다.

GitHub: TheAmitChandra/NeuralCleave

Install: pip install neuralcleave

Docs: docs.neuralcleave.com

Website: neuralcleave.com

이것은 무엇인가

NeuralCleave는 Python으로 작성된 **로컬 우선 AI 어시스턴트 게이트웨이 (local-first AI assistant gateway)**입니다. 당신의 머신(machine)(또는 작은 VPS)에서 실행하고, Telegram/Discord/Slack/WhatsApp을 여기에 연결하면, 그 순간부터 해당 플랫폼 중 어느 곳에 보내는 메시지라도 동일한 에이전트(agent)에 도달하게 됩니다. 동일한 메모리(memory), 동일한 도구(tools), 그리고 동일한 페르소나(personality)를 가진 에이전트 말이죠.

v2.1.0의 주요 수치:

문제점: 파편화된 AI

오늘날 AI를 진지하게 사용하고 있다면, 아마 다음과 같은 상황일 것입니다:

• 일반적인 질문을 위해 브라우저 탭에 ChatGPT를 열어둠
• 글쓰기와 추론(reasoning)을 위해 다른 탭에 Claude를 열어둠
• 한 번 설정하고 잊어버린 Telegram 봇
• 당신의 서버가 사용하는 Discord 봇
• 개인정보 보호가 중요할 때 로컬에서 실행 중인 Ollama

이 중 어느 것도 서로 대화하지 않습니다. 어느 것도 당신이 어제 다른 AI에게 말했던 내용을 기억하지 못합니다. 당신은

`plaintext Channel Adapter (채널 어댑터) ↓ AgentRuntime (에이전트 런타임) ↓ ModelRouter (모델 라우터: 이 작업 유형에 적합한 LLM 선택) ↓ 3-Tier Memory (3계층 메모리: 컨텍스트 읽기 및 쓰기) ↓ ReflectionEngine (성찰 엔진: 응답 점수 산정, 품질이 임계값 미만일 경우 재생성) ↓ Channel Adapter (채널 어댑터: 원래 플랫폼으로 답장 전송) `

이 게이트웨이는 FastAPI 애플리케이션입니다. 모든 통합은 비동기(async)로 처리되며, 모든 LLM 호출은 스트리밍(streamed) 방식으로 이루어집니다. 전체 시스템은 단일 Python 프로세스에서 실행되며, 메모리 계층을 위해 선택적으로 Redis 및 Qdrant를 사용할 수 있습니다.

시작하기

`bash pip install neuralcleave neuralcleave init # ~/.neuralcleave/config.toml 작성 neuralcleave start # localhost:7432에서 게이트웨이 실행 `

이것으로 끝입니다. 게이트웨이는 http://localhost:7432/app에서 WebSocket 채팅 UI를 제공하며, /api/v1/에서 전체 REST API를 제공하며 시작됩니다.

32개의 채널 어댑터 (Channel Adapters)

게이트웨이의 핵심은 모든 플랫폼이 동일한 에이전트로 라우팅된다는 점입니다. 32개 전체 목록은 다음과 같습니다:

주류 (Mainstream)
Telegram · Discord · WhatsApp · Slack · Microsoft Teams · Email (IMAP/SMTP)

소셜 및 연합형 (Social & federated)
Bluesky (AT Protocol) · Mastodon · Nostr (NIP-04 암호화된 DM) · Twitter/X (webhook을 통해)

아시아 플랫폼 (Asian platforms)
WeChat Work · LINE · Zalo · QQ Bot · Feishu / Lark · Doubao

워크플레이스 (Workplace)
Mattermost · Rocket.Chat · Google Chat · Nextcloud Talk · Synology Chat

개발 / 인프라 (Dev / infrastructure)
IRC · XMPP · Matrix · Generic Webhook · WebSocket

음성 및 전화 (Voice & telephony)
Twilio Voice (TwiML을 통한 멀티턴 음성) · SMS (Twilio)

엔터테인먼트 (Entertainment)
Twitch (IRCv3) · Viber · iMessage (BlueBubbles를 통해)

P2P
Tlon / Urbit

각 어댑터는 인증(authentication), 웹훅 검증 (HMAC-SHA256, Ed25519, JWT — 플랫폼이 요구하는 방식에 따라), 그리고 플랫폼의 네이티브 이벤트 형식을 NeuralCleave의 내부 Message 모델로 매핑하는 작업을 처리합니다. 설정 파일에서 이를 활성화할 수 있습니다:

`toml
[channels.telegram]
enabled = true
bot_token = "ENV:TELEGRAM_BOT_TOKEN"

[channels.discord]
enabled = true
bot_token = "ENV:DISCORD_BOT_TOKEN"
`

[channels.slack]
enabled = true
bot_token = "ENV:SLACK_BOT_TOKEN"
signing_secret = "ENV:SLACK_SIGNING_SECRET"

모든 비밀 값은 ENV:VAR_NAME 해석을 지원합니다 — 민감한 정보는 설정 파일에 저장되지 않습니다.

작업 인식 라우팅 (Task-Aware Routing)을 지원하는 13개의 LLM 제공업체

NeuralCleave는 단순히 하나의 모델을 선택하여 모든 작업에 호출하지 않습니다. ModelRouter는 들어오는 각 요청을 10가지 작업 유형 (task types) 중 하나로 분류하고 최적의 제공업체로 라우팅합니다:

Global: Anthropic · OpenAI · Google Gemini · Mistral AI · xAI Grok · Cohere

Local/open: Ollama (모든 GGUF 모델)

Asia: DeepSeek · Moonshot / Kimi · Zhipu GLM · Alibaba Qwen · Baidu ERNIE · ByteDance Doubao

요청별로 라우팅을 재정의하거나, 모든 데이터를 Ollama로 강제하여 데이터가 기기를 절대 떠나지 않도록 하는 **개인정보 보호 모드 (privacy mode)**를 설정할 수 있습니다.

[models]
default_provider = "anthropic"
privacy_mode = false

anthropic_api_key = "ENV:ANTHROPIC_API_KEY"
openai_api_key = "ENV:OPENAI_API_KEY"
deepseek_api_key = "ENV:DEEPSEEK_API_KEY"
ollama_base_url = "http://localhost:11434"

3계층 메모리 (3-Tier Memory)

이것은 제가 가장 자랑스럽게 생각하는 부분 중 하나입니다. 대부분의 AI 어시스턴트는 메모리가 없거나, 평면적인 벡터 저장소 (vector store), 또는 비용이 많이 드는 클라우드 동기화를 사용합니다. NeuralCleave는 3계층 캐스케이드 (cascade)를 사용합니다:

Hot tier → Redis (최근 세션, TTL 기반, 1밀리초 미만)
Vector tier → Qdrant (의미론적 ANN 검색, 코사인 유사도)
Long-term → SQLite (중요도 점수 기반, 영구적, 오프라인 가능)

새 메시지가 도착하면:

1. Hot tier를 먼저 확인합니다 — 최근 컨텍스트가 1ms 미만으로 로드됩니다.
2. 관련 있는 장기 기억을 찾기 위해 Qdrant를 대상으로 의미론적 검색 (semantic search)을 실행합니다.
3. 결합된 컨텍스트가 LLM 프롬프트 앞에 추가됩니다.
4. 응답 후, 중요한 사실들을 추출하여 세 계층 모두에 다시 기록합니다.

Redis와 Qdrant는 **선택 사항 (optional)**입니다. 해당 도구들이 없더라도 SQLite만으로 게이트웨이를 실행할 수 있으며, 이 경우 최신성/의미론적 (semantic) 기능만 다소 감소합니다.

메모리는 에이전트 노드별 (멀티 에이전트 설정을 위해) 및 채널별로 네임스페이스 (namespaced)가 지정되어 있어, 사용자가 원하지 않는 한 Telegram 대화 내용이 Discord 컨텍스트를 오염시키지 않습니다.

ReflectionEngine: 자동 품질 관리

모든 응답은 사용자에게 도달하기 전에 점수가 매겨집니다. ReflectionEngine은 다음 네 가지 차원을 0–100 척도로 평가합니다:

• 관련성 (Relevance) — 질문에 실제로 답변했는가?
• 완전성 (Completeness) — 명백히 누락된 내용이 있는가?
• 정확성 (Accuracy) — 메모리에 있는 알려진 사실과 모순되는가?
• 톤 (Tone) — 요청된 페르소나 (persona)와 일치하는가?

가중치 적용 점수가 설정 가능한 임계값 (threshold) 미만으로 떨어지면, 해당 응답은 폐기되고 실패 원인을 포함하여 개선된 프롬프트로 한 번 다시 생성됩니다. 사용자는 통과한 응답만을 보게 됩니다.

`toml [reflection] enabled = true threshold = 72 # 0–100; 이 점수 미만의 응답은 다시 생성됩니다 `

이를 통해 게으른 답변("실시간 데이터에 접근할 수 없지만...")이나 환각 (hallucination)이 섞인 자신만만한 오답이 사용자의 편지함에 도달하기 전에 잡아낼 수 있습니다.

음성 파이프라인 (Voice Pipeline)

음성 스택은 기본적으로 완전히 로컬 (local)로 작동합니다:

• STT (음성-텍스트 변환): OpenAI Whisper (tiny부터 large-v3까지), 기기 내에서 실행
• TTS (텍스트-음성 변환): 3단계 캐스케이드 (cascade) — ElevenLabs (최고 품질) → Kokoro (오프라인, 양호한 품질) → pyttsx3 (오프라인, 항상 사용 가능)
• 웨이크 워드 (Wake word): OpenWakeWord — 항상 켜져 있는 감지, CPU 전용
• 음성 복제 (Voice cloning): API 키가 있는 경우 ElevenLabs 음성 복제 API 사용

ContinuousVoiceListener는 VAD (음성 활동 감지, RMS 에너지) 루프를 실행하고, 발화를 감지하며, Whisper로 로컬에서 전사(transcribe)하고, 텍스트를 에이전트 파이프라인을 통해 라우팅한 뒤 응답을 말하는 비동기 (async) 프로세스입니다. 이 과정 중 어떤 것에도 클라우드 의존성이 필요하지 않습니다.

`bash neuralcleave voice listen # 항상 켜져 있는 음성 모드 시작 neuralcleave voice speak "Hello from NeuralCleave" `

플러그인 SDK (Plugin SDK)

NeuralCleave는 플러그인 탐색을 위해 PEP 451 entry-points를 사용합니다. 이는 pip 자체가 사용하는 것과 동일한 메커니즘입니다. Python 패키지를 작성하고 이를 neuralcleave.plugins entry-point 그룹 아래에 등록하면, 게이트웨이가 이를 자동으로 탐색하고 로드합니다.

# my_plugin/plugin.py

from neuralcleave_sdk import Plugin, Tool, ToolResult

class WeatherTool(Tool):  
    name = "get_weather"  
    description = "도시의 현재 날씨를 가져옵니다"  
    parameters = {  
        "city": {"type": "string", "description": "도시 이름"}  
    }

    async def run(self, city: str) -> ToolResult:
        # ... 날씨 정보 가져오기 ...
        return ToolResult(content=f"{city}의 현재 기온은 22°C입니다")

class WeatherPlugin(Plugin):  
    name = "weather"  
    version = "1.0.0"  
    tools = [WeatherTool]

    async def on_load(self) -> None:
        print("Weather plugin loaded")

# pyproject.toml

[project.entry-points."neuralcleave.plugins"]
weather = "my_plugin.plugin:WeatherPlugin"

pip install .
nevercleave plugins list # → weather 1.0.0 ✓

플러그인은 **핫 리로드 (hot-reload)**를 지원하므로 게이트웨이를 재시작할 필요가 없습니다.

naturalcleave plugins reload weather

세 가지 공식 플러그인이 프로젝트와 함께 제공됩니다: neuralcleave-github, neuralcleave-notion, 그리고 neuralcleave-google-calendar. 모두 PyPI에 등록되어 있습니다.

Hub Marketplace (Hub 마켓플레이스)

Hub는 NeuralCleave의 내장 플러그인 마켓플레이스입니다. 모든 패키지는 설치 전에 **이중 패스 보안 스캔 (dual-pass security scan)**을 거칩니다:

1. AST walk — 13개의 위험한 임포트(subprocess, ctypes, socket 등 악의적으로 사용될 경우)를 차단합니다.
2. Regex scan (정규식 스캔) — 14개의 위험한 패턴(eval(, exec(, __import__, 난독화된 base64 호출 등)을 스캔합니다.

스캔을 통과하면 플러그인은 설치되며, SHA-256 체크섬(checksum)으로 검증된 후 핫 로드됩니다:

naturalcleave hub search weather
naturalcleave hub install neuralcleave-weather
naturalcleave hub scan neuralcleave-weather # 설치 없이 감사 수행

Multi-Agent Orchestrator (멀티 에이전트 오케스트레이터)

더 복잡한 설정을 위해, 각각 고유한 모델, 라우팅 규칙 (routing rules), 메모리 네임스페이스 (memory namespace), 그리고 동시성 제한 (concurrency limit)을 가진 **이름이 지정된 에이전트 노드 (named agent nodes)**를 정의할 수 있습니다:

[[orchestrator.nodes]]  
name = "researcher"  
model_override = "claude-opus-4-8"  
task_types = ["complex_reasoning", "summarization"]  
channel_patterns = ["telegram", "discord"]  
priority = 10

[[orchestrator.nodes]]  
name = "coder"  
model_override = "deepseek-coder"  
task_types = ["code_generation", "code_review"]
priority = 8

[[orchestrator.nodes]]  
name = "fast"  
model_override = "ollama/llama3"  
task_types = ["general", "cheap_inference"]
priority = 5  

AgentOrchestrator는 필터(filter) → 우선순위(priority) → 라운드 로빈(round-robin) 파이프라인을 실행합니다. 각 노드는 자체적인 LRU 메모리 네임스페이스를 가지므로, coder 에이전트의 컨텍스트 (context)가 researcher 에이전트의 메모리로 유출되지 않습니다.

Live Canvas (라이브 캔버스)

Canvas는 실시간 시각적 출력 스트림입니다. 에이전트는 텍스트, 마크다운 (markdown), 코드 (code), 표 (tables), 차트 (charts), HTML 등 구조화된 블록을 렌더링하여 연결된 모든 시청자가 즉시 볼 수 있는 라이브 WebSocket 피드로 전송할 수 있습니다:

neuralcleave canvas open # 브라우저에서 http://localhost:7432/canvas를 엽니다

블록 유형: text · markdown · code · table · chart (Canvas API를 통한 bar/line/pie) · image · html

Canvas는 에이전트에게 복잡한 문제를 추론하도록 요청할 때 특히 유용합니다. 에이전트가 텍스트의 벽을 나열하는 대신, 자신의 사고 과정을 구조화된 블록으로 스트리밍할 수 있기 때문입니다.

Prometheus Observability (Prometheus 관측성)

Prometheus 노출 형식 (Prometheus exposition format)으로 GET /api/v1/metrics에서 제공되는 13개의 내장 메트릭 (metrics):

prometheus   neuralcleave_requests_total{channel,status}   neuralcleave_llm_calls_total{provider,model,status}   neuralcleave_llm_latency_seconds{provider,model}   neuralcleave_memory_reads_total{tier}   neuralcleave_memory_writes_total{tier}   neuralcleave_reflection_scores{result}   neuralcleave_plugin_calls_total{plugin,tool,status}   neuralcleave_active_connections{channel}   neuralcleave_websocket_messages_total   neuralcleave_channel_errors_total{channel,error_type}   neuralcleave_uptime_seconds   neuralcleave_memory_entries_total{tier}   neuralcleave_hub_installs_total{package,status}   ``` 

저장소에는 미리 구축된 Grafana 대시보드 JSON이 포함되어 있습니다. 이를 모든 Grafana 인스턴스에 연결하면 요청률(request rates), 지연 시간 히스토그램(latency histograms), 오류 분석(error breakdowns), 메모리 계층 활용도(memory tier utilization)를 얻을 수 있으며, 이 모든 것이 `docker-compose up`으로 가능합니다.

## 데스크톱 앱 + PWA

세 가지 플랫폼용 **Tauri v2** 데스크톱 앱이 제공됩니다: