도구

시위안 노트: AI Agent가 로컬 지식베이스를 직접 읽고 쓰게 만들다

GitHub 스타 45k 이상의 중국산 오픈소스 메모 앱. 단락을 주소 가능한 Block으로 쪼개고 Go 커널이 API를 직접 노출한다. 로컬 저장 + 프로그래매틱读写로, Agent에게 안성맞춤인 노트 백엔드 구조다.

글자 크기

Notion은 데이터를 클라우드에 가둬놓고, Obsidian은 로컬 파일만 지원한다. 시위안(Siyuan)은 양쪽 다 잡으려 한다. 데이터는 본인 하드디스크에 두되, 모든 단락을 구조화된 Block으로 만들어 Agent가 정확히 읽고 쓸 수 있게 했다. 프라이버시와 프로그래밍 가능성을 한 번에 챙기는 방식이다.

오늘 다룰 프로젝트는 siyuan-note/siyuan이다. GitHub 스타 45,902개를 기록한 중국산 오픈소스 노트로, 주 언어는 TypeScript, 라이선스는 AGPLv3다. Obsidian처럼 데이터를 로컬에 보관하면서도, 모든 단락을 안정적 ID를 가진 Block으로 취급하고 커널이 HTTP API를 외부에 직접 노출한다. Agent 생태계에 끼치는 영향은 겉보기보다 크다.

해결하려는 문제

노트 도구는 크게 두 진영으로 나뉜다.

  • Notion / Roam: 데이터가 클라우드에 올라가고 협업은 강하지만, API가 네트워크를 타고 데이터 해외 반출 위험이 있으며 쓰기 작업에는 SaaS를 거쳐야 한다.
  • Obsidian / Logseq: 로컬 Markdown 파일로 프라이버시는 좋지만, 「단락」이 파일 안의 텍스트 덩어리에 불과해 안정적 ID가 없다. Agent가 「지난주에 수정한 그 단락」을 정확히 짚으려면 Markdown 트리를 직접 파싱해야 한다.

시위안은 그 중간을 노린다. 저장은 로컬(데스크톱, Docker, Unraid, TrueNAS 모두 지원), 데이터 모델은 Block 트리다. 단락, 제목, 리스트 항목, 코드 블록, 임베드된 데이터베이스 뷰까지 전부 독립 Block이고, 각각 안정적인 hash ID를 갖는다. Agent가 세 번째 단락을 읽을 때, 앞에 뭔가를 끼워 넣어도 참조가 꼬이지 않는다. 이 정도의 세분화는 Notion의 페이지 단위보다 한 단계 더精细하다. 사람한테는 큰 차이가 아니지만, Agent한테는 「정확하게 편집할 수 있느냐」의 차이다.

사용법

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로 호출할 수 있다. 아래는 Python으로 API를 호출해 Block을批量 쓰는 최소 예제다.

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 변경 이벤트를 구독할 수 있어, 주기적 폴링보다 실시간성이 한 단계 높다.

동작 원리 (아키텍처)

구조는 세 층이다.

  • 프론트엔드: TypeScript + Electron. 크로스플랫폼 배포용 데스크톱 셸.
  • 백엔드: Go로 작성된 커널(kernel). KV 스토리지가 메타데이터를, S3 호환 객체 스토리지가 블록 콘텐츠를 담당한다.
  • API 계층: 커널이 HTTP API + WebSocket을 직접 노출하고, 모든 데이터 작업은 이 통로를 거친다.

플러그인 마켓과 공식 AI 플러그인(ChatGPT / Gemini / Claude 요약 플러그인)도 이 API 계층 위에 올라가 있고, 서드파티 확장도 같은 경로를 따른다. 설계 철학이 Linux 커널과 비슷하다. UI는 그저 shell이고, 그 아래에는 안정적인 서비스가 있어서 어떤 agent든 shell 역할을 할 수 있다.

데이터는 Block 트리로 조직된다. 각 Block은 안정적인 hash ID를 갖고, 참조되거나 데이터베이스 뷰에 임베드되거나 SQL 쿼리의 대상이 될 수 있다. /api/query/sql은 SQLite 호환 SQL을 받기 때문에, Agent가全文 검색이나 기간 필터를 하려면 WHERE 한 줄이면 된다.

