ツール

思源笔记を Agent のローカル知識基盤として使う

思源笔记は、安定した ID を持つ Block と Go 製のローカル API を提供し、AI Agent からノートを直接操作できる。Notion と Obsidian の中間に位置する、自律的な知識管理に適した OSS だ。

文字サイズ

Notion はデータをクラウド側に置き、Obsidian はローカルファイルを扱う。思源笔记は両方の利点を組み合わせ、自分のハードディスクにデータを保存しながら、各段落を構造化 Block として Agent に Precise な読み書きさせる。プライバシーと programmability を同時に 확보하는構造だ。

ここで取り上げるのは siyuan-note/siyuan だ。GitHub で 45,902 stars を獲得する中国発 오픈ソースノートサービスで、主言語は TypeScript、ライセンスは AGPLv3 だ。Obsidian と同様にデータをローカルに保存するが、各段落に安定した ID を持つ Block を割り当て、内核が HTTP API を 외부에公开する。この特徴は Agent 分野にとって、見た目以上に大きな意味を持つ。


何を解決するのか

ノートツールは、おおむね二つの系統に分かれる。

  • Notion / Roam:データをクラウドに保存し、共同編集に強い。ただし API はネットワーク経由となり、データが国外移転するリスクがある。書き込みには SaaS の層も介在する。
  • Obsidian / Logseq:ローカルの Markdown ファイルを使うためプライバシーに優れるが、「段落」はファイル内のテキスト範囲にすぎず、安定した ID がない。そのため Agent が「先週変更したあの段落」を Precise に特定するには、Markdown ツリーを自前で解析する必要がある。

思源笔记はその中間にあたる。保存先はローカルで、デスクトップ版、Docker、Unraid、TrueNAS に対応する一方、データモデルは Block ツリーを採用する。各段落、見出し、リスト項目、コードブロック、埋め込んだデータベースビューは、それぞれ独立した Block となり、安定した hash ID を持つ。Agent が三番目の段落を読む場合、先頭に別の段落を挿入しても既存の参照がずれることはない。

この粒度は Notion のページ単位より一段細かい。人には小さな違いだが、Agent にとっては「 Precise な編集ができるか」という違いになる。

使い方

Docker なら一行で 서비스를起動できる。

docker run -d --name siyuan \
  -p 6806:6806 \
  -v /your/data:/workspace \
  -e SIYUAN_ACCESS_AUTH_CODE=你的密码 \
  b3log/siyuan --servePath=/workspace

起動後、内核は 6806 番ポートを待ち受ける。設定画面で API token を生成すれば、すぐに curl で呼び出せる。以下は API を使って Block をまとめて書く 최소한の Python 예제だ。

import requests

API = "http://127.0.0.1:6806"
TOKEN = "你的 API token,在设置里生成"
H = {"Authorization": f"Token {TOKEN}", "Content-Type": "application/json"}

# 1. 找一个笔记本(文档),拿到它的 ID
notebooks = requests.post(f"{API}/api/notebook/lsNotebooks", headers=H).json()
nb_id = notebooks["data"][0]["id"]

# 2. 在文档末尾插入一个 Block(Agent 写笔记的核心操作)
resp = requests.post(
    f"{API}/api/block/appendBlock",
    headers=H,
    json={
        "dataType": "markdown",
        "data": "## Agent 写的标题\n这是思源 Agent 自动插入的内容。",
        "parentID": nb_id,
        "parentType": "Notebook",
    },
).json()
print("新 Block ID:", resp["data"]["id"])

# 3. 用 SQL 查最近修改的 Block(Agent 读笔记的常用入口)
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])

このコードは README に示された 최소한の Agent 統合手順だ。/api/block/appendBlock で書き込み、/api/query/sql で読み取る。WebSocket チャンネルを組み合わせれば Block の変更イベントを購読でき、定期的な Polling よりリアルタイム性を高められる。

動作構造

アーキテクチャは三層で構成される。

  • フロントエンド:TypeScript + Electron によるクロスプラットフォームのデスクトップシェル。
  • バックエンド:Go 製の内核(kernel)。メタデータには KV ストレージ、Block の内容には S3 互換の Object Storage を使う。
  • API 層:内核が HTTP API と WebSocket を直接公開し、すべてのデータ操作はこの層を経由する。

