> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Zeus Knowledge Base System Overview — Agentic RAG Architecture & Technology Stack

Zeus's knowledge base system implements **Agentic RAG** (Retrieval-Augmented Generation), enabling the Agent to proactively retrieve relevant information from user-uploaded documents. Unlike traditional RAG, Zeus's knowledge base is a **specialized tool** for the Agent — the Agent autonomously decides when to invoke retrieval, supports multi-turn queries and result verification, and works in concert with other tools (code execution, web search, etc.).

***

## Core Architecture

```mermaid theme={null}
graph TD
    subgraph Agent["Zeus Agent"]
        tool["search_knowledge_base<br/>Agentic RAG Tool"]
        parse["parse_resource_file<br/>Document Parsing Tool"]
    end

    subgraph Services["Service Layer"]
        rag["RAGService<br/>Retrieval + Formatting"]
        doc["DocumentService<br/>Upload + Parse + Chunk"]
        chunker["SmartChunker<br/>Intelligent Chunking"]
    end

    subgraph Storage["Storage Layer"]
        pgvector["PostgreSQL pgvector<br/>Vector Store + Metadata Filtering"]
        bm25["BM25Store<br/>Keyword Index (3-tier Cache)"]
        nextjs["Next.js API<br/>Knowledge Base / Document Metadata (CRUD)"]
        local["Local File System<br/>Original Document Files"]
    end

    tool --> rag
    parse --> doc
    rag --> pgvector
    rag --> bm25
    doc --> chunker
    doc --> pgvector
    doc --> nextjs
    doc --> local
```

The system uses a **dual-path recall** strategy combining **vector semantic search + BM25 keyword matching**, with results merged and ranked via **RRF (Reciprocal Rank Fusion)** for optimal results.

***

## Technology Stack

| Component         | Technology                                          | Description                                                |
| ----------------- | --------------------------------------------------- | ---------------------------------------------------------- |
| Vector Store      | PostgreSQL pgvector (`langchain-postgres` PGVector) | Vector storage + metadata filtering with cosine similarity |
| Embedding         | OpenAI `text-embedding-3-small` (default)           | Supports user-configurable embedding models                |
| Keyword Retrieval | BM25 (`rank-bm25` + `jieba` Chinese tokenizer)      | 3-tier cache (Memory → Redis → PostgreSQL), lazy-loaded    |
| Document Parsing  | LangChain Document Loaders + SmartChunker           | Multi-format support + semantically-aware chunking         |
| Metadata Storage  | Next.js API (Drizzle ORM + PostgreSQL)              | Knowledge base / document CRUD                             |
| Agent Framework   | DeepAgents (LangGraph)                              | Agentic RAG tool integration                               |

***

## Data Flow Overview

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Web as Web App
    participant NextJS as Next.js API
    participant Backend as AI Backend
    participant PGVector as pgvector
    participant BM25 as BM25Store

    User->>Web: Upload document to knowledge base
    Web->>Backend: POST /documents (file)
    Backend->>Backend: Save file locally
    Backend->>NextJS: Create document record

    User->>Web: Trigger processing
    Web->>Backend: POST /documents/{id}/process
    Backend->>Backend: Load → SmartChunker → Embedding
    Backend->>PGVector: Store vectors + metadata
    Backend->>BM25: invalidate(kb_id)
    Backend->>NextJS: Update status → completed

    User->>Web: Reference @knowledge-base in conversation
    Web->>Backend: POST /agent/invoke (knowledge_base_ids)
    Backend->>Backend: Agent calls search_knowledge_base
    Backend->>PGVector: Vector retrieval
    Backend->>BM25: BM25 retrieval (auto-builds index on first use)
    Backend->>Backend: RRF fusion ranking
    Backend->>User: SSE streaming response (with knowledge base citations)
```

<CardGroup cols={2}>
  <Card title="Document Processing" icon="file-lines" href="/en/knowledge-base/document-processing">
    Multi-format upload, SmartChunker intelligent chunking, processing pipeline
  </Card>

  <Card title="Vector Store" icon="database" href="/en/knowledge-base/vector-store">
    pgvector storage, user-level embedding configuration
  </Card>

  <Card title="Retrieval Strategy" icon="magnifying-glass" href="/en/knowledge-base/retrieval">
    Dual-path recall, RRF fusion, BM25 3-tier cache
  </Card>

  <Card title="API Reference" icon="code" href="/en/knowledge-base/api">
    Knowledge base / document management APIs, Agent tools
  </Card>
</CardGroup>