convez.ai
MCP ServerAutomaçãoAvançado
Noumenon-ai

Nexus Core

Noumenon-ai/nexus-core

Framework agentic auto-hospedável com orquestração LLM e gate de segurança

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework de assistente pessoal auto-hospedável com orquestração multi-provider LLM, loop agentic com ferramentas MCP, modelo de segurança com aprovação explícita e 10 servidores MCP pré-integrados. Roda localmente sem dependência de clouds terceirizadas, ideal para automação pessoal robusta.

Instalação

$npx convez-ai Noumenon-ai/nexus-core

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.1.0
Issues abertas
0
Contribuidores
2

Casos de uso

  • Assistente pessoal com controle total dos dados
  • Automação de tarefas do dia-a-dia (reminders, emails, calendário)
  • Integração agentic com múltiplos provedores LLM
  • Prototipagem de fluxos conversacionais com aprovação de ações destrutivas

Veredito

Nexus Core é um projeto sólido e bem-arquitetado para quem precisa de um assistente agentic privado e confiável. A separação clara entre orquestração LLM, segurança e integração MCP, aliada aos hooks de produção (secret scanning, auditoria), mostra maturidade técnica; cabe melhor em automação pessoal sofisticada que em uso genérico.

README

A tradução para o português deste README ainda está na fila.

Nexus Core

A self-hostable, multi-MCP personal-assistant framework with multi-provider LLM orchestration, a real safety model, and a production-grade test suite.

Nexus Core is the engine behind a Telegram-based personal assistant: it takes a message (text or voice), routes it through an LLM, lets the model call tools exposed by a fleet of Model Context Protocol servers, gates anything destructive behind explicit human approval, and replies. It is designed to run on your own machine against your own accounts — no third-party assistant cloud in the middle.

This is a clean, reference extraction: all personal data, credentials, and proprietary business logic have been removed. Bring your own keys and accounts.

Nexus Core example interaction: a reminder, a self-correction, and the approval gate on a destructive action

Illustrative interaction — showing in-message self-correction and the approval gate that holds destructive actions.


What's interesting here

  • Multi-provider LLM orchestration (services/brain_router.py) — a single entry point that routes a turn to a local Claude/Codex CLI subprocess (with the MCP servers loaded) or a local Ollama model, with circuit breakers, retries, and graceful fallback to a deterministic responder when every provider is down.
  • An agentic tool loop (pipeline/tool_dispatcher.py) — the model proposes tool calls, the dispatcher executes them, feeds results back, and iterates to a final reply, with dedup, thread binding, and a hard iteration cap.
  • A real safety model — a destructive-intent classifier plus an approval-gate flow: anything that deletes, sends, or overwrites is held until the user approves it in-chat. Cross-user access is rejected; tool inputs are validated.
  • Conversational recovery + self-correction — interprets messy follow-ups ("actually make it Tuesday", "June 2 no June 4") and echoes the correction so a revision is never silently applied.
  • A fleet of MCP servers (mcp_servers/) — reminders & tasks, a knowledge store, filesystem access behind a security boundary, PDF tools, Google Calendar / Gmail / Contacts, a browser agent, and a capability-introspection server.
  • Production hardening built in — user-scoped data access, pre-commit secret scanning + pre-push test hooks, structured logging with secret redaction, and a documented data map.

Architecture

Telegram ─► pipeline/unified.py ─► auth gate ─► tool_dispatcher ─┐
                                                                 │  proposes tool calls
                                  brain_router (Claude / Ollama) ◄┘
                                       │
            ┌──────────────────────────┼───────────────────────────┐
            ▼                          ▼                            ▼
     MCP servers (mcp_servers/)   services/ (domain logic)   repositories/ (SQLAlchemy)
     reminders, knowledge,        reminder, task, memory,    users, reminders, tasks,
     filesystem, pdf, calendar,   approval, recovery,        memories, approvals,
     email, contacts, web, self   self-correction, voice     conversation, audit, cron

See docs/ARCHITECTURE.md for the full tour.

MCP servers

ServerPurpose
nexus_reminders_tasksReminders + tasks over the shared SQLite store
nexus_knowledgeLong-term key/value memory, decisions log, journal
nexus_utilsTime, math, units, cron management, and small utilities
nexus_filesystemRead/search/write files behind an allow-list + denylist
nexus_pdf_docsGenerate, manipulate, and fill PDF forms
nexus_calendarGoogle Calendar (OAuth, optional)
nexus_emailGmail read/search/draft/send (OAuth, optional)
nexus_contactsGoogle Contacts / People API (OAuth, optional)
nexus_webHeadless browser agent (Playwright, optional)
nexus_selfCapability introspection ("what can you access?")

Quick start

git clone https://github.com/Noumenon-ai/nexus-core.git
cd nexus-core
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# optional: local Whisper voice transcription (heavy — pulls torch);
# only needed for VOICE_INPUT_BACKEND=whisper_local
pip install -r requirements-voice.txt

cp .env.example .env          # fill in TELEGRAM_BOT_TOKEN + ALLOWED_TELEGRAM_IDS
./scripts/install-git-hooks.sh # optional: secret-scan + test gates

python -m pytest -q            # run the suite
python main.py                 # start the assistant

The Google, voice, and browser integrations are optional and key-gated — the core (reminders, tasks, knowledge, filesystem) runs with no third-party keys.

Configuration

All configuration is via environment variables — see .env.example for the full annotated list. Nothing is hardcoded; secrets live only in .env (gitignored) and never in the codebase.

Security

  • Data isolation: every query on a user-scoped table filters by a server-derived user_id; cross-user access is rejected.
  • Approval gate: destructive tool calls require explicit in-chat approval.
  • Secrets: .gitignore blocks every secret shape; a pre-commit hook scans staged diffs; logs are redacted.
  • Data map: docs/DATA_MAP.md lists what is stored, where, who can access it, and retention.

Testing

python -m pytest -q     # 1500+ tests, synthetic fixtures, no network or keys required

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados