Tolaria 완벽 가이드 2026: 오픈소스 마크다운 지식베이스 데스크톱 앱

Tolaria란 무엇인가?

Tolaria는 마크다운 형식의 지식베이스를 관리하기 위한 오픈소스 데스크톱 애플리케이션입니다. 개발자 Luca Ronin이 자신의 개인 워크스페이스에 있는 10,000개가 넘는 노트를 관리하기 위해 만들었으며, 현재는 GitHub에서 14,000개 이상의 스타를 받은 인기 프로젝트로 성장했습니다.

핵심 철학

Tolaria의 설계 철학은 매우 명확합니다: 데이터는 사용자의 것이며, 어떤 애플리케이션의 것도 아닙니다. 이는 Obsidian, Notion 등 주류 노트 도구들과 근본적인 차이가 있습니다:

왜 Tolaria를 선택해야 할까?

1. 제로 락인(Zero Lock-in): 모든 노트는 표준 .md 파일이라서 VS Code, Vim 또는 다른 에디터로 언제든지 열 수 있습니다. Tolaria 사용을 중단하더라도 데이터를 잃지 않습니다.

2. Git 우선(Git-first): 각 지식베이스(Vault)는 Git 리포지토리라서 버전 기록, 브랜치 관리, 원격 동기화 기능을 자동으로 갖춥니다. 팀 협업이나 장기적인 지식 축적에 필수적입니다.

3. AI 네이티브 지원: Tolaria는 Claude Code, Codex CLI, Gemini CLI에 대한 내장 지원을 제공하며, AGENTS 파일을 통해 AI 어시스턴트가 지식베이스 구조를 이해하도록 돕습니다.

4. 키보드 우선 설계: 효율적인 사용자들을 위해 설계되어 단축키로 대부분의 작업을 수행할 수 있으며, Command Palette는 VS Code와 유사한 경험을 제공합니다.

5. 타입을 렌즈로 활용(Types as Lenses): Tolaria의 타입 시스템은 강제적인 스키마가 아니라 노트를 탐색하고 분류하는 데 도움을 주는 보조 도구입니다. 필수 필드나 검증 제한이 없습니다.

Tolaria 설치하기

macOS (Homebrew 권장)

# Homebrew로 설치 (가장 간단)
brew install --cask tolaria

# 또는 공식 웹사이트에서 다운로드
# https://refactoringhq.github.io/tolaria/download/ 방문

Windows

1. Tolaria 다운로드 페이지 방문
2. 최신 .exe 설치 패키지 다운로드
3. 설치 프로그램 실행

참고: Windows 설치 패키지는 Authenticode 서명이 되어 있지만, 회사 관리 장치에서는 최초 설치 시 IT 부서의 승인이 필요할 수 있습니다.

Linux

# AppImage 다운로드 (권장)
wget https://github.com/refactoringhq/tolaria/releases/latest/download/Tolaria-x86_64.AppImage
chmod +x Tolaria-x86_64.AppImage
./Tolaria-x86_64.AppImage

# 또는 Flatpak 사용 (사용 가능한 경우)
flatpak install flathub com.refactoringhq.tolaria

소스에서 빌드하기

# 리포지토리 클론
git clone https://github.com/refactoringhq/tolaria.git
cd tolaria

# 의존성 설치 (Node.js 18+ 필요)
npm install

# 개발 모드로 실행
npm run dev

# 프로덕션 버전 빌드
npm run build

빠른 시작: 첫 번째 지식베이스 만들기

Step 1: Vault 초기화

Tolaria를 처음 실행할 때 다음 옵션 중 하나를 선택할 수 있습니다:

1. 스타터 지식베이스 클론: Tolaria는 샘플 노트와 사용 튜토리얼이 포함된 getting started vault를 제공합니다
2. 빈 지식베이스 생성: 처음부터 시작
3. 기존 폴더 열기: 이미 마크다운 노트 폴더가 있다면 직접 가져올 수 있습니다

# 빈 vault 수동 생성 (명령줄 방식)
mkdir ~/my-knowledge-base
cd ~/my-knowledge-base
git init
echo "# My Knowledge Base" > README.md
git add .
git commit -m "Initial commit"

그런 다음 Tolaria에서 「Open Existing Vault」를 선택해 이 폴더를 지정하세요.

Step 2: 디렉토리 구조 이해

Tolaria의 지식베이스는 일반 폴더일 뿐이며, 전형적인 구조는 다음과 같습니다:

