# SAG Wiki

> Bilingual documentation for SAG, an open-source local-first knowledge base and original retrieval architecture using event-entity indexes and query-time dynamic hyperedges.

## Primary resources

- [SAG GitHub](https://github.com/Zleap-AI/SAG)
- [SAG paper](https://arxiv.org/abs/2606.15971)
- [zleap-sag](https://pypi.org/project/zleap-sag/)

## English documentation

- [Meet SAG](https://sag.wiki/en/guide/introduction): Understand SAG's product boundaries, core capabilities, and event-entity retrieval model.
- [Install and run](https://sag.wiki/en/guide/installation): Choose the desktop app or Docker and start a complete SAG workspace locally.
- [Your first knowledge base](https://sag.wiki/en/guide/first-knowledge-base): Create a local identity, configure models, import a document, and get a cited answer.
- [Ingestion and parsing](https://sag.wiki/en/guide/ingestion): Learn how files and web pages become Markdown, chunks, and indexed knowledge.
- [Retrieval and source tracing](https://sag.wiki/en/guide/search): Use fast and precise retrieval, then verify every result against its source evidence.
- [Agent conversations](https://sag.wiki/en/guide/agent-chat): Control knowledge scope, attachments, and sessions while producing streamed cited answers.
- [Knowledge Universe and graphs](https://sag.wiki/en/guide/explore): Explore events, entities, timelines, and source text in 2D graphs and Knowledge Universe.
- [MCP and Agent Skill](https://sag.wiki/en/integrations/mcp): Mount an entire knowledge base or one source in Codex, Claude Code, and other agents.
- [OpenAI-compatible API](https://sag.wiki/en/integrations/openai-compatible): Call any SAG Agent through a cited Chat Completions-compatible endpoint.
- [REST API reference](https://sag.wiki/en/api): Authentication, resource map, request constraints, and examples for the self-hosted SAG API.
- [System architecture](https://sag.wiki/en/developer/architecture): Understand the boundaries between Web, API, Agent Runtime, and the zleap-sag engine.
- [zleap-sag Python engine](https://sag.wiki/en/developer/python-engine): Embed DataEngine directly and run the ingest, extract, and search lifecycle.
- [Local development](https://sag.wiki/en/developer/local-development): Set up frontend and backend development, then run the repository quality checks.
- [Production deployment](https://sag.wiki/en/operations/production): Deploy SAG with PostgreSQL/pgvector, HTTPS, and an external access-control layer.
- [Configuration reference](https://sag.wiki/en/operations/configuration): Environment variables for ports, models, parsing, storage, and background jobs.
- [Upgrade, backup, and restore](https://sag.wiki/en/operations/upgrade): Update containers and desktop apps while protecting databases, indexes, and uploads.
- [Troubleshooting](https://sag.wiki/en/operations/troubleshooting): Diagnose common failures across readiness, background jobs, model settings, and networking.
- [Paper and benchmarks](https://sag.wiki/en/project/paper): SAG's original architecture, query-time dynamic hyperedges, and public multi-hop results.
- [Changelog](https://sag.wiki/en/project/changelog): Important changes in public SAG releases and the current main branch.
- [Contributing and license](https://sag.wiki/en/project/contributing): Contribute to SAG and distribute changes under the MIT License.

## 中文文档

- [认识 SAG](https://sag.wiki/guide/introduction): 理解 SAG 的产品边界、核心能力与 event-entity 检索模型。
- [安装与启动](https://sag.wiki/guide/installation): 选择桌面客户端或 Docker，在本机启动完整 SAG 工作台。
- [第一个知识库](https://sag.wiki/guide/first-knowledge-base): 从首次登录、模型配置到导入文档并得到第一条可溯源回答。
- [导入与解析](https://sag.wiki/guide/ingestion): 了解文件、网页、Markdown 规范化、分块与后台索引流程。
- [检索与原文溯源](https://sag.wiki/guide/search): 使用快速与精确模式检索，并核对每条结果对应的原始证据。
- [Agent 对话](https://sag.wiki/guide/agent-chat): 管理知识范围、附件、会话，并获得流式且带引用的回答。
- [知识宇宙与图谱](https://sag.wiki/guide/explore): 在二维图谱与知识宇宙中探索事件、实体、时间线和原文。
- [MCP 与 Agent Skill](https://sag.wiki/integrations/mcp): 将整库或单一信源挂载到 Codex、Claude Code 等 Agent。
- [OpenAI 兼容接口](https://sag.wiki/integrations/openai-compatible): 把任意 SAG Agent 作为兼容 Chat Completions 的带引用模型调用。
- [REST API 参考](https://sag.wiki/api): SAG 自托管 API 的认证、资源地图、请求约束与常用示例。
- [系统架构](https://sag.wiki/developer/architecture): 理解 Web、API、Agent Runtime 与 zleap-sag 引擎之间的边界。
- [zleap-sag Python 引擎](https://sag.wiki/developer/python-engine): 直接嵌入 DataEngine，完成 ingest、extract 与 search 生命周期。
- [本地开发](https://sag.wiki/developer/local-development): 搭建前后端开发环境，理解仓库结构与质量检查命令。
- [生产部署](https://sag.wiki/operations/production): 使用 PostgreSQL/pgvector、HTTPS 与外部访问控制部署 SAG。
- [配置参考](https://sag.wiki/operations/configuration): 端口、模型、解析、存储与后台任务相关环境变量说明。
- [升级、备份与恢复](https://sag.wiki/operations/upgrade): 安全更新容器和桌面客户端，并保护数据库、索引与上传文件。
- [故障排查](https://sag.wiki/operations/troubleshooting): 从健康检查、后台任务、模型配置和网络路径定位常见问题。
- [论文与基准](https://sag.wiki/project/paper): SAG 原创架构、查询时动态超边与公开多跳检索结果。
- [更新日志](https://sag.wiki/project/changelog): SAG 公开版本与当前 main 分支的重要变化。
- [贡献与许可](https://sag.wiki/project/contributing): 参与 SAG 开发、提交变更并遵循 MIT 许可。