English

DotBrain

Built for Humans. Optimized for AI.

DotBrain은 로컬 문서를 PARA 방법론에 따라 체계적으로 정리합니다.
이 구조는 사람에게는 직관적인 지식 체계가 되고,

AI에게는 이해할 수 있는 Context를 부여합니다.
Context는 AI의 탐색 기반이 되어, 당신의 지식을 더 깊이 이해하고 사고할 수 있게 합니다.

·‿·  →  ·_·!  →  ·_·…  →  ^‿^
               

---

🧐 What is DotBrain?

지식 관리의 병목은 축적이 아니라 활용입니다.
자료는 쉽게 쌓이지만,
찾기 좋게 정리하고 맥락을 연결하는 일은 어렵습니다.

더 어려운 일은,
AI가 이해하고 활용할 수 있는 형태로 그 지식을 구조화하는 것입니다.

The Problem: Human vs. AI

• PARA의 딜레마 (Human Overhead): PARA 방법론은 사람의 인지 구조에는 훌륭하지만, 매번 수동으로 분류해야 하는 유지보수 비용이 큽니다. 결국 정리는 밀리고 인박스에는 파일만 쌓입니다.
• AI의 불협화음 (Context Gap): 정리가 안 된 문서는 AI조차 맥락을 파악하기 어렵습니다. 단순한 파일 저장은 사람과 AI 모두에게 쓸모없는 데이터 덤프가 될 뿐입니다.

The Solution: DotBrain DotBrain은 이 '정리의 병목'을 AI에게 위임합니다.

• Zero-Friction Sort: 인박스에 파일을 모아두고 정리를 실행하면, AI가 내용을 읽고 PARA 체계에 맞춰 자동으로 분류·이동시킵니다.
• Semantic Structure: Obsidian 호환 프론트매터와 위키링크를 자동 생성하여 문서 간의 맥락을 연결합니다.
• Compounding Synthesis: 새 노트가 들어올 때마다 폴더 페이지와 카테고리 허브를 AI가 종합·갱신하여, 기록이 쌓일수록 지식이 복리로 정리됩니다.
• Self-Healing: 중첩된 폴더 구조를 플랫화하고, 깨진 링크와 누락된 프론트매터를 복구하며, SHA256 해시로 중복 파일을 감지해 병합합니다.
• Reliability: Claude CLI · Codex CLI · Claude API를 지원하며, 한쪽이 실패하면 다른 제공자로 폴백합니다.

---

🚀 Quick Start

터미널에서 한 줄로 설치할 수 있습니다.

npx dotbrain

메뉴바에 ·‿· 가 나타나면 설치 완료입니다. 아이콘을 클릭하여 온보딩을 시작하세요.

📖 자세한 사용법은 **서비스 매뉴얼 (MANUAL.md)**을 참고하세요.

필요한 것: macOS 13 (Ventura) 이상 / Node.js 18+ (npx 사용 시) / Claude 구독 (Pro/Max) + Claude CLI 기본. Codex CLI, Claude API 키도 지원.

소스에서 직접 빌드

git clone https://github.com/DinN0000/DotBrain.git ~/Developer/DotBrain
cd ~/Developer/DotBrain
swift build -c release
# 바이너리: .build/release/DotBrain

---

⚙️ How it Works

인박스 처리

인박스에 파일을 모아두고 정리를 실행하면 다음 순서로 처리됩니다 :

_Inbox/에 파일 추가 (드래그앤드롭)
    ↓
"정리" 실행 (사용자 트리거 — 던지는 순간 자동 실행 아님)
    ↓
내용 추출 (텍스트/PDF/이미지/PPTX/XLSX/DOCX)
    ↓
2단계 AI 분류
    ├── Stage 1: 빠른 배치 분류
    └── Stage 2: 정밀 재확인 — 신뢰도 낮은 파일만
    ↓
파일 이동 + 프론트매터 주입 + 관련 노트 연결 + 인덱스·폴더 페이지·카테고리 허브 갱신
    ↓
분류 완료

AI 분류 전략

제공자	Stage 1 (Fast)	Stage 2 (Precise)	비용
Claude CLI (추천)	사용자 기본 모델	사용자 기본 모델	구독 토큰 사용
Codex CLI	사용자 기본 모델	사용자 기본 모델	구독 토큰 사용
Claude API	Haiku 4.5	Sonnet 4.5	~$0.002/파일

