Neuroverse

🧠 NeuroVerse

📦 从 npm 安装 | 🐙 GitHub 仓库

你的 AI Agent 只会说英语。NeuroVerse 让它不再受限。
你的 AI Agent 会忘记一切。NeuroVerse 会记住。
你的 AI Agent 可能会做出危险操作。NeuroVerse 会阻止它。
你的 AI Agent 被限制为只能使用一个模型。NeuroVerse 会为它选择最佳模型。

为自主 AI Agent 提供多语言智能、记忆、安全防护和语音能力。

---

🚀 v4.1 新功能

• OpenRouter 推理：集成 stepfun/step-3.5-flash:free 模型，用于高性能分析任务。使用全新的 neuroverse_reason 工具进行深度思考。
• 推理 Token：实时追踪每个请求的推理 Token。
• 语音层（v2.0）：内置支持 Whisper STT 和 Coqui TTS。

---

🚀 什么是 NeuroVerse？

每次你在 Cursor、VS Code Copilot 或任何兼容 MCP 的 AI Agent 中开启新对话时，它都会从零开始——没有记忆、没有安全防护，也无法理解你的语言。NeuroVerse 是一款 MCP 服务，为你的 Agent 提供：

	功能	说明
🌐	多语言智能	理解泰米尔语、印地语、泰卢固语、卡纳达语、马拉雅拉姆语、孟加拉语与英语混合使用的表达。切换语言？毫无问题。
🎙️	语音层	通过 Whisper 实现 STT，通过 Coqui 实现 TTS。转录用户音频，并合成 Agent 的回复。
🧠	意图提取	优先使用大模型进行结构化意图提取，并提供确定性的规则回退机制。绝不错过任何命令。
💾	分层记忆	短期（会话）、情景（近期）、语义（长期事实）记忆——均带有重要性评分。
🛡️	三层安全防护（Kavach）	关键词阻止列表 → 意图风险分类器 → 大模型裁决器。在为时已晚之前阻止 DROP DATABASE。
🤖	多模型路由器（Marga）	OpenAI · Anthropic · Sarvam AI · Ollama · OpenRouter——自动为每项任务选择最佳模型。
🔗	Agent 间协作（Setu）	基于 REST+JSON 的 Agent 注册表，支持自动回退。Agent 调用 Agent，Agent 再调用 Agent。
⚡	全异步	FastAPI + asyncpg + httpx。亚毫秒级安全检查，不会阻塞。

⚡ NeuroVerse 是一个模块化智能层，而不是单体系统。按需接入，用不到的功能可以忽略。

---

目录

• 快速入门
• 为什么选择 NeuroVerse？
• 工作原理
• 多语言智能（Vani）
• 意图提取（Bodhi）
• 分层记忆（Smriti）
• 安全层（Kavach）
• 多模型路由器（Marga）
• Agent 间通信（Setu）
• MCP 工具
• REST API
• 配置
• 测试
• 架构
• 路线图
• 贡献

---

🚀 快速入门

1. 安装

选项 A：npm（推荐）——随处使用

npm install neuroverse

选项 B：从源码安装（Python）

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

💡 **提示：**如果通过 npm 安装，路径为 node_modules/neuroverse/dist/index.js。如果从源码安装，请使用克隆目录的绝对路径。

2. 将 NeuroVerse 添加到 MCP 配置

NeuroVerse 是标准的 MCP 服务（stdio）。将其添加到宿主的配置中：

Cursor / VS Code Copilot / Claude Desktop（npm）

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

从源码安装（Python）

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

3. 告诉 Agent 使用 NeuroVerse

将以下内容添加到 Agent 的规则文件（.md、.cursorrules、系统提示词等）：

## 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.

就这么简单。Agent 只需了解以下两条命令：

命令	使用时机	执行内容
neuroverse_process(text, user_id)	任意用户请求	检测语言、提取意图、进行安全检查并执行
neuroverse_store(user_id, intent, ...)	工作结束时	保存上下文，供下次会话使用

下次会话时，Agent 会准确地从上次中断处继续——仿佛从未忘记。

要求

• **npm 版本：**Node.js 18+（无需数据库依赖——使用 JSON 文件）
• **Python 版本：**Python 3.10+ + PostgreSQL（用于持久化记忆）

---

🤔 为什么选择 NeuroVerse？

不使用 NeuroVerse	使用 NeuroVerse
Agent 只懂英语	Agent 能理解泰米尔语、印地语、泰卢固语、卡纳达语及英语混用
"anna file ah csv convert pannu" → ❌ 错误	"anna file ah csv convert pannu" → ✅ 将文件转换为 CSV
每次会话都从零开始	Agent 会记住之前的操作——跨会话、跨 Agent
DROP DATABASE → 💀 数据全部丢失	DROP DATABASE → 🛡️ 在 < 1ms 内拦截，不消耗任何令牌
只能使用一家大模型提供商	自动为每项任务路由到最合适的模型
两个 Agent 就会一团混乱	Agent A 可无缝地将工作交接给 Agent B

