SAG: A SQL-Centric Retrieval Architecture That Replaces RAG and GraphRAG
A new SOTA for RAG — an original retrieval architecture and an open-source knowledge base for humans and agents.
At a glance
- What is it?
- Zleap-AI/SAG is a local-first knowledge base and retrieval system built on a new architecture that uses events, entities, and query-time dynamic hyperedges. It claims state-of-the-art results on multi-hop QA benchmarks, but its single-user focus and young ecosystem deserve scrutiny.
- Who is it for?
- Adopt SAG if you are an individual developer, researcher, or small team that wants a local-first, single-user knowledge base with built-in agent integration and a novel retrieval mechanism that may reduce the need for separate RAG and GraphRAG stacks. Do not adopt it if you need multi-user collaboration, mature enterprise support, or a proven track record beyond the project's own benchmarks.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What SAG Actually Solves
SAG addresses a specific pain point in retrieval-augmented generation: teams often maintain two separate systems, one for dense vector retrieval and one for graph-based relational reasoning. The README states that SAG is 'not a fusion of traditional RAG and GraphRAG' but an original architecture that replaces both. It targets individuals and agents who need a knowledge base where documents become searchable, connected, and traceable, without running an external database or managing two retrieval pipelines. The intended user is a single developer or a small team that wants a self-hosted, local-first system with a clean path to production backends. The project also explicitly supports agent integration through MCP, which makes it relevant for people building AI assistants that need grounded, cited answers.
The Event-Entity-Hyperedge Mechanism
The core idea is that each chunk of a document is parsed into one semantically complete event and multiple indexing entities. The event carries the full meaning of the chunk, unlike GraphRAG's fragmented triples. Entities are lightweight index and expansion points. A latent hyperedge is formed only at query time when SQL joins events that share entities around the current query. This design avoids offline hyperedge construction and global maintenance, which the README claims is a weakness of GraphRAG. The offline pipeline parses documents, extracts events and entities in parallel, persists chunks, events, entities, and their associations to relational storage, and also stores vector and full-text representations. The online retrieval path then uses SQL joins to create dynamic hyperedges, which allows relational reasoning without a separate graph store. The output boundary is always the original chunk, so every result can be traced back to a source.
How Retrieval Modes and Integration Work
The README describes two search modes: Fast (vector) and Precise (multi). Fast mode likely relies on vector similarity, while Precise mode probably uses the multi-hop dynamic hyperedge mechanism. The documentation does not give exact details on how these modes differ under the hood, but the naming suggests a trade-off between speed and reasoning depth. For integration, SAG offers a self-hosted REST/OpenAPI, an OpenAI-compatible chat endpoint, and MCP support. The changelog notes that a CLI client, @zleap-ai/sag-cli, can mount the SAG Knowledge MCP into Codex or Claude Code with a single command: 'sag agent connect codex | claude-code'. This removes the need for JWT copy-paste or hand-edited config files. The product also exposes a Python package, zleap-sag, and the repository includes a desktop release. For agent users, a DeepSeek Harness connector (@zleap-ai/dsh-sag) makes SAG knowledge available to DSH Agents for search and source management.
Getting It Running: Commands and Configuration
The README does not provide a full installation guide in the excerpt, but it references the zleap-sag package on PyPI and a desktop release on GitHub. The Python requirement is 3.11+, and Node 20+ is also listed, which suggests the UI or CLI may be Node-based. A typical first step would be to install the package with 'pip install zleap-sag' and then use the CLI or desktop application to start a local server. The README mentions that the product 'starts with SQLite and LanceDB, requires no external database, and keeps a clear path to PostgreSQL/pgvector.' This implies you can run it out of the box with SQLite, and later switch to PostgreSQL by changing configuration, though specific config keys are not shown in the provided material. The CLI commands for MCP integration are concrete examples of real usage. For developers, the repository likely contains a developer guide that explains how to run the full stack, but that section is not in the excerpt.
Limitations and Wrong-Tool Cases
The most obvious limitation is the deliberate single-user, local-first design. The README states the product is 'deliberately local-first and single-user.' That means it is not suitable for team-wide knowledge sharing or concurrent multi-user access without additional work. The SQLite and LanceDB backend is fine for a personal knowledge base, but if you need concurrent writes or fine-grained permissions, you will have to migrate to PostgreSQL/pgvector, which the README says is a 'clear path' but does not document in detail. Another concern is the novelty of the architecture. The README claims state-of-the-art results on HotpotQA, 2WikiMultiHopQA, and MuSiQue, but these are the project's own experiments. The paper is on arXiv, but we cannot verify peer review status. If the dynamic hyperedge mechanism fails on your specific domain or question types, you may find yourself debugging a research codebase rather than a mature product. Also, the recent UI rewrite and rapid releases (v1.8.4 to v1.8.6 in days) suggest the API may still be unstable.
Alternative Approaches and the Real Difference
The most direct alternative is a traditional GraphRAG implementation, such as Microsoft's GraphRAG or Neo4j-based retrieval systems. The key difference is that GraphRAG performs offline graph construction with triple extraction, entity merging, and relation normalization. That offline process is expensive and hard to update incrementally. SAG avoids that by not building a global graph; instead, it creates dynamic hyperedges at query time via SQL joins. Another alternative is a plain dense RAG system using vector search only, which is simpler but lacks relational reasoning. SAG's approach sits between the two, offering relational reasoning without the maintenance burden of a separate graph. For teams already invested in a vector database and a graph database, switching to SAG would mean abandoning a familiar stack. The trade-off is that SAG's mechanism is unproven outside its own benchmarks, whereas GraphRAG has broader community adoption and tooling.
Maintenance, Licensing, and Upgrade Cost
SAG is licensed under MIT, which is permissive and allows commercial use, modification, and redistribution with attribution. That is a low-license risk for most adopters. The project is actively maintained, with the last push on September 9, 2026, and a paper that appears recent. The changelog shows a major rewrite in July 2026, with the old version archived in a v1 branch and no longer maintained. That means if you relied on the old version, you must migrate to the zleap-sag package. The rapid release cadence (three versions in four days) indicates a fast-moving codebase, which can be a double-edged sword: you get bug fixes and new features, but you also face potential breaking changes. The documentation mentions 'document lifecycle controls' and 'reliable fast search and background processing' improvements, but no explicit migration guide is shown. Before upgrading, you should read the changelog for each release and test your own knowledge base against the new version. The MCP and CLI integrations are also evolving, so pinning versions for those tools is advisable.
Editorial conclusion
Adopt SAG if you are an individual developer, researcher, or small team that wants a local-first, single-user knowledge base with built-in agent integration and a novel retrieval mechanism that may reduce the need for separate RAG and GraphRAG stacks. Do not adopt it if you need multi-user collaboration, mature enterprise support, or a proven track record beyond the project's own benchmarks. Before committing, verify the arXiv paper (2606.15971) has been peer-reviewed, test retrieval quality on your own multi-hop questions, and confirm the PostgreSQL backend is ready for production. The project's rapid release cadence and recent UI rewrite suggest the API may still shift, so pin a specific version and review the changelog before upgrading.
Community notes