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 prototype and a production-ready system by implementing complex engineering patterns for document governance, intent analysis, hybrid retrieval, and agentic reasoning, specifically targeting the challenges of hallucinations, token costs, and retrieval precision in corporate environments.

How it works

The system operates through a coordinated architecture consisting of several key components:

• Three-Layer Executor: Instead of routing all queries to an LLM, it uses a deterministic orchestration layer to分流 queries into three paths: Ambiguity Clarification (for insufficient info), RAG Knowledge QA (for evidence-based answers), or a ReAct Agent (for open-ended reasoning and web search).
• Pre-orchestration Engine: Before retrieval, the system performs query rewriting (to handle pronouns), sub-question splitting, and knowledge domain shrinkage to narrow the search scope.
• Hybrid Retrieval Pipeline: It combines vector search (PGVector) and keyword search (Elasticsearch) using Reciprocal Rank Fusion (RRF) and optional Reranking. It utilizes a Parent-Child chunking strategy where small blocks are used for matching and larger blocks are used for generating the final answer.
• Knowledge Base Governance: Documents are processed via an asynchronous Kafka pipeline using Apache Tika for parsing and a combination of structural, recursive, semantic, and LLM-based chunking strategies. A Neo4j graph is used to maintain the document hierarchy (Document $\rightarrow$ Section $\rightarrow$ Item).
• Agentic Capabilities: Implements a ReAct loop with tool calling, MCP (Model Context Protocol) integration for dynamic tool discovery, and a "Skills" system for declarative capability extensions via SKILL.md files.

Who it’s for

• Backend Developers: Specifically those in the Java ecosystem who want to build AI applications without switching to Python.
• AI Engineers: Developers looking for a production-grade implementation of Agentic RAG and MCP.
• Students/Job Seekers: Individuals wanting a comprehensive project to demonstrate deep understanding of RAG and Agent engineering beyond basic tutorials.

Highlights

• Agentic RAG: Full ReAct implementation with checkpoint persistence in MySQL and parallel tool execution.
• Advanced Retrieval: Dual-channel hybrid search with RRF fusion and Parent-Child block aggregation.
• Knowledge Routing: A three-stage funnel (Scope $\rightarrow$ Topic $\rightarrow$ Document) to lock onto relevant knowledge before retrieval.
• Production Guardrails: Includes Redis-based lease mutexes for cluster safety, model/tool call limits to prevent infinite loops, and full-link observability tracing.
• Memory Management: Three distinct strategies: no memory, sliding window, and summary compression to balance token costs and context.
• MCP & Skills: Integration of the Model Context Protocol and a declarative skill system for hot-swappable capability extensions.