令牌效率

NeuroVerse 的安全层运行时不消耗任何令牌——纯粹使用正则表达式和规则匹配，不会浪费大模型调用：

安全方式	每次检查的成本	延迟
基于大模型的安全检查	500–2,000 个令牌	1–5 秒
基于嵌入的安全检查	100–500 个令牌	200–500ms
NeuroVerse Kavach	0 个令牌	< 1ms

每次会话调用 100 次工具，相比基于大模型的安全检查，可节省 50,000–200,000 个令牌。

---

⚙️ 工作原理

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

---

🌐 多语言智能 — Vani

**问题：**每个 MCP 服务都只使用英语。印度有 70% 的人每天会切换语言。

"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

**关键洞见：**不要完全翻译。只规范化领域关键字，其余内容保持原样——从而保留上下文、语气和细微差别。

支持的语言

语言	映射的关键字	示例
🇮🇳 泰米尔语	pannu → do、maathru → change、anuppu → send	"file ah csv convert pannu"
🇮🇳 印地语	karo → do、banao → create、bhejo → send	"report banao sales ka"
🇮🇳 泰卢固语	cheyyi → do、pampu → send、chupinchu → show	"data chupinchu"
🇮🇳 卡纳达语	将在 v2 中支持	—
🇬🇧 英语	原样传递	"convert json to csv"

代码混用检测

{
  "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"
}

---

🧠 意图提取 — Bodhi

优先使用大模型，规则回退。永不失败。

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}"

基于规则的回退（7 种模式）

模式	意图	触发关键词
格式转换	convert_format	convert, csv, json, excel, pdf
摘要	summarize	summarise, summary, brief, tldr
报告生成	generate_report	report, generate report
删除	delete_data	delete, remove, drop, clean
数据查询	query_data	query, search, find, fetch, get
通信	send_message	send, share, email, notify
解释	explain	explain, describe, what is, how to

输出

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

关键区别在于：由代码做出决定，而非大模型。如果大模型失效、产生幻觉或返回垃圾内容，规则引擎就会接管。确定性强，可靠。

---

💾 分层记忆 — Smriti

问题： 原始日志毫无用处。存储所有内容会浪费资源，也没有相关性评分。

NeuroVerse 的做法： 评分 → 筛选 → 压缩 → 存储。

三个层级

层级	存储	生命周期	用途
短期	进程内 dict	当前会话	活跃上下文，每位用户最多保存 50 条
情景记忆	PostgreSQL	最近操作	Agent 最近执行的操作
语义记忆	PostgreSQL	长期事实	关于用户、项目和实体的持久知识

重要性评分

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

只有重要的记忆会保留下来。不会臃肿，也不会回忆无关内容。

上下文压缩

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

结构化 JSON 负载，而非原始文本转储。经过压缩，可编制索引，也可查询。

记忆架构（PostgreSQL）

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

---

🛡️ 安全层 — Kavach

“永不休眠的盾牌。”

三层防御，纵深防护

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

第 1 层 — 基于规则的阻止列表（零成本）

在 MCP 服务内部运行。纯正则表达式，无网络调用，不消耗令牌。

阻止的关键词：

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)

第 2 层 — 意图风险分类

风险级别	意图	操作
🟢 低	convert_format、summarize、generate_report、query_data、explain	✅ 允许
🟡 中	send_message、unknown	⚠️ 严格模式下阻止
🔴 高	delete_data	❌ 始终阻止
⛔ 严重	drop_database、system_shutdown	❌ 始终阻止

第 3 层 — 大模型安全判定器（可选）

如果通过第 1–2 层，可选择询问大模型：“这安全吗？”

// 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

---

🤖 多模型路由器 — Marga

问题： 受供应商锁定。所有任务都用同一个模型。费用过高。

NeuroVerse 的做法： 自动将每项任务路由到最合适的模型。

路由逻辑

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

支持的提供商

提供商	默认模型	最适合	成本
🇮🇳 Sarvam AI	sarvam-2b-v0.5	印度语言、多语言	低
🧩 OpenRouter	stepfun/step-3.5-flash:free	高性能推理	免费
🧠 Anthropic	claude-sonnet-4-20250514	推理、分析	中
🤖 OpenAI	gpt-4o	通用任务、代码	中
🦙 Ollama	llama3	本地、私密、离线	免费

优势

	不使用 Marga	使用 Marga
