neuroverse

📦Install from npm|🐙GitHub Repository

- Quick Start
- Why NeuroVerse?
- How It Works
- Multilingual Intelligence (Vani)
- Intent Extraction (Bodhi)
- Tiered Memory (Smriti)
- Safety Layer (Kavach)
- Multi-Model Router (Marga)
- Agent-to-Agent (Setu)
- MCP Tools
- REST API
- Configuration
- Testing
- Architecture
- Roadmap
- Contributing

git clone https://github.com/joshua400/neuroverse.git cd neuroverse python -m pip install -e ".[dev]"

💡Tip:If you installed via npm, the path isnode_modules/neuroverse/dist/index.js. If from source, use the absolute path to your cloned directory.

NeuroVerse is a standard MCP server (stdio). Add it to your host's config:

Cursor / VS Code Copilot / Claude Desktop (npm)

{ "mcpServers": { "neuroverse": { "command": "npx", "args": ["neuroverse"] } } }

{ "mcpServers": { "neuroverse": { "command": "python", "args": ["mcp/server.py"], "cwd": "/path/to/neuroverse" } } }

Add this to your agent's rules file (.md,.cursorrules, system prompt, etc.):

## NeuroVerse Integration - Use neuroverse_process to handle any user request — it auto-detects language, extracts intent, checks safety, and executes. - Use neuroverse_reason for complex tasks requiring analytical reasoning (powered by OpenRouter). - Use neuroverse_store / neuroverse_recall for persistent context across sessions. - Use neuroverse_execute for any potentially dangerous action — it will block destructive operations.

That's it. Two commands your agent needs to know:

Next session, your agent picks up exactly where it left off — like it never forgot.

- npm edition:Node.js 18+ (zero database deps — uses JSON files)
- Python edition:Python 3.10+ + PostgreSQL (for persistent memory)

NeuroVerse's safety layer runs atzero token cost— pure regex and rule matching, no LLM calls wasted:

Over 100 tool calls per session, that's50,000–200,000 tokens savedcompared to LLM-based safety.

User Input (any language) │ ┌────┴────┐ │ Vani │ ← Language detection + keyword normalisation │ (भाषा) │ Tamil/Hindi/Telugu → normalised internal format └────┬────┘ │ ┌────┴────┐ │ Bodhi │ ← LLM intent extraction + rule-based fallback │ (बोधि) │ Returns structured JSON with confidence └────┬────┘ │ ┌────┴────┐ │ Kavach │ ← 3-layer safety: blocklist → risk → LLM judge │ (कवच) │ Blocks dangerous actions at zero token cost └────┬────┘ │ ┌────┴────┐ │ Marga │ ← Routes to best model (OpenAI/Anthropic/Sarvam/Ollama) │ (मार्ग) │ Based on task type: multilingual/reasoning/local └────┬────┘ │ ┌────┴────┐ │ Smriti │ ← Stores/recalls from tiered memory │ (स्मृति) │ Short-term + Episodic + Semantic (PostgreSQL) └────┬────┘ │ Tool Execution + Response

The Problem:Every MCP server speaks only English. 70% of India code-switches daily.

"anna indha file ah csv convert pannu" ↓ "anna this file ah csv convert do" ← keyword normalisation (not full translation) ↓ Intent: convert_format { output_format: "csv" }

Input → Language Detect (langdetect) → Code-Switch Split → Keyword Normalise → Output

Key insight:Don't fully translate. Only normalise domain-critical keywords. The rest stays untouched — preserving context, tone, and nuance.

{ "languages": ["ta", "en"], "confidence": 0.92, "is_code_switched": true, "original_text": "anna indha file ah csv convert pannu", "normalized_text": "anna this file ah csv convert do" }

LLM-first. Rule-based fallback. Never fails.

LLM succeeds (confidence ≥ 0.5)? ├─ Yes → use LLM result └─ No → rule-based parser (deterministic)

# Prompt to LLM: "Extract structured intent from the following input. Return ONLY valid JSON: {intent, parameters, confidence}"

{ "intent": "convert_format", "parameters": { "input_format": "json", "output_format": "csv" }, "confidence": 0.87, "source": "rule" }

The key difference:the code decides— not the LLM. If the LLM fails, hallucinates, or returns garbage, the rule engine takes over. Deterministic. Reliable.

The Problem:Raw logs are useless. Storing everything wastes resources. No relevance scoring.

NeuroVerse's approach:Score → Filter → Compress → Store.

if importance_score >= 0.4: persist_to_database() # worth remembering else: skip() # noise

Only important memories survive. No bloat. No irrelevant recall.

❌ Bad: "The user asked about sales data three times in the last hour and seemed frustrated..." ✅ Good: { "intent": "sales_query", "frequency": 3, "sentiment": "frustrated" }

Structured JSON payloads, NOT raw text dumps. Compressed. Indexable. Queryable.

CREATE TABLE memory_records ( id TEXT PRIMARY KEY, user_id TEXT NOT NULL, tier TEXT NOT NULL, -- short_term | episodic | semantic intent TEXT NOT NULL, language TEXT DEFAULT 'en', data JSONB DEFAULT '{}', -- compressed structured payload importance REAL DEFAULT 0.5, created_at TIMESTAMPTZ DEFAULT NOW(), updated_at TIMESTAMPTZ DEFAULT NOW() ); -- Indexed: user_id, intent, tier

"The shield that never sleeps."

Agent calls tool → MCP Server receives request │ ┌───────────┴───────────┐ │ Layer 1: Blocklist │ ← regex + keywords, < 0.1ms └───────────┬───────────┘ │ pass ┌───────────┴───────────┐ │ Layer 2: Risk Score │ ← intent → risk classification └───────────┬───────────┘ │ pass ┌───────────┴───────────┐ │ Layer 3: LLM Judge │ ← optional model-based check └───────────┬───────────┘ │ pass Execute handler