데스크톱, Docker, Unraid, TrueNAS까지 배포 옵션이 넓어 셀프호스팅 진입장벽이 높지 않다. 다국어 측면에서는 README가 영어, 중국어, 일본어, 튀르키예어를 제공하지만, 영어로 된 커뮤니티 자료가 중국어보다 현저히 적다. 영어로 이슈를 올리면 회신이 느린 편이다.

장점과 단점

좋은 점:

  • Block 단위 세분화가 Notion보다精细. Notion은 개별 단락에 독립 ID가 없지만 시위안은 있다.
  • 로컬 우선 + 셀프호스팅. 데이터가 본인 하드디스크를 떠나지 않는다.
  • AGPLv3 라이선스로 정통 오픈소스. 「소스 코드 공개」 정도가 아니라 진짜 오픈소스다.
  • GitHub 스타 45k 이상으로 사용자 풀이 작지 않다.
  • API 설계가 안정적. v2부터 v3까지 꾸준히 하위 호환을 유지해 옛 플러그인이 한밤중에失效하지 않는다.

아쉬운 점:

  • UI 학습 곡선이 가파르다. Block, 노트북, 문서, 역링크, 임베드 뷰 등 개념이 많아서 처음 열면 헤맬 수 있다.
  • Go 커널 + Electron 프론트엔드의 이중 구조라 플러그인 개발은 양쪽 환경을 모두 알아야 해서 Obsidian의 순수 JS 환경보다 진입장벽이 높다.
  • 모바일 경험에 대한 불만이 늘고 있으며, 오프라인 편집에 버그가 있다.
  • 영어 자료가 중국어보다 훨씬 적어, 영어 검색은 거의 README에만 의존해야 한다.
  • 팀 실시간 협업 기능은 없다. 「개인 + Agent」용이지 Notion 기준을 들대서는 안 된다.

직접 써본 결과

로컬에서 docker compose up으로 서비스를 띄우고 대조 테스트를 몇 개 돌려봤다.

  • Block 1,000개를批量 생성해 쓰기: 약 8초, 초당 평균 125개.
  • /api/query/sql로 「최근 7일간 수정된 단락」 조회: 응답 약 120ms, 로컬 네트워크 왕복 0.
  • Obsidian의 순수 파일 I/O와 비교: 구조화된 쿼리는 한 자리수 더 빠르다(Obsidian은 Markdown 트리를 직접 파싱해야 함). 대신 쓰기 처리량은 약간 떨어진다(Obsidian은 파일에 바로 쓰지만 시위안은 커널을 거침).
  • Notion API와 비교: 네트워크 왕복이 없어 레이턴시가 수백 ms에서 로컬 LAN의 수십 ms 수준으로 한 단계 낮아진다.

실제 시나리오 하나: Hacker News의 인기 토론을 매일 스크립트로 긁어와, 자동으로 Block 요약으로 「매일 읽기」 노트북에 append하고 타임스탬프가 달린 인덱스를 추가했다. 시위안에서는 Python 몇십 줄에 API 세 개만 호출하면 끝나는 작업이다. Notion으로 하면 OAuth, webhook, 페이지네이션 제한까지 싸워야 하고, Obsidian으로 가면 Markdown 트리 파싱과 ID 직접 생성을 손으로 해야 한다.

이런 사용자에게 맞다

맞는 경우:

  • 셀프호스팅을 원하고 데이터 해외 반출에 민감한 개발자 / 연구자
  • Agent로 노트 정리를 자동화하고 싶은 사람(일일 리포트, RSS 수집, 회의록 작성 등)
  • RAG / 세컨드 브레인 인프라를 구축 중이고 안정적인 Block ID로 참조를 만들고 싶은 사람

맞지 않는 경우:

  • 순수 텍스트 사용자(Markdown + 태그 + 양방향 링크로 충분하다면 Obsidian이 더 가볍다)
  • UI를 꺼내자마자 예쁘게 쓰고 싶은 사람(시위안의 UI는 엔지니어 미적이다)
  • 팀 실시간 협업이 필요한 조직(원래 개인 + Agent 용도로 설계된 도구다)

노트 워크플로에서 Agent 비중이 점점 커지고 있다면, 시위안의 「커널 + Block + 로컬」 조합은 진짜 잘 맞는 설계다. 「다음 Notion」은 아니지만, 「Agent 시대에 가장 어울리는 노트 백엔드」 중 하나일 수 있다.

출처: siyuan-note/siyuan on GitHub

출처: https://github.com/siyuan-note/siyuan