SiYuan
An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents collaborate.
Evidence shows: README emphasizes privacy-first, local data storage, provides access auth code and Docker permission control (PUID/PGID), but lacks detailed least-privilege design or user confirmation mechanisms. Data flow transparency is limited; no clear explanation of how data is processed or transmitted. Sensitive data handling mentions data repository key and encryption but lacks details. Dependency security has go.mod and package.json but no vulnerability scanning or audit evidence. External effects include network services and export features but no impact scope. Rollback has data repository reset and snapshot features but no explicit rollback mechanism. Source attribution has open-source license and contributor list but no detailed provenance. Therefore, scores are low due to insufficient or partial evidence.
Evidence shows: README and CI workflows provide build and release processes, but no test results or error handling details. Self-consistency is generally consistent between docs and code structure but not verified. Dependency availability lists multiple dependent projects but no availability guarantees. Failure messages lack specific error handling or user prompts. Hence, scores are moderate to low.
Evidence shows: README describes multiple usage scenarios (desktop, mobile, Docker) and provides CLI and API, but capability boundaries are not explicit. Audience and scenarios cover personal knowledge management but target users are not specified. Trigger precision lacks specific trigger mechanisms. Environment fit supports multiple platforms and deployment methods but lacks detailed configuration instructions. Hence, scores are moderate.
Evidence shows: README is well-structured with installation, usage, FAQ, but lacks complete API documentation or comprehensive known limitations. Information architecture is well-organized. Install notes provide multiple installation methods. Naming stability is consistent. Examples and FAQ are provided. Known limitations are mentioned in Docker section but not comprehensive. License is clearly AGPL-3.0. Versioning and changelog exist with CHANGELOG.md and version numbers. Maintenance responsibility is indicated by contribution guide and community. Hence, scores are moderate.
Evidence shows: README describes rich features but no performance or cost data. Output usability provides multiple export formats. Marginal value as open-source project offers free features. Cost-benefit lacks specific cost analysis. Hence, scores are moderate.
Evidence shows: Claims in README lack specific evidence or citations. Traceability lacks source links. Cross-source corroboration lacks multiple sources. Fact-inference separation is not explicit. Hence, scores are low.
- This repository is a knowledge management application, not a dedicated AI agent framework; its agent capabilities are limited. Assessment should account for this.
- Publisher identity is unverified; treat as unknown and do not infer safety from brand.
- Static review cannot verify runtime behavior; all scores are based on documentation and code structure, with low confidence.
What does this agent do, and when should you use it?
SiYuan is an open-source (AGPL-3.0), privacy-first personal knowledge management system that supports fine-grained block-level reference and Markdown WYSIWYG editing. Data is stored locally by default in a workspace folder, with an optional end-to-end encrypted data repository and cloud sync (member privilege). It features a full desktop (Electron) and mobile app, can be self-hosted via Docker, and provides a command-line interface (CLI) for direct access to workspace data without a running server. The ecosystem includes a plugin API (petal), community marketplace (bazaar), Chrome clipper extension, and Android/iOS/HarmonyOS apps. The core editor engine is Lute, and the data repository is handled by dejavu. Features include block-level links, database views, flashcard spaced repetition, AI writing via OpenAI API, and OCR.
SiYuan stores content as JSON (.sy files) in the workspace's data folder, including assets, templates, plugins, and notebook folders. The core kernel program (SiYuan-Kernel) runs as an HTTP server, providing an API and WebSocket interface. The built-in CLI (via the siyuan command) directly reads and writes data, e.g., siyuan notebook list -w ~/SiYuan, siyuan search "keyword" -w ~/SiYuan -f json, and siyuan export md --id <block-id> -w ~/SiYuan. The editor supports block-level references, bidirectional links, SQL query embeds, Markdown WYSIWYG, and exports to Markdown, PDF, Word, and HTML. It offers AI writing and Q/A chat via OpenAI API, and Tesseract OCR. Deployment options include desktop installers, Docker images (b3log/siyuan), and the CLI.
- Knowledge workers who want complete control over their notes, storing data locally and syncing via encrypted repositories without relying on third-party cloud services.
- Teams that need a self-hosted knowledge base, deployed on internal servers via Docker and protected behind an NGINX reverse proxy.
- Researchers who require fine-grained block references and bidirectional links to build complex knowledge graphs.
- Users who track projects or literature with database views and embed SQL queries within notes.
- Language learners using flashcard spaced repetition to review content.
- Writers who need offline, local-first tools with export to Markdown or Word and web clipping capabilities.
What are this agent's strengths and limitations?
- Fine-grained block-level references and bidirectional links enable building complex knowledge networks.
- Local-first and privacy-preserving, storing data locally with optional end-to-end encrypted sync.
- Self-hostable via Docker, offering complete control over your data.
- Rich features: database views, flashcard spaced repetition, AI writing, and OCR.
- Third-party sync disks are not supported as they may corrupt data; sync is a paid member feature.
- Some features (like cloud sync and certain export options) require a paid membership.
- The Docker version does not support desktop/mobile app connections and only works in browsers; it lacks PDF/Word/HTML export and Markdown import.
- Configuration of reverse proxy and permissions (PUID/PGID) adds complexity for non-technical users.
How do you install or deploy this agent?
Multiple installation methods:
- Desktop: Download from the official site (b3log.org/siyuan) or GitHub Releases, or via Microsoft Store (Windows), App Store (iOS), Google Play/F-Droid (Android).
- Docker self-hosting: Use the image b3log/siyuan. Run docker run -d -v /siyuan/workspace:/siyuan/workspace -p 6806:6806 -e PUID=1001 -e PGID=1002 b3log/siyuan serve --workspace=/siyuan/workspace/ --accessAuthCode=xxx. Ensure the workspace folder ownership matches PUID/PGID.
- CLI: The binary is located at <install-dir>/resources/kernel/SiYuan-Kernel; Windows installer adds it to PATH automatically; macOS and Linux require creating a symlink.
How do you use this agent?
After installation, launch the desktop app or start the Docker container with docker run. Access http://localhost:6806 in a browser (Docker) or open the desktop client. Set workspace path and lock screen password on first run. Use the editor to create notes with Markdown shortcuts and block operations. The CLI can be used: siyuan notebook list -w ~/SiYuan to list notebooks, siyuan search "keyword" -w ~/SiYuan -f json to search full-text, and siyuan export md --id <block-id> -w ~/SiYuan to export. For synchronization and encryption, configure the data repository key in settings.
How does this agent compare with similar options?
SiYuan competes with tools like Obsidian and Notion in the block-reference and knowledge management space, but the README does not explicitly name specific competitors.
FAQ
Is SiYuan completely free?
Where is my data stored and how can I back it up?
data). You can back up by exporting data or copying the entire data directory.