이 레포가 무엇을 하는 물건인가.
원칙이 9개나 명시돼 있지만 요점은 셋입니다: Files-first(노트는 평범한 마크다운 + YAML 프런트매터), Git-first(볼트가 곧 git 저장소 — 버전 이력·원격 백업 공짜), Offline-first(계정·구독·서버 의존 없음). 여기에 "타입은 스키마가 아니라 렌즈"(필수 필드·검증 없이 탐색 보조만) 같은 절제된 설계 철학이 얹힙니다.
용도는 세컨드 브레인·개인 지식 관리가 기본이고, 최근의 주목 포인트는 셋째 용례 — 회사 문서·에이전트 메모리·절차를 AI의 컨텍스트로 정리하는 데스크탑 관리자입니다. AGENTS.md를 동봉해 어떤 에이전트든 볼트 규약을 스스로 파악하게 했고, Claude Code·Codex·Gemini CLI 설정 경로를 공식 지원합니다.
트렌딩 이유 · 경쟁 대비 장점.
노트 앱은 포화 시장입니다 — Obsidian(파일 기반·플러그인 제국), Notion(클라우드 DB) 등. Tolaria가 비집고 들어온 틈은 "에이전트와 같은 파일을 공유하는 작업대"라는 포지션과, 제작자가 10,000+ 노트로 매일 실사용하며 다듬는다는 신뢰("Built from real use")입니다.
| 비교 항목 | Notion류 (클라우드 DB) | Tolaria |
|---|---|---|
| 데이터 형식 | 전용 DB — 내보내기 필요 | 평범한 .md + YAML — 내보낼 것 자체가 없음 |
| 버전 관리 | 앱 내 히스토리 | git 그 자체 — 아무 원격이나 사용 |
| AI 연동 | API·커넥터 경유 | 에이전트가 파일을 직접 읽고 씀 + MCP 서버 내장 |
| 락인 | 구독·계정 | 없음 — 앱을 지워도 볼트는 그대로 |
클라우드 노트의 내용을 에이전트에 먹이려면 API·내보내기·동기화 계층이 필요하고, 그 계층이 곧 마찰이자 락인이 됩니다.
코딩 에이전트는 어차피 파일을 읽고 쓰는 존재 — 지식베이스가 마크다운 폴더면 별도 통합 없이 그대로 컨텍스트가 됩니다. 사람에겐 Tolaria의 에디터·커맨드 팔레트·타입 렌즈가, AI에겐 AGENTS.md와 MCP 서버가 같은 볼트의 두 출입구입니다.
Tauri 2 데스크탑 앱의 모범 구성.
| 레이어 | 기술 | 역할 |
|---|---|---|
| 데스크탑 셸 | Tauri 2 (Rust, src-tauri/ 121파일) | 네이티브 창·파일시스템·git 연동 — Electron보다 가벼운 Rust 셸. |
| 프론트엔드 | React + TypeScript + Vite | 에디터·커맨드 팔레트·탐색 UI (components 420 · hooks 255 파일). |
| AI 연동 | 내장 MCP 서버 (mcp-server/) | 외부 AI 도구가 볼트를 MCP로 조회 — Linux에선 시스템 node로 spawn. |
| 데이터 | 마크다운 + YAML 프런트매터 + git | 전용 포맷 없음. demo-vault-v2가 견본. |
| 품질 | Playwright 3종(스모크·통합·e2e) · Codecov · CodeScene · Codacy · Semgrep | 개인 출발 프로젝트답지 않은 품질 인프라. |
| 문서 | docs/adr 140파일 ★ · site/(GitHub Pages) | 아키텍처 결정 기록(ADR)이 140개 — 설계 사유의 보고. |
| 배포 | brew cask · 서명된 인스톨러 | Windows Authenticode 서명까지. |
노트 하나가 화면에 뜨고, 에이전트에게 읽히기까지.
흐름 하나 — 에이전트가 노트를 고치면: ① Claude Code가 볼트 폴더에서 AGENTS.md를 읽어 명명·프런트매터 규약을 파악하고 ② 노트 .md를 직접 수정합니다. ③ Tauri의 Rust 코어가 파일 변경을 감지(watcher)해 React UI를 갱신하고, ④ 변경 이력은 git에 쌓입니다 — 사람이 에디터로 고친 것과 완전히 같은 경로로. 앱과 에이전트가 "동기화 프로토콜" 없이 파일시스템과 git이라는 공용 기반 위에서 협업하는 구조입니다.
사무실의 공용 서류 캐비닛과 같습니다. 직원(사람)은 잘 정리된 열람실(Tolaria UI)에서 서류를 보고, 비서(에이전트)는 캐비닛을 직접 엽니다. 누가 고치든 서류는 한 부뿐이고, 모든 수정엔 도장(git 커밋)이 찍힙니다.
어떤 폴더가 무슨 일을 하나.
| 위치 | 주목할 점 |
|---|---|
docs/adr/ | 140개 결정 기록 — "왜 Tauri인가, 왜 타입을 강제 안 하나"의 1차 사료. |
AGENTS.md + CLAUDE.md + GEMINI.md | 레포 자체도 에이전트 친화 — 개발도 AI와 함께 한다는 신호. |
demo-vault-v2/ | 프런트매터·타입·폴더 규약의 살아있는 예제 — 볼트 설계 참고서. |
playwright.*.config 3종 | 스모크/통합/E2E를 분리 운용 — 데스크탑 앱 테스트 전략 견본. |
이 레포에서 배울 만한 것 + 어디를 보면 되는지.
Rust 코어 ↔ React 프론트의 IPC, 파일 워처, 플랫폼별 패키징(서명 포함)까지 — Tauri 튜토리얼 다음에 읽을 "진짜 앱"으로 적당한 규모입니다.
"앱을 지워도 잃는 게 없다"를 기능이 아니라 아키텍처로 보장하는 법 — 동기화 서버를 만들지 않은 결정이 ADR에 어떻게 기록돼 있는지 찾아 읽어 보세요.
같은 데이터에 대한 두 출입구(UI / AGENTS.md+MCP)를 충돌 없이 운영하는 패턴 — "내 앱을 에이전트 친화로 만들기"의 구체적 견본입니다.
Codecov+CodeScene+Codacy+Semgrep+Playwright 3종 — 어떤 도구를 어느 단계에 끼웠는지 .github/workflows를 훑으면 품질 파이프라인 설계가 보입니다.
돌리려면 무엇이 필요한가.
| 항목 | 요구사항 |
|---|---|
| 사용자 | macOS(brew cask)·Windows(서명된 인스톨러)·Linux 릴리스 다운로드. |
| 개발 | Node 20+ · pnpm 8+ · Rust stable. Linux는 WebKit2GTK 4.1·GTK 3 등 시스템 패키지. |
| MCP 흐름 | Linux에서 내장 MCP 서버는 시스템 node를 spawn — 배포판 node 설치 필요. |
| 시작 | 첫 실행 시 getting-started 볼트 클론 제안 — 앱 전체 워크스루 포함. |
난이도별로 손에 익히는 단계.
설치 후 getting-started 볼트를 클론해 따라가고, 노트 몇 개를 만든 뒤 파인더/탐색기에서 .md 파일과 .git을 직접 확인합니다 — "정말 그냥 파일이네"를 체감하는 단계.
볼트 폴더에서 Claude Code를 열어 "이번 주 회의록을 요약해 weekly-review 노트를 만들어줘"를 시키고, Tolaria UI에 결과가 바로 뜨는 걸 확인합니다. AGENTS.md 규약을 에이전트가 지키는지도 관찰.
demo-vault-v2를 참고해 내 도메인 타입(예: 현장·발주·회의)을 프런트매터로 설계하고, 타입 필터로 탐색이 얼마나 달라지는지 실험합니다.
docs/adr에서 흥미로운 결정 3개를 골라 코드의 실제 구현과 대조하고, GETTING-STARTED.md대로 로컬 빌드까지 — 오픈소스 기여의 준비 운동.
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | 볼트 운용 — 노트·타입·git 흐름 | getting-started 볼트 · Loom 워크스루 |
| 2주차 | 에이전트 연동 — AGENTS.md·MCP | 실습 2 · mcp-server/ |
| 3주차 | Tauri 2 구조 — IPC·워처·패키징 | src-tauri/ · Tauri 공식 문서 |
| 4주차 | 설계 사상 — ADR 정독 | docs/adr 140편 중 핵심 결정들 |
| 5주차 | 내 지식 체계 이식 | 실습 3 · 기존 노트 마이그레이션 |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| 볼트(vault) | 노트가 담긴 폴더 = git 저장소 — Tolaria의 작업 단위. |
| YAML 프런트매터 | 마크다운 머리의 --- 블록 — 타입·태그 등 메타데이터. |
| 세컨드 브레인 | 기억·생각을 외부 시스템에 축적하는 개인 지식 관리 방법론. |
| Files-first / Git-first | 데이터를 평범한 파일로 / 이력을 git으로 — 락인 제로의 두 기둥. |
| 타입 렌즈 | 검증 없는 분류 — 스키마가 아닌 탐색 보조로서의 타입. |
| Tauri | Rust 코어 + 시스템 웹뷰로 데스크탑 앱을 만드는 프레임워크 — Electron 대안. |
| IPC | 프론트(웹뷰)와 Rust 코어 사이의 프로세스 간 통신. |
| MCP 서버 | 외부 AI 도구가 볼트를 표준 프로토콜로 조회하는 내장 서버. |
| AGENTS.md | 에이전트가 읽는 볼트/레포 사용 설명서. |
| ADR | 아키텍처 결정 기록 — 이 레포에 140개. |