成本	所有任务都使用 GPT-4	简单任务使用 Ollama
速度	所有任务的延迟相同	快速任务使用本地模型
隐私	所有数据都发送到云端	敏感数据留在本地
供应商锁定	只能使用一个提供商	随时切换

回退链

如果首选提供商不可用或未配置：

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

---

🔗 Agent 间通信 — Setu

Agent 调用 Agent，Agent 再调用 Agent。

Agent 注册表

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 }
}

回退

如果无法连接目标 Agent：

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

调用方可以回退到本地执行，不会出现硬性失败。

---

🧩 MCP 工具

NeuroVerse 通过 Model Context Protocol 提供 6 个工具：

#	工具（npm）	工具（Python）	描述
1	neuroverse_process	india_mcp_process_multilingual_input	完整流程：检测 → 规范化 → 意图识别 → 安全检查 → 执行
2	neuroverse_store	india_mcp_store_memory	将记忆记录存储到分层系统中
3	neuroverse_recall	india_mcp_recall_memory	按用户、意图或层级检索记忆
4	neuroverse_execute	india_mcp_safe_execute	端到端安全执行（便捷工具）
5	neuroverse_route	india_mcp_route_agent	将任务路由到已注册的下游 Agent
6	neuroverse_model	india_mcp_model_route	查询多模型路由器（可选择调用）
7	neuroverse_transcribe	india_mcp_transcribe_audio	通过 Whisper STT 将音频转录为文本
8	neuroverse_synthesize	india_mcp_synthesize_speech	通过 Coqui TTS 将文本合成为语音
9	neuroverse_reason	N/A	通过 OpenRouter 实现高性能推理

真实示例

── 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

---

🌐 REST API

NeuroVerse 还附带 FastAPI REST 层，供非 MCP 客户端使用：

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

端点	方法	描述
/health	GET	健康检查
/api/process	POST	完整的多语言处理流程
/api/memory/store	POST	存储记忆
/api/memory/recall	POST	检索记忆

---

⚙️ 配置

所有设置均通过环境变量（.env）配置：

# 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

---

🧪 测试

python -m pytest tests/ -v

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 ==============================

测试内容

类别	测试数	覆盖范围
语言检测	10	泰米尔语、印地语、英语、空输入、代码切换标志
意图提取	10	全部 7 种规则模式、LLM 模拟、LLM 故障、空输入
安全引擎	12	关键词、正则表达式、风险级别、完整流程、严格模式
完整流程	8	端到端英语、泰米尔语、印地语、危险命令、边缘情况

---

🏗️ 架构

npm 版本（Node.js / TypeScript）

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

Python 版本

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（3 个包）：

包	用途
@modelcontextprotocol/sdk	MCP 协议
zod	模式验证
axios	HTTP 请求

Python（7 个包）：

包	用途
mcp[cli]	Model Context Protocol SDK
fastapi + uvicorn	REST API 层
pydantic	输入验证（v2）
langdetect	统计语言识别
asyncpg + sqlalchemy[asyncio]	PostgreSQL 异步驱动程序
httpx	用于模型 API 的异步 HTTP

---

🚀 路线图

阶段	状态	内容
v1.0	✅ 已完成	多语言解析 + 意图提取 + 5 个工具
v1.0	✅ 已完成	分层记忆系统（PostgreSQL）
v1.0	✅ 已完成	3 层安全引擎（Kavach）
v1.0	✅ 已完成	多模型路由器（Marga）+ Agent 路由（Setu）
v2.0	✅ 已完成	语音层（Whisper/Coqui）+ 扩展多语言支持
v3.0	✅ 已完成	Redis 缓存 + 基于嵌入的语义检索
v4.0	✅ 已完成	强化学习（RLHF）+ Arachne 上下文索引
v4.1	✅ 已完成	OpenRouter 推理层集成
v5.0	🔮 未来	Agent 市场与外部系统插件

---

🔐 安全

措施	实现方式
API 密钥管理	仅使用环境变量，绝不写入代码
输入清理	使用 Pydantic v2 为所有输入设置字段约束
速率限制	计划在 v2.0 实现
路径遍历	N/A — 工具不访问文件系统
SQL 注入	通过 SQLAlchemy 使用参数化查询
加密存储	交由 PostgreSQL TLS 处理

---

🤝 贡献

欢迎贡献！以下是开始的方法：

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'feat: add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

开发环境设置

# 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

---

📜 许可证

Apache-2.0

---

“我创建 NeuroVerse，是因为每次看到 Agent 忘记之前所有内容——还听不懂一个泰米尔语词，都让我心碎。”

Joshua Ragiland M
✉️ [email protected]
🌐 作品集网站

_{Joshua 用 🧠 打造——献给未来的 Agent。}