SAG

SAG

English · 简体中文

From now on, this is the only knowledge base app you need.

Built on the state-of-the-art SAG architecture, it turns scattered documents and data into knowledge that is searchable, connected, and traceable.

https://github.com/user-attachments/assets/ac805e3c-ab52-4857-bef6-2865f3831b2f ## Contents

Community · Project · Technology · User Guide · Developer Guide

--- ## Project ### Changelog **August 30, 2026** SAG now supports [`@zleap-ai/dsh-sag`](https://github.com/Zleap-AI/dsh-sag). The built-in local DeepSeek Harness connector makes SAG knowledge available to DSH Agents for search, source reading, and source and document management. **August 13, 2026** Added OCTX source import and export with integrity validation, conflict handling, failure recovery, and compatible vector reuse for cross-instance knowledge base migration and backup. This release also improves continuous Chinese-term retrieval and document lifecycle controls for more reliable fast search and background processing. **July 31, 2026** Published the official command-line client [`@zleap-ai/sag-cli`](docs/sag-cli.en.md). One command (`sag agent connect codex | claude-code`) mounts the SAG Knowledge MCP into Codex or Claude Code — no JWT copy-paste, no hand-edited config files. The MCP guide below now leads with the CLI. **July 14, 2026** Released a completely new version built on the `zleap-sag` package, featuring an entirely redesigned UI. The previous version has been archived in the `v1` branch and is no longer maintained. ### SAG in one minute SAG is not a fusion of traditional RAG and GraphRAG. It is an original retrieval architecture that replaces both. Through event-entity indexing and query-time dynamic hyperedges, SAG delivers semantic retrieval and relational reasoning in one system, without maintaining two RAG systems or merging two retrieval paths. Experiments on HotpotQA, 2WikiMultiHopQA, and MuSiQue show that SAG achieves the best retrieval and end-to-end QA performance on every benchmark, establishing a new state of the art for RAG. This project is a complete knowledge base application for individuals and Agents built on SAG: **sources and documents → structured knowledge → search and source tracing → cited Agent answers → reuse through API or MCP** Upload a document once. SAG parses it, splits it into chunks, embeds it, extracts events and entities, and keeps every retrieval result connected to the original text. You can then search across sources, inspect the event-entity graph, ask questions with citations, or expose the same knowledge to another application. | Capability | What it gives you | | --- | --- | | Knowledge ingestion | File and web sources, document parsing, chunking, embedding, event/entity extraction, background processing | | Search | Global or source-scoped retrieval with Fast (`vector`) and Precise (`multi`) modes | | Source tracing | Open any result or citation back to the exact original chunk | | Knowledge graph | Inspect events, entities, and their queryable associations | | Agent chat | Multi-turn answers grounded in selected sources, with clickable citations | | Integration | Self-hosted REST/OpenAPI, OpenAI-compatible chat, MCP, and the `zleap-sag` Python package | The product is deliberately local-first and single-user. It starts with SQLite and LanceDB, requires no external database, and keeps a clear path to PostgreSQL/pgvector and other production backends. --- ## Technology ### Paper **SAG: SQL-Retrieval Augmented Generation with Query-Time Dynamic Hyperedges**
Yuchao Wu*, Junqin Li, XingCheng Liang, Yongjie Chen, Yinghao Liang, Linyuan Mo, and Guanxian Li [Read the paper](https://arxiv.org/abs/2606.15971) · [Reproduce the benchmark](https://github.com/Zleap-AI/SAG-Benchmark)

### An original third architecture Traditional dense RAG retrieves chunks mainly by semantic similarity. GraphRAG adds offline graph construction, but pays for triple extraction, entity merging, relation normalization, global maintenance, and difficult incremental updates. SAG does not wrap those two systems. It replaces that choice with its own data model and execution path: ```text chunk → one semantically complete event chunk → multiple indexing entities event ↔ entities → one latent hyperedge ``` - **Event** carries the complete meaning of a chunk. It is not fragmented into independent triples. - **Entity** is a lightweight index and expansion point, not a replacement for the event's meaning. - **Query-time dynamic hyperedge** is created locally when SQL joins events that share entities around the current query. SAG does not pre-build or globally maintain those hyperedges. - **Original evidence** remains the output boundary. Selected events always map back to source chunks for generation and citation. The semantic and structural paths inside SAG are native parts of the SAG pipeline. They are not a traditional RAG service and a GraphRAG service running side by side.

### How retrieval works **Offline indexing** 1. Parse a document into semantically coherent chunks. 2. Extract one event and multiple entities from each chunk in parallel. 3. Persist chunks, events, entities, and event-entity associations to relational storage. 4. Persist chunk, event, and entity representations to vector/full-text indexes. **Online retrieval** 1. Find seed entities and events using semantic and lexical signals. 2. Use SQL joins over shared entities to expand from seed events into a local candidate space. 3. Instantiate only the hyperedges relevant to this query; no global graph traversal or rebuild is required. 4. Select the strongest event and direct-chunk candidates, deduplicate them, and return the original evidence chunks. This makes incremental writes natural: a new chunk adds its own event, entities, and associations without recomputing a global graph. ### A new SOTA for RAG Under the same `BGE-Large-EN-v1.5` embedding and `Qwen3.6-Flash` LLM configuration, SAG achieves the best retrieval and end-to-end QA performance on every benchmark across HotpotQA, 2WikiMultiHopQA, and MuSiQue. - Across the three datasets, SAG averages **90.07%/72.96%** in Recall@5 and F1, outperforming the strongest baseline for each metric by **6.79/4.33** percentage points, respectively. - On the most challenging MuSiQue dataset, SAG outperforms the strongest baseline for each metric by **11.52/7.01** percentage points in Recall@5 and F1, respectively. Full results:

See the [paper](https://arxiv.org/abs/2606.15971) and [SAG-Benchmark](https://github.com/Zleap-AI/SAG-Benchmark) for the full method and reproduction scripts. --- ## User Guide ### Desktop app (easiest) Download the latest desktop installer from [GitHub Releases](https://github.com/Zleap-AI/SAG/releases/latest): | Platform | Download | Update behavior | | --- | --- | --- | | macOS 15+, Apple Silicon | `SAG-*-mac-arm64.dmg` | Signed, notarized, and updated through the stable channel | | Windows 10/11, x64 | `SAG-Setup-*-win-x64.exe` | Unsigned for now; Windows may show an unknown-publisher warning; stable automatic updates remain supported | The desktop app bundles the Web workspace and local knowledge backend, so users do not need to install Python, Node.js, or a database. Application updates preserve the knowledge base and uploads in the operating system's application-data directory. Release checksums are published as `SHA256SUMS.txt`. ### Quick start (Docker, self-hosted) Requirements: Docker Desktop, or Docker Engine with Compose v2. ```bash git clone https://github.com/Zleap-AI/SAG.git cd SAG docker compose up -d --build ``` No API key, Python runtime, Node runtime, or external database is required to boot the application. When both services are healthy, open: - Web application: [http://localhost:3000](http://localhost:3000) - API documentation: [http://localhost:8000/docs](http://localhost:8000/docs) On first launch: 1. Enter your name to create or restore the local identity. 2. Use the 302.AI quick setup, or open **Settings → Models** and configure any OpenAI-compatible LLM and embedding endpoint. 3. Create a source, upload documents, and wait until their status is **Ready**. 4. Search, open the original source, or start a cited conversation. The UI and services still start without model credentials. Embeddings are required for indexing/vector retrieval; the LLM is required for event extraction, query understanding, and generated answers. #### Model settings precedence `SAG_LLM_*` values in Docker Compose or `.env` provide the initial model configuration. After an administrator saves model settings in the web UI, the persisted Settings value is used for subsequent extraction and generation jobs without a restart. To make the deployment configuration mandatory, set `SAG_LOCK_LLM_CONFIG=true`. SAG then shows the generation fields as locked in Settings and continues to use the `SAG_LLM_*` values. Change Docker Compose or `.env` and restart the API container to update a locked configuration. API keys remain deployment-managed and are never returned by the Settings API. ### Import knowledge Create a source and add Markdown, text, PDF, Office, or other supported documents. SAG normalizes documents to Markdown, then runs chunking, embedding, event extraction, and entity extraction in the background.

PDF files use MinerU when it is configured and fall back to local MarkItDown when it is unavailable or fails. Other Office and text formats use MarkItDown by default. ### Search and verify the source Search globally or restrict the query to selected sources. Every result can open the original chunk beside the ranked result, so retrieval quality is inspectable before an Agent uses it.

### Ask with citations The default Agent searches the bound knowledge sources, streams the answer, and attaches clickable citations. The same conversation path is also available through an OpenAI-compatible endpoint.

### Explore mode Explore mode unfolds the entire knowledge base into an interactive knowledge universe. Search events and entities, travel through their relationships, and open event details or original sources without leaving the same view.

### Explore the event-entity graph Switch a source from list view to graph view to inspect the events, entities, and associations produced by the SAG index.

### MCP guide The recommended path is two steps: **CLI** mounts the MCP, **Skill** teaches the Agent how to explore it. Together they give you a complete knowledge retrieval setup with zero hand-edited config. #### Step 1: mount MCP with the CLI [`@zleap-ai/sag-cli`](docs/sag-cli.en.md) is the official command-line client. It auto-discovers your local Docker SAG container, verifies the MCP works, and wires it into Codex or Claude Code — for the local Docker path no JWT is needed. Install (Node.js ≥ 20.19): ```bash npm install --global @zleap-ai/sag-cli ``` Wire the MCP in one command: ```bash sag mcp test # verify the SAG MCP