대부분의 파일은 Stage 1에서 끝납니다. Claude CLI는 구독 토큰을 사용하므로 별도 API 비용이 없습니다. CLI 제공자(Claude/Codex)는 별도 모델을 지정하지 않고 사용자의 CLI 기본 모델을 그대로 사용하며, 두 스테이지는 모델이 아니라 프롬프트 전략(배치 vs 개별 정밀)만 다릅니다. 특정 모델(Haiku/Sonnet)은 API 키를 쓰는 Claude API 경로에만 적용됩니다.

폴더 정리

기존 PARA 폴더를 AI가 다시 정리합니다:

폴더 선택
    ↓
플랫화 — 중첩 하위 폴더에서 콘텐츠를 최상위로 이동 (SHA256 중복 제거)
    ↓
AI 재분류
    ├── 위치 맞음 → frontmatter 갱신
    └── 위치 틀림 → 올바른 폴더로 자동 이동

볼트 관리

• PARA 관리 — 카테고리 간 폴더 이동, 프로젝트 생성, 폴더별 자동 정리
• 전체 재정리 — 볼트 전체를 AI가 스캔하여 잘못된 분류 이동 제안 (사용자 승인 후 실행)
• 볼트 점검 — 깨진 링크·누락 프론트매터 자동 수정, 변경 노트 시맨틱 링크 갱신, 링크 재선별(문서당 12개 유지), 폴더·카테고리 종합 갱신까지 한 번에 수행

Frontmatter 표준화

DotBrain은 모든 노트에 대해 사람과 AI가 모두 이해할 수 있는 표준 규격을 적용합니다.

---
para: project
tags: [defi, ethereum, blockchain]
created: 2026-02-11
status: active
summary: "DeFi 시스템 구축 프로젝트"
source: import
project: MyProject
---

필드	설명
para	PARA 카테고리 (Project/Area/Resource/Archive)
tags	파일 내용 기반으로 자동 태깅
created	최초 생성일 (기존 값 보존)
status	active / draft / completed / on-hold
summary	파일 내용을 한줄로 요약
source	original / meeting / literature / import
project	연관 프로젝트명
area	연관 Area 이름
projects	연관 프로젝트 목록 (Area 내 문서용)
file	원본 파일명 (비텍스트 파일의 경우)

---

📂 Folder Structure

DotBrain이 관리하는 PKM(Personal Knowledge Management) 폴더 구조입니다.

PKM Root/
├── _Inbox/                          ← 여기에 파일을 넣으면
├── _Assets/                         ← 바이너리 파일 중앙 저장소
│   ├── documents/                   ← PDF, DOCX 등
│   ├── images/                      ← 이미지
│   └── videos/                      ← 동영상
├── .meta/                           ← 기계용 레이어 (노트 인덱스, 볼트 로그)
├── 1_Project/
│   ├── 1_Project.md                 ← 카테고리 허브 (지형·교차연결·모순 종합)
│   └── MyProject/
│       ├── MyProject.md             ← 하위 폴더 페이지 (개요·최근 흐름·핵심 노트·모순·노후)
│       └── plan.md
├── 2_Area/
│   ├── 2_Area.md                    ← 카테고리 허브
│   ├── DevOps/
│   │   └── monitoring-guide.md
│   └── Unsorted/                    ← 분류 애매한 Area·Resource 신규 노트가 모이는 곳
├── 3_Resource/
│   ├── 3_Resource.md                ← 카테고리 허브
│   ├── Python/
│   │   └── asyncio-patterns.md
│   └── Unsorted/
└── 4_Archive/                       ← 종합 없음 (허브·폴더 페이지 없음)
    └── 2024-Q1/
        └── quarterly-report.md

🛠 Technical Details

지원 파일 형식

형식	추출 방식	추출 내용
.md, .txt 등	직접 읽기	전체 텍스트
.pdf	PDFKit	텍스트 + 페이지수/저자/제목
.docx	ZIPFoundation + XML	본문 텍스트 + 메타데이터
.pptx	ZIPFoundation + XML	슬라이드 텍스트
.xlsx	ZIPFoundation + XML	셀 데이터
.jpg, .png, .heic 등	ImageIO	EXIF (촬영일, 카메라, GPS)
폴더	내부 파일 순회	포함 파일 내용 종합

중복 감지

상황	감지 방식	처리
같은 내용, 다른 이름	SHA256 본문 해시 (frontmatter 제외)	태그 병합 → 삭제
같은 내용 바이너리	SHA256 해시 (≤500MB) 또는 크기+수정일 (>500MB)	태그 병합 → 삭제
같은 이름, 다른 내용	파일명 비교	사용자에게 확인
폴더 개체 페이지와 이름 충돌	폴더명.md 비교	사용자에게 확인

기술 스택

