XYVREN Agent | AI Operating Workspace

One brain. Any model. Every agent.
Unified AI Operating Workspace delivering persistent cross-agent memory, resilient multi-provider model routing, autonomous developer IDE, and native Model Context Protocol (MCP) tooling.

---

🌟 Overview

XYVREN decouples intelligence from memory. When you change models or spawn new agents, the project memory, architectural decisions, and coding standards remain fully intact.

• XYVREN Brain: Persistent knowledge engine combining relational Knowledge Graphs and vector embeddings (pgvector) across 5 scopes: GLOBAL, WORKSPACE, PROJECT, AGENT, and SESSION.
• XYVREN Connect: Intelligent multi-provider gateway (OpenAI, Anthropic, Google Gemini, Groq, Mistral, Ollama/Local) with automatic latency/cost-optimized primary and fallback routing.
• Build Studio (Agent IDE): Autonomous agent workspace capable of inspecting project file trees, proposing clean inline diffs, running safe live sandboxes, and learning project conventions.
• Model Context Protocol (MCP): Native JSON-RPC 2.0 interface exposing 9 internal Brain tools to external clients (Claude Desktop, Cursor, external CLI agents).
• Observability & Audit Stream: Complete zero-secret-leakage telemetry log capturing token consumption, latency benchmarks, tool calls, and model fallbacks.

---

🏗️ System Architecture

               ┌────────────────────────────────────────────────────────┐
               │                     XYVREN BRAIN                       │
               │  • pgvector Semantic Storage   • Relational Knowledge   │
               │  • 5 Memory Scopes             • Context Engine Pack    │
               └──────────────────────────┬─────────────────────────────┘
                                          │ Context Packs & Memories
                                          ▼
┌───────────────────────────┐      ┌──────────────────────────┐      ┌───────────────────────────┐
│        AI AGENT IDE       │◄────►│   XYVREN CONNECT ROUTER  │◄────►│        MCP SERVERS        │
│ • Code Proposal Diff      │      │ • Multi-Provider Adapter │      │ • /api/mcp (JSON-RPC 2.0) │
│ • Sandboxed Live Preview  │      │ • Auto Fallback Engine   │      │ • Standardized Tools      │
│ • Convention Learning     │      │ • Zero Secret Leakage    │      │ • Claude / Cursor Bridge  │
└───────────────────────────┘      └──────────────┬───────────┘      └───────────────────────────┘
                                                  │
                   ┌──────────────────────────────┴──────────────────────────────┐
                   │                                                             │
                   ▼                                                             ▼
       [ Cloud Providers ]                                              [ Local Inference ]
   Anthropic • OpenAI • Gemini                                        Ollama (Llama 3.2,
      Groq LPU • Mistral                                                DeepSeek-R1, Qwen)

---

⚡ Key Modules

1. 🧠 XYVREN Brain

• Multi-Scope Memory: Keeps context isolated or inherited across GLOBAL, WORKSPACE, PROJECT, AGENT, and SESSION.
• Knowledge Graph Visualizer: Interactive SVG network canvas visualizing entity relations, protocols, and subsystem topologies.
• Automated Context Ingestion: Extracts facts, preferences, decisions, and standards directly into the persistent layer.

2. 🔌 XYVREN Connect

• Unified AI Gateway: Drop-in OpenAI-compatible endpoints (/api/v1/chat/completions and /api/v1/models).
• Resilient Routing Profiles: Pre-configured routing strategies:
  • Auto Resilient: Primary model with automatic fallback to secondary providers upon error or rate limit.
  • Lowest Latency: Sub-50ms execution via Groq LPUs or local runtimes.
  • Cost Optimizer: Balances lightweight task execution against token budgets.
• Vaulted Credentials: Encrypted server-side storage ensuring raw secrets are never exposed to browser clients.

3. 🛠️ Build Workspace (Agent IDE)

• Autonomous Engineer Agents: Frontend, Backend, Security, and DevOps specialist agents.
• Structured Diff Proposals: Side-by-side unified code diff viewer with granular accept/reject controls.
• Simulated Sandbox & Preview: Live multi-viewport renderer (Desktop, Tablet, Mobile) reflecting agent changes.

