# SiYuan

> A self-hosted, block-level knowledge base you can query, script and point an LLM at

- Category: AI Productivity & Writing / Notes & Knowledge Bases
- Language: TypeScript
- Licence: AGPL-3.0
- Repository: https://github.com/siyuan-note/siyuan
- Website: https://b3log.org/siyuan
- Canonical page: https://ai-tldr.dev/tools/siyuan/

## In short

SiYuan is a privacy-first personal knowledge management system built around content blocks. It sits in the Notes & Knowledge Bases category of the AI Productivity & Writing tools and is open-source, written in TypeScript and licensed AGPL-3.0. To get started: install the app.

## Overview

SiYuan is a privacy-first personal knowledge management system built around content blocks. Every block can be referenced and back-linked, carry custom attributes, be addressed by a `siyuan://` URL, and be pulled into a document by an embedded SQL query — which is what separates it from a folder of Markdown files. The editor is block-style Markdown WYSIWYG with list outlining, block zoom-in, math and diagram rendering, web clipping and PDF annotation links, and it is built to survive million-word documents.

Data lives on your own machine or your own server. It ships as desktop apps, Android, iOS and HarmonyOS apps, and a Docker image (`b3log/siyuan`) for self-hosting, where the `serve` subcommand takes a workspace path and an access code, with optional OIDC authentication against Google, Microsoft, GitHub or a custom provider. A built-in CLI reads and writes workspace data without a running server: notebooks, documents, blocks, attributes, tags, bookmarks, templates, full-text and SQL queries, backlinks, import/export, snapshots and sync — with `-f json` output for scripting and `--dry-run` on mutating commands.

The AI surface is deliberately modest: AI writing and question-answering through an OpenAI-compatible API, Tesseract OCR on assets, plus an HTTP API and a community marketplace of plugins, themes and templates that other tools (including MCP bridges) build on. Spaced-repetition flashcards, a table database view, JavaScript/CSS snippets and export to PDF, Word, HTML or standard Markdown round it out. The code is AGPL-3.0; most features are free, including for commercial use, while cloud sync and some extras are reserved for paid members.

## What it does

- Block-level references, two-way links, custom attributes and embedded SQL queries over your notes
- Markdown WYSIWYG editing with outlining, block zoom, formulas, diagrams, web clipping and PDF annotation
- Self-hosting via Docker with workspace mounting, access codes and optional OIDC login
- A scriptable CLI for notebooks, blocks, search, SQL, export/import, snapshots and sync — JSON output, `--dry-run`
- AI writing and Q&A chat through an OpenAI-compatible API, plus Tesseract OCR
- Spaced-repetition flashcards, database table views, plugin API and a community marketplace

## Getting started

Install the app from a store or package, or self-host the kernel with Docker. The CLI works against a workspace directory directly.

1. Install the app

   The project recommends the app stores so upgrades are one click; installers and packages are also published on B3log and GitHub Releases.

2. Or self-host with Docker

   Since v3.7.0 the `serve` subcommand must be passed explicitly. Mount a workspace directory and set the lock-screen access code.

```bash
docker run -d \
  -v workspace_dir_host:workspace_dir_container \
  -p 6806:6806 \
  -e PUID=1001 -e PGID=1002 \
  b3log/siyuan \
  serve \
  --workspace=workspace_dir_container \
  --accessAuthCode=xxx
```

3. Wire up the CLI

   The binary lives inside the installed app; symlink it onto your PATH (macOS shown; Linux is the same against your install directory).

```bash
ln -s /Applications/SiYuan.app/Contents/Resources/kernel/SiYuan-Kernel /usr/local/bin/siyuan
```

4. Query the workspace from a script

   Every command takes `-w <workspace>`; `-f json` makes the output script-friendly.

```bash
siyuan notebook list -w ~/SiYuan
siyuan search "keyword" -w ~/SiYuan -f json
siyuan export md --id <block-id> -w ~/SiYuan
```

## When to use it

- Keep a personal or team knowledge base on hardware you control instead of a hosted notes SaaS
- Build structured notes where SQL queries over blocks assemble views instead of copy-pasting
- Feed an assistant your own notes through the CLI, HTTP API or a marketplace plugin
- Study with spaced repetition over the same blocks you write in