# SiYuan

Block-based local-first knowledge base whose Go kernel ships a 30-plus tool MCP server and HTTP API.

SiYuan is a privacy-first personal knowledge manager with block-level references, databases, daily notes, and an SQL query layer, available as desktop, mobile, and a Docker-served kernel. The kernel exposes an HTTP API (API.md) and an in-kernel MCP server (kernel/mcp) with tools for notebooks, documents, blocks, search, SQL, attributes, assets, export, sync, and even web search. Core is free and AGPL; sync and some features are paid.

Alternative to: Notion, Obsidian

- Capabilities: adaptable, operable
- Vertical: notes-knowledge
- Shape: product
- Form factor: desktop
- Execution model: hybrid
- Provenance: mixed (recorded, never ranked)
- Repo: https://github.com/siyuan-note/siyuan (AGPL-3.0), 46138 stars, last commit 2026-09-03
- Last activity: 2026-09-03
- Page: apps/siyuan-note--siyuan.html
- JSON: apps/siyuan-note--siyuan.json

## Use it when

- you want block references and databases like Notion, stored locally, with an agent that can query them by SQL
- you run a Docker kernel on your NAS and want daily notes written by an agent from the terminal

## Gotchas

- AGPL-3.0
- Since v3.7.0 the Docker image needs an explicit serve subcommand
- Official cloud sync and some features are paid; third-party S3/WebDAV sync needs PRO Features
- Docker web UI is protected only by the access auth code unless OIDC is set

## Editions

- Free: Free, open source
  - source: https://github.com/siyuan-note/siyuan
  - binary: https://b3log.org/siyuan/en/download.html
  - container: docker run -d b3log/siyuan serve --workspace=/siyuan/workspace
- PRO Features: $64 lifetime, closed source
  - hosted: https://b3log.org/siyuan/en/pricing.html
- Subscription: $148 per year, closed source
  - hosted: https://b3log.org/siyuan/en/pricing.html

## Adaptable: make it yours

Effort: config-only (10 things to edit)

Docker serve mode is env-driven: SIYUAN_WORKSPACE_PATH, SIYUAN_ACCESS_AUTH_CODE (or SIYUAN_ACCESS_AUTH_CODE_BYPASS), SIYUAN_LANG, PUID and PGID, and an OIDC block (SIYUAN_OIDC_ENABLED, SIYUAN_OIDC_PROVIDER, SIYUAN_OIDC_REDIRECT_URL) that replaces the lock-screen code. The README carries docker-compose, Unraid, and TrueNAS examples. Desktop settings live in the UI.

- Env vars: SIYUAN_WORKSPACE_PATH, SIYUAN_ACCESS_AUTH_CODE, SIYUAN_ACCESS_AUTH_CODE_BYPASS, SIYUAN_OIDC_ENABLED, SIYUAN_OIDC_PROVIDER, SIYUAN_OIDC_REDIRECT_URL, SIYUAN_LANG, PUID, PGID
- Config files: docker-compose.yml
- Prompt files: none
- Accounts you'll need: OpenAI (optional, AI writing); SiYuan account (paid sync and PRO features); S3 or WebDAV provider (PRO third-party sync)

## Operable: what an agent can drive

Operability: official. Interface: mcp at https://github.com/siyuan-note/siyuan/tree/master/kernel/mcp (published by the builder, local).

### Reach (partial coverage)

- Notebooks and documents: reachable. kernel/mcp/tools notebook.go, document.go
- Block-level read, insert, update, and move: reachable. block.go
- Search and SQL queries: reachable. search.go, sql.go
- Attributes, tags, bookmarks, and references: reachable. attr.go, tag.go, bookmark.go, ref.go
- Daily notes and templates: reachable. dailynote.go, template.go
- Databases (attribute views): reachable. database.go
- Assets, files, and images: reachable. asset.go, file.go, image.go
- Export, import, history, and snapshots: reachable. export.go, import.go, history.go, repo.go
- Sync and workspace management: reachable. sync.go, workspace.go, system.go
- Plugins and marketplace, AI writing UI: not reachable. no plugin tool in kernel/mcp/tools; AI writing is a UI feature over the OpenAI API

## Code stack

- Languages: Go, TypeScript
- Frameworks: Electron, Gin
- Package manager: go modules, pnpm
- Database: SQLite
- Hosting target: binary, docker

## Model stack

- Providers: OpenAI API (AI writing and chat)
- Models: none
- Keys you need (names only): none
- Prompts live in: none
- Tools: notebook, document, block, search, sql, attr, tag, bookmark, dailynote, database, asset, file, image, export, import, history, sync, template, inbox, todo_write, ref, outline, repo, workspace, system, web_fetch, web_search, question, skill

## Evidence and confidence

- formFactor: README: desktop app from app stores and installers; Docker serves the same kernel with a web UI (confidence 0.7)
- executionModel: AI writing and Q/A through OpenAI API; MCP tools include web_search and question; notes work without a model (confidence 0.75)
- operability: kernel/mcp/tools in the repo with 30-plus tool files; tagline 'From thought to insight, with agents' (confidence 0.9)
- effort: README Docker section names SIYUAN_* env vars (confidence 0.9)
- editions: b3log.org/siyuan/en/pricing.html: core free, PRO Features $64 lifetime, Subscription $148/year (confidence 0.85)
- active: pushedAt 2026-09-03
- provenance: AGENTS.md at root; project from 2020 (confidence 0.4)
- reach:  (confidence 0.85)

## Open questions

- Is the level native rather than official? The Builder now leads with agents but the app predates them
- Does the MCP server require the paid tier for any tool (sync, web_search)?

## Sources

- https://github.com/siyuan-note/siyuan (sourcing:notes-knowledge:curated)
- https://b3log.org/siyuan/en/pricing.html (analysis)
- https://github.com/siyuan-note/siyuan/tree/master/kernel/mcp/tools (analysis)