java-up-up/nexus-agent

What it solves

Nexus Agent is an enterprise-grade AI agent platform designed to move beyond simple API calls and basic RAG demos. It addresses the gap between a trivial prototype and a production-ready system by implementing complex engineering patterns for document governance, high-precision retrieval, and autonomous agent behavior, specifically targeting the challenges of hallucinations, token costs, and retrieval accuracy in corporate environments.

How it works

The system employs a multi-layered architecture that avoids relying solely on the LLM for decision-making. It uses a Pre-orchestration Engine to handle query rewriting, sub-question splitting, and ambiguity detection before routing the request to one of three executors: a Clarification Executor (for vague queries), a RAG Knowledge Executor (e-g., evidence-driven generation with citations), or a ReAct Agent Executor (for open-ended tasks requiring multi-step reasoning and tool use).

Key technical components include:

• Hybrid Retrieval: Combines vector search (PGVector) and keyword search (Elasticsearch) using Reciprocal Rank Fusion (RRF) and optional Reranking.
• Knowledge Graph: Uses Neo4j to map document structures (Document $\rightarrow$ Section $\rightarrow$ Item) for structural navigation.
• Parent-Child Chunking: Retrieves small "child" chunks for precision but provides larger "parent" chunks to the LLM for full context.
• Memory Management: Offers three strategies (None, Sliding Window, and Summary Compression) to balance context window limits with token costs.
• MCP & Skills: Integrates the Model Context Protocol (MCP) for dynamic tool discovery and a declarative "Skills" system for extensible domain capabilities.

Who it’s for

• Backend developers (particularly Java/Spring) looking to transition into AI application development.
• Engineers wanting to implement a production-grade RAG/Agent system with a focus on engineering rigor rather than just model tuning.
• Students or professionals preparing for technical interviews regarding frontier AI architectures.

Highlights

• Three-Tier Execution: Prevents unpredictable agent behavior by prioritizing stable RAG paths over open-ended agent exploration.
• Causal Evidence Control: Implements "no-evidence short-circuiting" to prevent the model from hallucinating when no relevant documents are found.
• Composite Chunking Engine: Combines structural, recursive, semantic, and LLM-based chunking strategies.
• Enterprise Guardrails: Includes Redis-based lease locks for cluster concurrency, model/tool call limits to prevent infinite loops, and full-link observability traces.
• Shadow Routing: Silently compares system-recommended documents against user-selected ones to continuously optimize routing quality.