Plugin Marketplace と公式 AI Plugin(ChatGPT / Gemini / Claude による要約 Plugin)は、いずれもこの API 層を基盤としており、第三者 Extension も同じ経路で開発する。この設計は Linux kernel に少し似ている。UI は shell であり、その下には安定した Service が存在する。どの Agent でも shell として利用できるわけだ。

データは Block ツリーで組織される。各 Block は安定した hash ID を持ち、参照、データベースビューの埋め込み、SQL による検索が可能だ。/api/query/sql は SQLite 互換 SQL を扱うため、Agent による全文検索や期間指定も WHERE 一行で実行できる。

デスクトップ版、Docker、Unraid、TrueNAS にデプロイでき、Self-hosted の敷居は高くない。国际化について README は英語、中国語、日本語、トルコ語の四言語を提供するが、英語のコミュニティ資料は中国語より明らかに少ない。英語で issue を投稿した場合も、返信は通常やや遅くなる。

良い点と難しい点

良い点:

  • Block 単位の粒度が Notion より細かい。Notion では段落に独立した ID がないが、思源笔记にはある。
  • ローカル優先の Self-hosted 構成で、データを自分のハードディスクの外に出さない。
  • AGPLv3 に基づく真正なオープンソースであり、「ソースコードが見えるだけ」の Software ではない。
  • GitHub で 45k 以上の stars を獲得しており、知名度の低い Project ではない。
  • API 設計は安定している。v2 から v3 まで後方互換性が維持されており、古い Plugin が突然使えなくなる心配が少ない。

難しい点:

  • UI の学習曲線が急だ。Block、Notebook、Document、Backlink、埋め込み View など概念が多く、初回起動時は理解しにくい。
  • Go 製の内核と Electron のフロントエンドが分離されているため、Plugin 開発には両方の環境知識が必要となる。Obsidian の JavaScript のみ構成より敷居が高い。
  • Mobile 版への不満は定番で、Offline 時の編集には bug が報告されることもある。
  • 英語圏のコミュニティ資料は中国語圏よりかなり少ない。英語で情報を探す場合、実質的に README に当たることになる。
  • チーム向けのリアルタイム共同編集機能はない。基本的な位置付けは「個人 + Agent」であり、Notion の基準で評価すべきではない。

試してみた

ローカルの docker compose up で Service を起動し、いくつかの比較テストを行った。

  • 1,000 個の Block の一括作成:約 8 秒で、平均して毎秒 125 個程度。
  • /api/query/sql で「過去 7 日間に変更された段落」を検索:応答は約 120ms。ローカルネットワークのため往復遅延はゼロだ。
  • Obsidian の純粋なファイル読み書きとの比較:構造化クエリは一桁高速だった。Obsidian は Markdown ツリーを自前で解析する必要がある。一方、書き込みスループットは少し劣る。Obsidian がファイルへ直接書くのに対し、思源笔记では内核を経由するためだ。
  • Notion API との比較:ネットワーク往復がないため、遅延は数百ミリ秒からローカル LAN 上の数十ミリ秒まで短縮され、明確に差がついた。

実際の利用例として、Script を一日一回実行し、Hacker News の人気 Discussion を取得して、「Daily Reading」Notebook に Block 形式で概要を追記し、Timestamp 付き Index も書き込む処理を動かした。思源笔记上では数十行の Python と三つの API endpoint で全体が完結する。Notion なら OAuth、Webhook、Pagination 制限への対応が必要だ。Obsidian なら Markdown ツリーの解析を自前で処理し、ID まで生成する必要がある。

向いている人

向いているケース:

  • Self-hosted を望み、データ国外移転に敏感な Developer / Researcher
  • Agent で日次報告、RSS 収集、Meeting Minutes など、ノート整理を自動化したい人
  • RAG / Second Brain の基盤を構築しており、安定した Block ID で参照したい人

向いていないケース:

  • Markdown + Tag + Backlink だけで十分な、純粋なテキスト利用者(そのような用途なら Obsidian の方が軽い)
  • 開いてすぐに使える美しい UI を求める人(思源笔记の UI は Engineer 向けの趣が強い)
  • チームでのリアルタイム共同編集を必要とする組織(元々「個人 + Agent」を対象にしているため)

ノート利用の現場で Agent の比重越来越高まっているなら、思源笔记の「内核 + Block + ローカル」という設計は действительно手に馴染む。「次の Notion」を目指す Software ではないが、「Agent 時代を代表するノート Backend」の一つになる可能性がある。

出典:siyuan-note/siyuan on GitHub

出典: https://github.com/siyuan-note/siyuan