4. 🌐 Model Context Protocol (MCP) Server

• Exposes internal tools via standardized JSON-RPC 2.0 protocol (POST /api/mcp):
  • xyvren_memory_search: Semantic retrieval over Brain memories.
  • xyvren_memory_write: Store new facts or decisions.
  • xyvren_memory_get / xyvren_memory_update / xyvren_memory_delete: CRUD memory management.
  • xyvren_graph_search / xyvren_graph_neighbors: Graph traversal and concept relationship discovery.
  • xyvren_context: Compile structured context packs for prompt injection.
  • xyvren_project_context: Project-specific memory context.

---

🚀 Getting Started

Prerequisites

• Node.js v20.x or v22.x+
• npm v10+ (or pnpm / yarn)
• Optional: PostgreSQL with pgvector extension

1. Clone the Repository

git clone https://github.com/xyvren/xyvren_agent.git
cd xyvren_agent

2. Install Dependencies

npm install

3. Environment Configuration

Copy the example environment configuration:

cp .env.example .env.local

4. Run the Development Server

npm run dev

Open http://localhost:3000 (or port 3001 if port 3000 is occupied).

---

📡 API Reference

OpenAI-Compatible Chat Completions

curl -X POST "http://localhost:3000/api/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet",
    "messages": [
      { "role": "user", "content": "What is our zero secret leakage standard?" }
    ],
    "brain_access": true
  }'

MCP JSON-RPC 2.0 Endpoint

curl -X POST "http://localhost:3000/api/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "xyvren_memory_search",
      "arguments": {
        "query": "design guidelines",
        "scopes": "GLOBAL,WORKSPACE"
      }
    }
  }'

---

📂 Project Structure

├── prisma/
│   └── schema.prisma              # PostgreSQL schema with pgvector extensions
├── src/
│   ├── app/
│   │   ├── activity/page.tsx      # Real-time audit telemetry & event stream
│   │   ├── brain/page.tsx         # Knowledge Graph & Memory management
│   │   ├── build/page.tsx         # Agent IDE & Code Diff reviewer
│   │   ├── connect/page.tsx       # AI Gateway & Provider management
│   │   ├── playground/page.tsx    # Context Inspector & Testing Playground
│   │   ├── settings/page.tsx      # Workspace settings & Vault
│   │   ├── page.tsx               # Ecosystem Overview & Architecture diagram
│   │   └── api/
│   │       ├── activity/          # Activity telemetry stream
│   │       ├── brain/             # Memory CRUD & Graph traversal API
│   │       ├── build/             # Project file management & Agent execution
│   │       ├── connect/           # Provider health tests & router toggle
│   │       ├── mcp/               # Model Context Protocol JSON-RPC 2.0
│   │       └── v1/                # OpenAI-compatible /chat/completions & /models
│   ├── components/
│   │   ├── brain/                 # KnowledgeGraphVisualizer & MemoryModal
│   │   ├── build/                 # DiffViewer, FileTree, LivePreview
│   │   ├── dashboard/             # ArchitectureDiagram
│   │   └── layout/                # AppSidebar & Header
│   ├── server/
│   │   └── mock-db.ts             # In-memory singleton database state
│   ├── services/
│   │   ├── brain/                 # memoryService & graphService
│   │   ├── connect/               # providerService & routerService
│   │   ├── context/               # contextEngine
│   │   ├── mcp/                   # mcpServerService
│   │   └── projects/              # projectService
│   └── types/                     # TypeScript definitions across all modules
├── package.json
├── tsconfig.json
└── README.md

---

🛡️ Security & Zero Secret Leakage Standard

• Zero Client-Side Secret Exposure: No API keys, database credentials, or provider secrets are ever bundled into client JavaScript.
• Masked Telemetry: Provider authentication is handled strictly on server boundary adapters.
• Audit Trail: Every agent invocation, memory query, and fallback trigger is stamped with an immutable ID and timestamp.

---

📄 License

MIT License © 2026 XYVREN