• Swift 5.9 + SwiftUI + Combine
• macOS 메뉴바 앱 — NSStatusItem + NSPopover
• AI — Claude CLI (구독, 추천) / Codex CLI / Claude API — 3중 제공자, 자동 폴백
• 의존성 — ZIPFoundation (DOCX/PPTX/XLSX 처리)
• 보안 — Claude CLI는 API 키 불필요 (구독 인증). API 키 사용 시 AES-GCM 암호화 파일로 기기 종속 저장 (하드웨어 UUID + HKDF)
• 안정성 — 지수 백오프 재시도, 제공자 폴백, 경로 탐색 보호

---

🎨 Design Philosophy

당신의 맥락을, AI가 읽을 수 있게

AI는 주어진 자료를 바탕으로 판단합니다. 하지만 대부분의 경우, 사용자가 직접 파일을 선택해서 전달해야 합니다.

• 파일 단위로 전달하면 개별 분석은 가능하지만, 자료 간 맥락 연결이 어렵습니다
• 대량으로 전달하면 컨텍스트 제한에 도달합니다
• 매 대화마다 동일한 배경 설명을 반복해야 합니다

AI가 사용자의 지식 전체를 활용하려면, AI 스스로 탐색할 수 있는 구조화된 지식베이스가 필요합니다.

DotBrain은 파일을 받아 분류하고, 태그를 부여하고, 문서 간 연결 관계를 생성합니다. 어떤 AI 도구든 이 지식베이스를 열었을 때, 구조만으로 관련 맥락을 탐색할 수 있는 상태를 만듭니다.

Frontmatter — 사람과 AI 모두를 위한 메타데이터

모든 파일에는 YAML frontmatter가 부여됩니다.

---
para: project
tags: [defi, ethereum, blockchain]
summary: "DeFi 시스템 구축 프로젝트"
---

사람에게는 Obsidian에서 바로 보이는 메타데이터이고, AI에게는 파싱 한 번으로 분류·검색·요약 정보가 추출되는 구조화된 데이터입니다.

tags·summary는 AI가 생성하고 유지합니다. 본문을 고치면 볼트 점검 때 요약과 태그도 최신 내용으로 다시 생성되어 메타데이터가 낡지 않습니다. 사용자가 지키는 것은 자신이 쓴 산문 본문뿐이며, DotBrain은 이 본문을 절대 건드리지 않습니다. 메타데이터를 손수 채우는 노동에서 벗어나고, AI는 일관된 규격의 데이터를 확보합니다.

세 겹의 종합 — 노트 위에 폴더, 폴더 위에 카테고리

원본 노트는 그대로 두고, AI가 그 위에 두 겹의 종합 레이어를 쌓습니다. 기록이 쌓일수록 상위 레이어가 다시 정리되어 지식이 복리로 축적됩니다.

• 노트 — 원본. AI는 프론트매터와 ## Related Notes만 기록하고, 사용자가 쓴 산문 본문은 건드리지 않습니다.
• 하위 폴더 페이지(폴더명.md) — 그 폴더의 개요 · 최근 흐름 · 핵심 노트 · 모순 · 노후를 종합한 진입점.
• 카테고리 허브(1_Project.md 등) — 하위 폴더들 사이의 지형 · 교차연결 · 모순을 종합. Project · Area · Resource에서 하위 폴더가 2개 이상일 때 생성되며, Archive는 종합하지 않습니다.

지식의 시간 축은 별도 파일이 아니라 흐름으로 남습니다. 각 페이지의 ## 최근 흐름이 이전 항목을 이어받아 누적되고(스냅샷이 아니라 누적), 종합이 일어날 때마다 .meta/log.md에 synthesis 한 줄이 append되어 grep 한 번으로 훑을 수 있는 연대기가 됩니다.

모든 종합은 사용자 트리거 + 해시 게이트입니다. 인박스 정리와 볼트 점검을 실행할 때만, 그리고 내용이 실제로 바뀐 폴더·카테고리만 다시 종합합니다. 백그라운드 스케줄러도, 매번 전체 재작성도 없습니다.

문서 사이는 ## Related Notes 섹션이 관계 유형과 한 줄 맥락을 담아 자동 연결합니다. 문서당 12개를 넘으면 AI가 가장 가치 있는 링크만 남기고 재선별합니다.

## Related Notes

### 선행 지식
- [[DeFi 기초]] — 프로토콜 구조를 이해하려면

### 함께 보기
- [[시장 리포트]] — 시장 전체 트렌드와 비교할 때

