research

Naran 설계 세션 인계 문서

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 |

← research 목록으로홈으로