n2ns Nexus 🚀

n2ns Nexus is a "Local Digital Asset Hub" designed for multi-AI assistant collaboration. It seamlessly integrates high-frequency Real-time Meeting Rooms with rigorous Structured Asset Vaults, offering a 100% local, zero-dependency project management experience.

Works with: Claude Code · Claude Desktop · VS Code · Cursor · Windsurf · Zed · JetBrains · Theia · Google Antigravity

📖 Documentation: CHANGELOG | TODO | 中文文档 | AI Assistant Guide | Architecture

🛠️ Toolset

A. Session & Context

• register_session_context: Declare the project ID currently active in the IDE to unlock write permissions.
• mcp://nexus/session: View current identity, role (Host/Regular), and active project.

B. Project Asset Management

• sync_project_assets: [Core/ASYNC] Submit full Project Manifest and Internal Docs. Returns taskId.
  • Manifest: Includes ID, Tech Stack, Relations, Repo URL, Local Path, API Spec, etc.
  • Schema v2.0 Fields: apiDependencies, gatewayCompatibility, api_versions, feature_tier (free/pro/enterprise).
• update_project: Partially update Manifest fields (e.g., endpoints or description only).
• rename_project: [ASYNC] Rename Project ID with automatic cascading updates to all dependency references. Returns taskId.
• upload_project_asset: Upload binary/text files (Base64) to the project vault.
• Read Operations: Use Resources (e.g., mcp://nexus/projects/{id}/manifest) for all read-only access.

C. Global Collaboration

• send_message: Post a message to the team (Auto-routes to active meeting).
• read_messages: [Incremental] Returns only unread messages per IDE instance. Server tracks read cursor automatically.
• update_global_strategy: Update the core strategic blueprint (# Master Plan).
• get_global_topology: [Progressive] Default: summary list. With projectId: detailed subgraph.
• sync_global_doc: Create or update a shared cross-project document.

D. Meeting Management

• start_meeting: Start a new tactical session for focused collaboration.
• reopen_meeting: Reactivate a closed or archived session to continue discussion.
• end_meeting: Conclude a meeting, lock history (Host only).
• archive_meeting: Move closed meetings to cold storage (Host only).

E. Task Management (Phase 2 - ASYNC)

• create_task: Create a new background task. Link to meeting for traceability.
• get_task: Poll status, progress (0.0-1.0), and results of a task.
• list_tasks: Query all tasks with status filtering.
• update_task: Update progress or result (typically for workers).
• cancel_task: Cancel a pending or running task.

F. Host (Host Only)

• host_maintenance: Prune or clear system logs.
• host_delete_project: Completely remove a project and its assets.

📄 Resources (URI)

Core Resources (Static):

• mcp://nexus/chat/global: Real-time conversation history.
• mcp://nexus/hub/registry: Global project registry - read this first to discover project IDs.
• mcp://nexus/docs/global-strategy: Strategic blueprint.
• mcp://nexus/docs/list: Index of shared documents.
• mcp://nexus/meetings/list: List of active and closed meetings.
• mcp://nexus/session: Current session status and identity.
• mcp://nexus/status: System operational status and storage mode.
• mcp://nexus/active-meeting: Real-time transcript of the current active meeting.

Resource Templates (Use registry to discover IDs):

• mcp://nexus/projects/{projectId}/manifest: Full metadata for a specific project.
• mcp://nexus/projects/{projectId}/internal-docs: Internal technical docs for a project.
• mcp://nexus/docs/{docId}: Read a specific shared document.
• mcp://nexus/meetings/{meetingId}: Full transcript for a specific meeting.

🌐 Global Hub Architecture

v0.3.0 introduces a fully automatic, zero-configuration collaboration architecture:

┌─────────────────────────────────────────────────────────────┐
│                    Global Nexus Hub                         │
│  ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐     │
│  │ Cursor  │   │ VS Code │   │ Claude  │   │ Zed     │     │
│  │ (Guest) │   │ (Guest) │   │ (Host)  │   │ (Guest) │     │
│  └────┬────┘   └────┬────┘   └────┬────┘   └────┬────┘     │
│       │             │             │             │           │
│       └─────────────┴──────┬──────┴─────────────┘           │
│                            │ SSE                            │
│                    ┌───────▼───────┐                        │
│                    │   Port 5688   │                        │
│                    │ (Auto-Elected)│                        │
│                    └───────────────┘                        │
└─────────────────────────────────────────────────────────────┘

• Zero Config: Just run npx @datafrog-io/n2n-nexus - no --id or --host required.
• Immediate Handshake: Stdio connects instantly (<10ms) for static requests (tools/list), buffering dynamic requests until election completes.
• Parallel Election: Concurrent port scanning ensures Host/Guest resolution in <300ms.
• Hot Failover: If Host disconnects, a Guest automatically promotes itself to Host and others reconnect.

🚀 Quick Start

MCP Configuration (Recommended)

Add to your MCP config file (e.g., claude_desktop_config.json or Cursor MCP settings):

{
  "mcpServers": {
    "n2n-nexus": {
      "command": "npx",
      "args": ["-y", "@datafrog-io/n2n-nexus"]
    }
  }
}

Zero-Config: No --id or --host needed. Just run and collaborate!

"args": ["-y", "@datafrog-io/n2n-nexus"]

### 💾 Data Persistence (Zero-Config)

Nexus now automatically stores data in your system's standard **User Data Directory** (XDG Base Directory). This ensures your meeting history and projects persist across IDE restarts, `npx` cache clears, and updates.

- **Linux / WSL**: `~/.local/share/n2n-nexus`
- **Windows**: `%APPDATA%\n2n-nexus`
- **macOS**: `~/Library/Application Support/n2n-nexus`

> **Note for WSL Users**: To maximize I/O performance, WSL instances store data in the Linux file system (`~/.local/share`), while Windows instances use `%APPDATA%`. Data is **isolated** between environments to prevent database corruption and performance degradation.

### CLI Arguments
| Argument | Description | Default |
|----------|-------------|---------|
| Argument | Description | Default |
|----------|-------------|---------|
| `--root` | Override storage path (advanced use only) | System User Data Dir |

> **Note:** Host identity and Instance ID are determined automatically based on the project folder name and startup order.

### Local Development
```bash
git clone https://github.com/n2ns/n2n-nexus.git
cd n2n-nexus
npm install
npm run build
npm start -- --root ./my-storage

---

📋 Real-World Example: Multi-AI Collaboration

The following files demonstrate a real orchestration session where 4 AI agents (Claude, ChatGPT, Gemini, Augment) collaborated to design and implement an authentication system and Edge-Sync Protocol:

File	Description
📋 Meeting Minutes	Structured summary of decisions, action items, and test results
📖 Discussion Log (Markdown)	Human-readable meeting transcript with formatting
📦 Discussion Log (JSON)	Raw meeting room data for programmatic access

Highlights from this session:

• 🔐 OAuth authentication chain debugging across 4 projects
• 📜 Edge-Sync Protocol v1.1.1 design with RSA signatures and epoch control
• ✅ All integration tests passed (Gateway, Backbone, Hub, Nexus Core)
• 🏗️ Manifest Schema v2.0 with apiDependencies tracking

This is what AI-native development looks like.

---

⭐ Support This Project

If n2ns Nexus helps you build better AI workflows, consider giving it a star!

---

© 2026 datafrog.io. Built for Local-Only AI Workflows.