사람에게 이 링크는 클릭으로 이동하는 목차이고, AI에게는 탐색 그래프의 엣지입니다. .meta/에는 노트 인덱스(JSON)와 볼트 변경 타임라인(log.md)이 함께 유지되어, AI가 볼트 전체를 읽지 않고도 어떤 문서를 먼저 읽을지 판단할 수 있습니다.

같은 구조가 사람에게는 네비게이션으로, AI에게는 탐색 그래프로 작동합니다.

AI Companion Files — 볼트를 AI-ready로

DotBrain은 사용자의 볼트에 CLAUDE.md(Claude Code)와 AGENTS.md(Codex) AI 컴패니언 파일을 자동 생성합니다. 이 파일들이 있으면 AI 코딩 도구가 볼트를 열었을 때 폴더 구조, 분류 규칙, 태그 체계, 탐색 우선순위를 즉시 파악합니다. 가치 있는 종합·분석 답변은 다시 노트로 저장하도록 유도해, 탐구 결과도 볼트에 쌓입니다.

볼트 전체를 읽지 않아도, 컴패니언 파일 하나로 **"이 지식베이스는 이렇게 구성되어 있고, 이런 규칙을 따른다"**를 전달할 수 있습니다.

업데이트 시에는 <!-- DotBrain:start --> / <!-- DotBrain:end --> 마커 사이만 갱신합니다. 마커 바깥에 사용자가 추가한 내용은 보존됩니다.

프로젝트는 사람이, 분류는 AI가

PARA 프레임워크(Projects, Areas, Resources, Archive)가 분류의 기본 구조를 제공합니다. 이 구조 안에서 AI가 파일을 자동으로 분류합니다.

사용자가 하는 일은 프로젝트를 정의하는 것입니다. "PoC-Alpha", "Research-Beta", "DotBrain" — 어떤 프로젝트가 진행 중인지는 사용자만 압니다. 프로젝트가 설정되면, 어떤 파일이 어디에 속하는지는 AI가 판단합니다.

---

지식베이스가 구조화되면, AI는 단순한 질의응답을 넘어섭니다. 관련 자료를 스스로 탐색하고, 문서 간 연결에서 패턴을 발견하고, 사용자의 맥락 위에서 사고합니다.

DotBrain은 그 시작점을 만듭니다.

---

❓ Troubleshooting

"확인되지 않은 개발자" / "손상되어 열 수 없음"

xattr -cr ~/Applications/DotBrain.app

또는: 시스템 설정 → 개인정보 보호 및 보안 → "확인 없이 열기"를 클릭하세요.

폴더 접근 권한 팝업

첫 실행 시 PKM 폴더 접근 권한 요청에 반드시 **"허용"**을 선택해야 합니다.

메뉴바에 아이콘이 안 보임

메뉴바 공간 부족일 수 있습니다. 다른 아이콘을 ⌘+드래그로 제거하거나, Bartender/Ice로 정리하세요.

앱 제거

npx dotbrain --uninstall

또는 수동으로:

pkill -f DotBrain 2>/dev/null; \
launchctl bootout gui/$(id -u)/com.dotbrain.app 2>/dev/null; \
rm -f ~/Library/LaunchAgents/com.dotbrain.app.plist; \
rm -rf ~/Applications/DotBrain.app; \
echo "제거 완료"

---

💬 그래서 DotBrain은?

DotBrain은 macOS 메뉴바에서 동작하는 AI PKM 앱입니다. 파일을 인박스에 모아두고 정리하면 AI가 내용을 분석해서 PARA 구조로 자동 분류하고, 프론트매터 작성, 관련 노트 연결, 폴더·카테고리 페이지 종합까지 다 해줍니다.

노트 정리하는 시간을 없애줍니다. 어디에 넣을지 고민하고, 태그 달고, 관련 문서 찾아서 연결하는 작업을 AI가 대신 하니까, 사용자는 쓰고 읽는 것만 하면 됩니다. 쌓기만 하고 안 보는 노트앱이 아니라, 알아서 정리되니까 실제로 다시 찾아 쓰게 됩니다.

그리고 진짜 핵심은, 이렇게 정리된 볼트를 AI가 읽을 때 성능이 확 올라갑니다. 구조화된 프론트매터, 자동 인덱스, 관계 유형이 붙은 노트 링크, 폴더·카테고리 종합 페이지 덕분에 AI가 맥락을 정확히 파악하고, 필요한 문서를 빠르게 찾아냅니다. 내 지식이 잘 정리될수록 AI가 더 똑똑하게 일하는 구조입니다.

Obsidian 호환이고, Claude Code·Codex용 에이전트도 자동으로 심어줘서 "볼트 점검해줘" 한마디로 전체 건강 검사까지 됩니다.

---

Made by Hwaa