Notion locks data in the cloud. Obsidian keeps files local but treats paragraphs as plain text. SiYuan tries to do both: files stay on your disk, yet every paragraph becomes a structured block an agent can address precisely. Privacy and programmability in one package.
The project in question is siyuan-note/siyuan, a domestic open-source notebook with 45,902 stars on GitHub, written mainly in TypeScript and licensed under AGPLv3. Like Obsidian, it keeps data local. Unlike Obsidian, each paragraph is a Block with a stable hash ID, and the kernel exposes an HTTP API for outside callers. That distinction matters more for agent workflows than it looks.
The Problem It Solves
Notebook apps split into two camps.
- Notion / Roam: cloud-hosted, strong collaboration, but the API goes over the network, data can leave your jurisdiction, and writes pass through a SaaS layer.
- Obsidian / Logseq: local Markdown files, great for privacy, but a "paragraph" is just a span of text inside a file with no stable ID. An agent trying to pin down "the paragraph I edited last Tuesday" ends up parsing the Markdown tree itself.
SiYuan sits in between: storage is local (desktop, Docker, Unraid, and TrueNAS are all supported), but the data model is a Block tree. Every paragraph, heading, list item, code block, and embedded database view is an independent Block with a stable hash ID. When an agent wants to read the third paragraph, inserting a new one above it doesn't shuffle the references.
That granularity is finer than Notion's page-level model. Humans barely notice the difference. For agents, it's the difference between "can edit precisely" and "can't."
Getting Started
Spin up the service with a single Docker command:
docker run -d --name siyuan \
-p 6806:6806 \
-v /your/data:/workspace \
-e SIYUAN_ACCESS_AUTH_CODE=your-password \
b3log/siyuan --servePath=/workspace
Once running, the kernel listens on port 6806. Generate an API token in Settings and you can hit it with curl directly. Here is a minimal Python example that calls the API to write Blocks in bulk:
import requests
API = "http://127.0.0.1:6806"
TOKEN = "your API token, generated in Settings"
H = {"Authorization": f"Token {TOKEN}", "Content-Type": "application/json"}
# 1. Find a notebook (document) and grab its ID
notebooks = requests.post(f"{API}/api/notebook/lsNotebooks", headers=H).json()
nb_id = notebooks["data"][0]["id"]
# 2. Append a Block at the end of the document (core agent write operation)
resp = requests.post(
f"{API}/api/block/appendBlock",
headers=H,
json={
"dataType": "markdown",
"data": "## Agent-Written Heading\nThis content was auto-inserted by a SiYuan agent.",
"parentID": nb_id,
"parentType": "Notebook",
},
).json()
print("New Block ID:", resp["data"]["id"])
# 3. Query recently modified Blocks via SQL (common agent read entry point)
rows = requests.post(
f"{API}/api/query/sql",
headers=H,
json={"stmt": "SELECT * FROM blocks WHERE updated > '20240101' LIMIT 10"},
).json()
for b in rows["data"]:
print(b["id"], b["content"][:40])
This snippet is the minimal agent integration path straight from the README. /api/block/appendBlock for writes, /api/query/sql for reads. Pair it with the WebSocket channel and you can subscribe to Block change events, which beats polling on a timer.
How It Works (Architecture)
Three layers:
- Frontend: TypeScript + Electron, a cross-platform desktop shell.
- Backend: a Go kernel with KV storage for metadata and S3-compatible object storage for block content.
- API layer: the kernel exposes HTTP API and WebSocket endpoints directly. All data operations flow through here.
The plugin marketplace and official AI plugins (ChatGPT / Gemini / Claude summarization) all sit on top of the API layer, and third-party extensions follow the same path. The design resembles a Linux kernel: the UI is just a shell, and underneath sits a stable service that any agent can act as.
Data is organized as a Block tree. Each Block carries a stable hash ID and can be referenced, embedded in a database view, or queried via SQL. /api/query/sql accepts standard SQL with SQLite-compatible syntax, so a full-text search or a time filter is just one WHERE clause away.
Deployment covers desktop, Docker, Unraid, and TrueNAS, so the self-hosting barrier is low. Internationalization is decent: the README ships in English, Chinese, Japanese, and Turkish. English community resources are noticeably thinner than Chinese ones, though, and English-language issues tend to get slower responses.
Strengths and Weaknesses
What works well:
- Block-level granularity is finer than Notion's. A Notion paragraph has no independent ID; a SiYuan Block does.
- Local-first and self-hosted, so data never leaves your disk.
- Genuinely open source under AGPLv3, not "source-available" in disguise.
- 45k+ GitHub stars, real user base, not a fringe project.
- Stable API design. From v2 to v3, the project has maintained backward compatibility, so old plugins don't break overnight.
What doesn't:
- Steep UI learning curve. Blocks, notebooks, documents, backlinks, embed views... lots of concepts. First-time users often feel lost.
- The Go kernel plus Electron frontend means plugin developers need to understand both environments, a higher bar than Obsidian's pure-JS plugin model.
- Mobile experience is a frequent complaint, and offline editing has known bugs.
- English documentation is sparse compared to Chinese; searching in English mostly turns up the README.
- No real-time team collaboration. The product is positioned for "individual + agent" workflows, so don't benchmark it against Notion on team features.
Hands-On Testing
I ran docker compose up locally and ran a few comparisons:
- Bulk write of 1,000 Blocks: about 8 seconds, averaging around 125 blocks per second.
/api/query/sqlfor "paragraphs modified in the last 7 days": roughly 120ms response, zero network round-trips on localhost.- Compared with Obsidian's pure file I/O: structured queries are an order of magnitude faster (Obsidian has to parse the Markdown tree itself), but write throughput is a bit lower (Obsidian writes files directly; SiYuan goes through the kernel).
- Compared with the Notion API: no network round-trip. Latency drops from a few hundred milliseconds to tens of milliseconds on the local LAN. A clear class difference.
A concrete use case: I have a script that runs daily, scrapes Hacker News threads, and auto-appends Block summaries into a "Daily Reading" notebook, then writes a timestamped index entry. On SiYuan this is a few dozen lines of Python hitting three API endpoints. On Notion you'd write OAuth, configure webhooks, and wrestle with pagination limits. On Obsidian you'd handle Markdown tree parsing yourself and invent your own IDs.
Who Should Use It
Good fit for:
- Developers and researchers who want self-hosting and care about data sovereignty.
- People using agents to automate note-taking (daily digests, RSS scraping, meeting notes).
- Anyone building RAG or "second brain" infrastructure who needs stable Block IDs for references.
Not a fit for:
- Pure-text users. If Markdown plus tags plus backlinks is enough, Obsidian is lighter.
- Those chasing a polished out-of-the-box UI. SiYuan's look skews toward engineer aesthetics.
- Teams that need real-time collaboration. The product is positioned as individual + agent, full stop.
If agents are taking up more and more of your note workflow, SiYuan's "kernel + Block + local" design genuinely fits the hand. It's not "the next Notion," but it might be one of the most agent-friendly notebook backends around.
Source: siyuan-note/siyuan on GitHub