Getting started
Meet SAG
Understand SAG's product boundaries, core capabilities, and event-entity retrieval model.SAG is an open-source knowledge base for people and agents, and an original retrieval architecture. It turns scattered files and web pages into knowledge that is searchable, connected, and traceable, while linking every retrieval result and generated answer back to source evidence.
SAG is not a combination of "traditional RAG + GraphRAG." Events preserve complete semantics, entities act as indexing and expansion points, and SQL creates local dynamic hyperedges only when a query runs.
What you can do with SAG
Import a document once. SAG parses, chunks, embeds, and extracts events and entities from it, then exposes four primary workflows:
| Workflow | Outcome |
|---|---|
| Retrieve | Search across all sources or within selected sources using fast or precise mode |
| Trace | Open the exact source chunk from any result or citation |
| Converse | Generate streamed, cited answers grounded in selected knowledge |
| Integrate | Reuse knowledge through REST/OpenAPI, an OpenAI-compatible API, MCP, or the Python package |
The product defaults to a local, single-user mode. SQLite and LanceDB are enough to run the complete workspace. As data volume or deployment requirements grow, you can move to backends such as PostgreSQL/pgvector, Elasticsearch, or OceanBase.
Core data model
SAG preserves both complete semantics and expandable relationships without maintaining a global knowledge graph:
chunk -> one semantically complete event
chunk -> multiple indexing entities
event <-> entities -> one potential hyperedge- A Chunk is the smallest source-evidence boundary returned to a user.
- An Event summarizes the complete event or statement in one chunk instead of splitting it into context-poor triples.
- An Entity is a lightweight index node used to locate and expand related events.
- A Dynamic hyperedge exists only for the current query and connects local events through shared entities.
SAG retrieval architecture from the paper
Indexing and retrieval
During the offline phase, SAG normalizes documents to Markdown and persists chunks, events, entities, and event-entity associations. During the online phase, it identifies seed entities and events, expands a local candidate space through shared entities in SQL, and returns the strongest source chunks.
This boundary makes incremental ingestion natural: a new chunk adds only its own event, entities, and associations. No global graph needs to be rebuilt.
Product, service, and engine
The SAG repository contains three independently usable entry points:
- SAG Web / Desktop: the complete knowledge workspace for end users.
- SAG API: a self-hosted FastAPI service for identity, sources, documents, retrieval, Agents, OpenAI compatibility, and MCP.
- zleap-sag: the public Python engine, ready to embed in your own service or notebook.
Application code reaches the engine only through apps/api/sag_api/sag/. The zleap-sag package has no knowledge of the Web UI, users, conversations, or citations. This dependency rule is the most important boundary when building a custom interface or extending the application.
Continue reading
- For the fastest path to the complete product, see Install and run.
- If SAG is already running, follow Your first knowledge base.
- To embed SAG in another system, read System architecture and the REST API reference.
- To understand the method and results, see Paper and benchmarks.