Layer 1 — Rule-Based Blocklist (Zero Cost)

Runs inside the MCP server. Pure regex. No network. No tokens.

delete_all_data, drop_database, drop_table, system_shutdown, format_disk, rm -rf, truncate, shutdown, reboot, erase_all, destroy

DROP (DATABASE|TABLE|SCHEMA) DELETE FROM  TRUNCATE TABLE FORMAT [drive]: rm (-rf|--force)

If Layers 1–2 pass, optionally ask an LLM:"Is this safe?"

// LLM returns: { "safe": false, "reason": "This action would delete all user data." }

{ "allowed": false, "risk_level": "critical", "reason": "Blocked keyword detected: 'drop_database'", "blocked_by": "rule" }

Most AI safety: Agent → "rm -rf /" → Safety LLM → 2,000 tokens burned NeuroVerse: Agent → "rm -rf /" → regex match → BLOCKED (0 tokens, < 1ms)

# .env SAFETY_STRICT_MODE=true # Also blocks MEDIUM risk (unknown/send) SAFETY_STRICT_MODE=false # Only blocks HIGH and CRITICAL

def route_task(task): if task.type == "multilingual": return sarvam_model # Best for Indian languages elif task.type == "reasoning": return claude_or_openai # Best for complex analysis elif task.type == "local": return ollama # Free, on-device, private else: return best_available # Fallback chain

OpenRouter → Anthropic → OpenAI → Sarvam → Ollama (local, always available)

register_agent({ "agent_name": "report_agent", "endpoint": "http://localhost:8001/generate", "capabilities": ["generate_report", "sales_analysis"] })

{ "target_agent": "report_agent", "task": "generate_sales_report", "payload": { "quarter": "Q1", "year": 2026 } }

{ "success": false, "error": "Agent unreachable: ConnectError", "fallback": true }

── Session 1 (Agent Alpha, 2pm) ─────────────────────────── india_mcp_process_multilingual_input({ text: "anna indha sales data ah csv convert pannu", user_id: "alpha", execute: true }) → Language: Tamil+English (code-switched) → Intent: convert_format { output_format: "csv" } → Safety: ✅ allowed (LOW risk) → Execution: ✅ success india_mcp_store_memory({ user_id: "alpha", intent: "convert_format", tier: "episodic", data: { "file": "sales_q1.json", "output": "csv" }, importance_score: 0.8 }) ── Session 2 (Agent Beta, next day) ─────────────────────── india_mcp_recall_memory({ user_id: "alpha", intent: "convert_format", limit: 5 }) → "Agent Alpha converted sales_q1.json to CSV yesterday" → Beta picks up exactly where Alpha left off

python app/main.py # → http://localhost:8000/docs (Swagger UI)

# Database (PostgreSQL required for persistent memory) DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/neuroverse # AI Model API Keys (configure the ones you have) OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... SARVAM_API_KEY=... # Ollama (local, free) OLLAMA_BASE_URL=http://localhost:11434 # Safety SAFETY_STRICT_MODE=true # Block MEDIUM risk actions too # MCP Transport MCP_TRANSPORT=stdio # or streamable_http MCP_PORT=8000

tests/test_intent.py — 10 passed (rule-based + async + mock LLM + fallback) tests/test_language.py — 10 passed (keyword normalisation + detection + code-switch) tests/test_pipeline.py — 8 passed (full e2e: English, Tamil, Hindi, dangerous, edges) tests/test_safety.py — 12 passed (blocklist, regex, risk classification, pipeline) ============================= 40 passed in 0.87s ==============================

npm/ ├── src/ │ ├── core/ │ │ ├── language.ts # Vani — Language detection (zero deps) │ │ ├── intent.ts # Bodhi — Intent extraction (LLM + fallback) │ │ ├── memory.ts # Smriti — Tiered memory (JSON files) │ │ ├── safety.ts # Kavach — 3-layer safety engine │ │ └── router.ts # Marga — Multi-model AI router │ ├── services/ │ │ ├── executor.ts # Tool registry + retry engine │ │ └── agent-router.ts # Setu — Agent-to-Agent routing │ ├── types.ts # TypeScript interfaces & enums │ ├── constants.ts # Shared constants │ └── index.ts # MCP Server — 6 tools (McpServer + Zod) ├── package.json # npm publish config ├── tsconfig.json └── LICENSE # Apache-2.0

app/ ├── core/ │ ├── language.py # Vani — Language detection (langdetect) │ ├── intent.py # Bodhi — Intent extraction (LLM + fallback) │ ├── memory.py # Smriti — Tiered memory (PostgreSQL) │ ├── safety.py # Kavach — 3-layer safety engine │ └── router.py # Marga — Multi-model AI router ├── models/schemas.py # 12 Pydantic v2 models ├── services/ │ ├── executor.py # Tool registry + retry engine │ └── agent_router.py # Setu — Agent-to-Agent routing ├── config.py # Settings from environment └── main.py # FastAPI REST entry point mcp/server.py # MCP Server (FastMCP) — 6 tools tests/ # 40 tests (pytest)

# npm edition git clone https://github.com/joshua400/neuroverse.git cd neuroverse/npm npm install npm run build # Python edition cd neuroverse python -m pip install -e ".[dev]" python -m pytest tests/ -v # All 40 should pass

"I built NeuroVerse because it broke my heart watching agents forget everything every session — and not understand a word of Tamil."*

Joshua Ragiland M
✉️joshuaragiland@gmail.com
🌐Portfolio Website

Visual coordination protocol for AI agents — 22 MCP tools for glyph-based communication with 50-70% token savings, shared memory, governance, and on-chain attestation.