Naran 설계 세션 인계 문서

작성: 2026-03-31 목적: 설계하자 세션 → 새 대화창 인계용 compact 맥락

프로젝트 한 줄 정의

Naran = zeroclaw 위에 도메인 레이어를 얹는 개인 생산성 시스템.
zeroclaw가 실행을 담당하고, Naran은 "무엇을 언제"를 결정한다.

서버: 로컬 GPU 서버 (RTX 5080)
GitHub repo: maullim/naran (main branch)

확정된 아키텍처 (ADR-001 ~ ADR-011)

ADR	결정
001	Naran = 별도 MCP 서버, zeroclaw upstream 건드리지 않음
002	naran.db = MySQL
003	Task = 구조체(상태 없음), Event = Task의 상태(시간 블록)
004	rules 별도 테이블 + task_rules/event_rules 관계 테이블
005	Event Rule → zeroclaw cron_jobs 변환 (name 인코딩)
006	반복 Event — Hybrid Materialization (1년 이내 eager, 초과 lazy)
007	LLM 구동 = llama.cpp (localhost:8080/v1, GGUF)
008	LLM 권한 = ReadOnly 시작 → 테스트 후 단계적 확대
009	브라우저 자동화 = zeroclaw BrowserTool(원자) + Naran Skill(goal 순서)
010	Privacy Boundary = age 암호화 파일 + sensitive_login Tool (heuristic → local LLM fallback, TOTP 자동)
011	zeroclaw = 직접 clone (포크 없음), config는 naran repo zeroclaw-config/에서 관리

DB 스키마 (naran.db MySQL, v4 확정)

tasks                    Task 구조체 (상태 없음)
rules                    rule 정의 저장소
task_rules               Task ↔ Rule 관계
event_rules              Event ↔ Rule 관계
events                   Task의 상태 (시간 블록)
event_series             반복 규칙 (rrule)
event_series_exceptions  삭제/수정된 인스턴스

Task 상태는 events에서 파생: unscheduled / scheduled / overdue / complete

v1 / v2 기능 범위

v1

대화 클라이언트 (claw /ws/chat)
Task/Event/Rule CRUD (ReadOnly 시작)
Cron 관리 UI
브라우저 자동화 (BrowserTool + Skill)
Privacy Boundary (age + sensitive_login Tool)

v2 이관

데스크탑 자동화 (enigo + rdev)
Android 알림 수신 (NotificationListenerService)
cross-platform 2FA
Generative UI (render_hint 기반)

서버 경로 구조

~/llama.cpp/         설치됨
~/AI_MODELS/         GGUF 모델 있음
~/[claw]/            미설치 (claw 선택 후 결정)
~/naran/             Naran repo
  ├── CLAUDE.md
  ├── feature_list.json   F-01 ~ F-14
  ├── context-bridge.md
  ├── docs/
  │   ├── architecture.md
  │   └── decisions.md    ADR-001~011
  ├── mcp-server/
  ├── client/
  ├── skills/
  └── zeroclaw-config/    config.toml, init.sh

feature_list.json (F-01 ~ F-14)

ID	Group	내용
F-01	infra	claw + llama.cpp 환경 구성
F-02	storage	MySQL naran.db 스키마 생성
F-03	infra	Naran MCP 서버 기본 구조
F-04	server	Task CRUD MCP Tools
F-05	server	Rule CRUD MCP Tools
F-06	server	Event CRUD MCP Tools (단독)
F-07	server	Event Rule + cron_jobs 변환
F-08	server	반복 Event (Hybrid Materialization)
F-09	server	sensitive_login Tool (Privacy Boundary)
F-10	server	Browser Skill 파일
F-11	client	Tauri 기본 구조
F-12	client	Chat UI
F-13	client	Task/Event UI (캘린더 + 태스크 뷰)
F-14	client	Cron 관리 UI

🔴 현재 미결 — 새 대화창에서 시작할 것

claw 선택: ZeptoClaw vs LoongClaw

zeroclaw(theonlyhennygod/zeroclaw, 4.6K⭐)가 접근 불가 상태.

후보 A: ZeptoClaw (qhkm/zeptoclaw)

Rust, ~6MB, 3,900+ tests, Apache 2.0
Library Facade 제공: ZeptoAgent::builder().tool(t).build()
→ Naran MCP 서버를 별도 프로세스로 분리하는 대신, ZeptoClaw를 Naran 안에 crate로 embed
→ ADR-001 (별도 MCP 서버 구조) 재검토 필요
OpenAI-compatible ✅, Cron ✅, BrowserTool ✅
config.json 방식

후보 B: LoongClaw (loongclaw-ai/loongclaw)

Rust, governance-first, 7-crate workspace, MIT
Extension Planes: tool plane에 어댑터 추가 (코드 수정 필요)
→ 기존 ADR-001 MCP 구조 유지 가능
OpenAI-compatible ✅, Cron ✅, BrowserTool ✅
config.toml 방식
dev branch 기반, 아직 성숙도 낮음

핵심 트레이드오프

ZeptoClaw → Library Facade로 구조 단순화
            ADR-001 (별도 MCP 서버) 재검토 필요
            성숙한 코드베이스

LoongClaw → 기존 ADR-001 MCP 구조 유지
            Extension 방식으로 Naran Tool 추가
            dev branch, 아직 불안정

파일	위치
DB 스키마	knowledge vault: research/naran-scheduling/naran-data-model.md
미결사항	knowledge vault: research/naran-scheduling/naran-open-decisions.md
architecture.md	maullim/naran: docs/architecture.md
decisions.md	maullim/naran: docs/decisions.md
context-bridge	maullim/naran: context-bridge.md

Naran 설계 세션 인계 문서

Naran 설계 세션 인계 문서

프로젝트 한 줄 정의

확정된 아키텍처 (ADR-001 ~ ADR-011)

DB 스키마 (naran.db MySQL, v4 확정)

v1 / v2 기능 범위

v1

v2 이관

서버 경로 구조

feature_list.json (F-01 ~ F-14)

🔴 현재 미결 — 새 대화창에서 시작할 것

claw 선택: ZeptoClaw vs LoongClaw

후보 A: ZeptoClaw (qhkm/zeptoclaw)

후보 B: LoongClaw (loongclaw-ai/loongclaw)

핵심 트레이드오프

관련 문서 위치