my-vault/
├── .git/                  # Git 리포지토리 (자동 생성)
├── AGENTS.md              # AI 어시스턴트 설정 파일
├── types/                 # 타입 정의 폴더
│   ├── note.type.yaml     # 노트 타입 템플릿
│   └── task.type.yaml     # 작업 타입 템플릿
├── inbox/                 # 인박스 (아이디어 빠른 캡처)
├── projects/              # 프로젝트 노트
├── areas/                 # 책임 영역
├── resources/             # 참고 자료
└── archive/               # 아카이브 콘텐츠

팁: 이 구조는 PARA 방법론(Projects, Areas, Resources, Archive)을 참고했지만, 자유롭게 커스터마이징할 수 있습니다.

Step 3: 첫 번째 노트 만들기

Tolaria에서 Cmd/Ctrl + N을 눌러 새 노트를 만듭니다:

---
title: Tolaria 학습 노트
type: note
created: 2026-06-10
tags:
  - tolaria
  - knowledge-base
---

# Tolaria 핵심 기능

Tolaria는...

## 주요 기능

- 파일 우선
- Git 우선
- 오프라인 우선

## 관련 링크

- [[다른 노트]]  <!-- 양방향 링크 -->
- [Tolaria GitHub](https://github.com/refactoringhq/tolaria)

Step 4: Git 원격 리포지토리 설정 (선택 사항이지만 권장)

# vault 디렉토리에서 실행
cd ~/my-knowledge-base

# 원격 리포지토리 추가 (GitHub/GitLab/Gitee)
git remote add origin https://github.com/yourusername/my-vault.git

# 푸시
git push -u origin main

이렇게 하면 노트에 클라우드 백업이 생기고 여러 기기 간 동기화가 가능해집니다.

핵심 기능 상세 설명

1. 파일 우선: 순수 마크다운의 힘

Tolaria의 가장 큰 장점은 전용 형식을 만들지 않는다는 점입니다. 모든 노트는 표준 마크다운 파일입니다:

# 어떤 에디터에서든 열기
code ~/my-vault/inbox/idea.md
vim ~/my-vault/projects/project-a.md

# grep으로 검색
grep -r "키워드" ~/my-vault/

# 일괄 처리
find ~/my-vault -name "*.md" -exec sed -i 's/old/new/g' {} \;

这意味着: - ✅ 어떤 텍스트 에디터로도 수정 가능 - ✅ 스크립트로 일괄 처리 가능 - ✅ 버전 관리에 포함 가능 - ✅ 다른 도구와 통합 가능 (정적 사이트 생성기 등)

2. Git 통합: 버전 기록의 자연스러운 장점

노트 수정 후 Tolaria는 변경 사항을 자동으로 감지하고 커밋을 제안합니다. 수동으로 조작할 수도 있습니다:

# 변경 사항 확인
git status
git diff

# 변경 사항 커밋
git add .
git commit -m "프로젝트 노트 업데이트"

# 기록 확인
git log --oneline

# 특정 버전으로 롤백
git checkout <commit-hash> -- filename.md

실전 시나리오: 글을 쓰다가 중요한 부분을 실수로 삭제했습니다. git log로 이전 커밋을 찾아 git checkout으로 복구하면 됩니다.

3. 양방향 링크: 지식 네트워크 구축

Tolaria는 Wiki 스타일의 양방향 링크를 지원합니다:

# 노트 A에서
자세한 내용은 [[노트 B]]를 참조하세요.

# 노트 B에서
이는 [[노트 A]]에서 인용된 내용입니다.

Tolaria 인터페이스에서: - 링크를 클릭하면 바로 이동 - 우클릭하여 「역링크」(현재 노트를 인용한 노트들) 확인 - 그래프 뷰로 노트 간 관계망 시각화

4. 타입 시스템: 유연한 분류

Tolaria의 타입(Types)은 강제적인 스키마가 아니라 탐색 보조 도구입니다:

# types/note.type.yaml
name: Note
icon: 📝
color: blue
fields:
  - name: created
    type: date
  - name: tags
    type: list

---
title: 내 노트
type: note
created: 2026-06-10
tags:
  - learning
---

사이드바에서 타입별로 노트를 필터링할 수 있지만, 필수 필드가 없으며 필드가 부족하다고 오류가 발생하지 않습니다.

5. Command Palette: 키보드 효율 작업

Cmd/Ctrl + P를 눌러 명령 팔레트를 엽니다. VS Code와 유사합니다:

• Quick Open: 노트 빠르게 열기
• Create Note: 새 노트 만들기
• Search: 전체 텍스트 검색
• Git Commit: 변경 사항 커밋
• Toggle Theme: 테마 전환

주요 단축키: - Cmd/Ctrl + N: 새 노트 - Cmd/Ctrl + P: 명령 팔레트 - Cmd/Ctrl + F: 검색 - Cmd/Ctrl + Shift + F: 전역 검색 - Cmd/Ctrl + [: 이전 페이지로 돌아가기

AI 통합: AI 어시스턴트가 지식베이스를 이해하도록 하기

Tolaria의 핵심 하이라이트 중 하나는 AI 프로그래밍 어시스턴트의 네이티브 지원입니다. 각 vault 루트 디렉토리에는 AGENTS.md 파일이 있어 AI에게 지식베이스 구조를 이해시키는 방법을 알려줍니다.

Claude Code 설정

# vault 디렉토리에서
cd ~/my-vault

# Claude Code 초기화 (아직 설치되지 않은 경우)
claude

# Claude Code는 AGENTS.md를 자동으로 읽어 노트 구조를 이해합니다

AGENTS.md 예시 내용:

# AGENTS.md - Tolaria Vault Guide

This vault uses the PARA method for organization:

- **Projects/**: Active projects with deadlines
- **Areas/**: Ongoing responsibilities
- **Resources/**: Reference materials
- **Archive/**: Completed or inactive items

## Note Format

All notes are Markdown files with YAML frontmatter:

```yaml
---
title: Note Title
type: note|task|resource
created: YYYY-MM-DD
tags: [tag1, tag2]
---

Common Tasks

• To find recent notes: search by created date in frontmatter
• To find related notes: look for [[wiki-links]]
• To update a project: check projects/ directory

### 실전: AI로 노트 정리하기

```bash
# vault 디렉토리에서 Claude Code 실행
claude

# 그리고 질문하기:
# "projects/ 디렉토리의 모든 미완료 프로젝트를 요약해줘"
# "'TODO'가 포함된 모든 노트를 찾아줘"
# "내 Python 학습 노트에 태그를 추가해줘"

지원하는 다른 AI 도구

• Codex CLI: OpenAI의 명령줄 도구
• Gemini CLI: Google Gemini의 명령줄 인터페이스
• 임의의 LLM: 노트가 순수 텍스트이므로 어떤 AI 도구로도 처리 가능

고급 활용법

1. Inbox 워크플로우: 아이디어 빠른 캡처

Tolaria가 추천하는 워크플로우는 「Inbox → 정리」입니다:

1. 캡처: 생각이 날 때마다 inbox/ 아래에 노트를 빠르게 만들고, 분류에 신경 쓰지 않기
2. 정리: 매일/매주 inbox를 검토하여 노트를 적절한 폴더로 이동

# 예시: 빠른 캡처
# Cmd/Ctrl + N을 눌러 제목 입력, inbox/quick-thought.md로 저장

# 정기적으로 정리
mv inbox/quick-thought.md projects/project-alpha/
git add .
git commit -m "inbox 정리: 노트를 프로젝트로 이동"

2. 웹 클리핑: 웹 페이지 콘텐츠 저장

Tolaria는 웹 페이지 저장을 위한 브라우저 확장 프로그램(또는 Bookmarklet)을 제공합니다:

// Bookmarklet 코드 (브라우저 북마크에 저장)
javascript:(function(){
  const title = document.title;
  const url = window.location.href;
  const content = document.getSelection().toString() || document.body.innerText;

  const markdown = `---
title: ${title}
type: resource
created: ${new Date().toISOString().split('T')[0]}
source: ${url}
---

# ${title}

${content}
`;

  // 클립보드에 복사한 후 Tolaria에 붙여넣기
  navigator.clipboard.writeText(markdown);
  alert('클립보드에 복사됨. Tolaria에서 붙여넣으세요');
})();

3. 템플릿 시스템: 표준화된 노트 형식

templates/ 디렉토리에 템플릿을 만듭니다:

# templates/meeting-note.md
---
title: {{title}}
type: meeting
created: {{date}}
attendees: []
---

# {{title}}

**날짜:** {{date}}
**참석자:** 

## 의제

1. 
2. 

## 논의 사항

## 액션 아이템

- [ ] 

새 노트를 만들 때 템플릿을 복사하고 변수를 교체합니다.

4. 정적 사이트 생성기와 통합

노트가 순수 마크다운이므로 SSG를 사용해 지식베이스를 웹사이트로 게시할 수 있습니다:

# MkDocs 사용
pip install mkdocs
mkdocs new my-site
cp -r ~/my-vault/* my-site/docs/
mkdocs serve

# 또는 Hugo 사용
hugo new site my-blog
cp -r ~/my-vault/* my-blog/content/
hugo server

5. 다중 기기 동기화

Git을 통해 다중 기기 동기화를 구현합니다:

# 기기 A (푸시)
cd ~/my-vault
git add .
git commit -m "노트 업데이트"
git push

# 기기 B (풀)
cd ~/my-vault
git pull

팁: 충돌이 발생하면 Git이 수동 병합을 요청합니다. 마크다운 파일의 경우 병합은 일반적으로 간단합니다.

자주 묻는 질문

Q1: Tolaria와 Obsidian의 차이점은 무엇인가요?

A: 주요 차이점은 설계 철학에 있습니다: - Obsidian: 기능이 풍부하고 방대한 플러그인 생태계가 있지만 코어는 클로즈드 소스입니다 - Tolaria: 완전 오픈소스, Git 네이티브 통합, AI 친화적, 더 가벼움

데이터 주권과 오픈소스 투명성을 중시한다면 Tolaria가 더 나은 선택입니다. 모바일 앱과 풍부한 커뮤니티 플러그인이 필요하다면 Obsidian이 더 적합할 수 있습니다.

Q2: Obsidian에서 Tolaria로 마이그레이션할 수 있나요?

A: 가능합니다! 둘 다 순수 마크다운 파일을 사용하므로 다음만 수행하면 됩니다:

# Obsidian vault를 Tolaria로 복사
cp -r ~/obsidian-vault ~/tolaria-vault
cd ~/tolaria-vault
git init
git add .
git commit -m "Obsidian에서 마이그레이션"

그런 다음 Tolaria에서 이 폴더를 열면 됩니다. 양방향 링크 구문([[link]])도 호환됩니다.

Q3: Tolaria는 모바일을 지원하나요?

A: 현재 Tolaria는 데스크톱(macOS/Windows/Linux)만 지원합니다. 모바일에서는 다음 방법으로 접근할 수 있습니다: - Git으로 동기화한 후 휴대폰의 마크다운 에디터(iA Writer, 1Writer 등)로 열기 - vault를 정적 사이트로 게시하여 브라우저로 접근

Q4: 이미지 첨부 파일은 어떻게 처리하나요?

A: vault에 assets/ 폴더를 만들어 이미지를 저장합니다:

![ 다이어그램 ](assets/diagram.png)

# 이미지를 assets 디렉토리로 복사
cp ~/Downloads/diagram.png ~/my-vault/assets/
git add assets/diagram.png
git commit -m "다이어그램 추가"

Q5: Tolaria의 성능은 어떻나요? 몇 개의 노트를 처리할 수 있나요?

A: Tolaria의 작성자는 이를 사용해 10,000개 이상의 노트를 관리하며 일상적으로 원활하게 사용합니다. 성능 병목은 일반적으로 다음에 있습니다: - Git 작업 (많은 파일일 때 git status가 느려짐) - 전체 텍스트 검색 (인덱싱으로 최적화 가능)

활성 노트 수를 합리적인 범위로 유지하기 위해 오래된 노트를 정기적으로 archive/ 디렉토리로 아카이브하는 것이 좋습니다.

요약

Tolaria는 개발자를 위해 설계된 지식베이스 도구이며, 그 핵심 가치는 다음과 같습니다:

1. 데이터 주권: 순수 마크다운 파일, 제로 락인
2. 버전 제어: Git 네이티브 통합, 자연스러운 기록 추적
3. AI 친화적: 주요 AI 프로그래밍 어시스턴트 네이티브 지원
4. 오픈소스 무료: 완전 투명, 숨겨진 비용 없음
5. 크로스 플랫폼: macOS / Windows / Linux

적합한 사용자: - ✅ 개발자, 기술 작가 - ✅ 데이터 주권을 중시하는 지식 근로자 - ✅ 이미 Git을 사용하는 팀 - ✅ AI로 지식 관리를 보조하려는 사용자

덜 적합한 사용자: - ❌ 모바일 앱이 필요한 사용자 - ✅ 리치 미디어 임베딩(비디오, 상호작용 차트 등)을 좋아하는 사용자 - ❌ Git 설정을 원하지 않는 비기술 사용자

리소스 링크: - Tolaria GitHub 리포지토리 - 다운로드 페이지 - 스타터 지식베이스 템플릿 - 작성자 Luca의 X 계정

이 글이 도움이 되었다면 더 많은 개발자와 공유해주세요!