Inkling

기록 습관이 없는 사람도 3초 안에 던지고, 로컬 AI가 정리하고, 나중에 업무 자산으로 회수할 수 있게 해주는 데스크톱 메모 앱이다. "메모 = 잊기 전에 머리에서 꺼내는 1회 행동"으로 행동 기준을 낮추고, 정리는 Ollama가 맡는다.

이 저장소는 슬라이스 v0.4 단계다 — 가장 얇은 종단 경로(Quick Capture → SQLite → 로컬 Ollama → Inbox)만 동작한다. 음성·검색·내보내기·온보딩·캘린더 트리거는 후속 spec의 범위.

---

상태

• 버전: Slice v0.4
• 플랫폼: Windows(dogfood 우선) + macOS(빌드 통과 수준)
• 테스트: 단위 52/52, e2e smoke 1/1, typecheck/build 통과
• 종료 조건: 본인 2주 dogfood 완주 + AI 결과 7/10 수용 + 크래시 0회 (spec §1.3)

---

사전 요구

항목	버전/메모
Node	24.15.0 (.nvmrc) — Volta 권장, nvm-windows도 가능
Visual Studio Build Tools	2022 + "Desktop development with C++" 워크로드 (better-sqlite3 빌드용)
Ollama	LAN 서버에서 실행, gemma4:e4b 모델 pull (8.0B Q4_K_M, 효율 변형)
Git for Windows	최신

LAN Ollama 엔드포인트는 환경변수 INKLING_OLLAMA_ENDPOINT 로 주입한다.

INKLING_OLLAMA_ENDPOINT=http://192.168.0.47:11434

미설정 시 http://localhost:11434 로 폴백.

---

시작하기

# 1. 의존성 설치
npm install

# 2. 개발 모드 (electron-vite dev)
npm run dev

# 3. 프로덕션 빌드
npm run build

# 4. 빌드 결과 실행
npm start

전역 단축키: Ctrl+Shift+J (Windows) / Cmd+Shift+J (macOS). Quick Capture 창이 화면 중앙 상단에 뜬다. 한 줄 던지고 Ctrl+Enter 로 저장.

---

패키징 (Windows NSIS 인스톨러)

# Windows 개발자 모드 ON 필요 (winCodeSign 캐시 추출 시 darwin symlink 풀어야 해서)
# 설정 → 시스템 → 개발자용 → 개발자 모드 ON

npm run dist        # NSIS 인스톨러: dist/Inkling Setup x.y.z.exe
npm run dist:dir    # 패키징 없이 win-unpacked 디렉터리만

산출물:

• dist/Inkling Setup 0.2.0.exe — 약 100MB, oneClick=false (설치 위치 선택 가능)
• dist/win-unpacked/ — portable 디렉터리, 그대로 실행 가능

설치 후:

• 첫 실행 시 app.isPackaged === true 면 <프로필>/.autostart-init 마커가 없을 때 한정 자동 시작 ON 으로 설정 (--hidden 인자 포함, inbox 창 안 뜨고 트레이만)
• 이후 트레이 메뉴 → "윈도우 시작 시 자동 실행" 토글로 조작
• 자동 시작 시 inbox 창은 안 뜸. Ctrl+Shift+J 또는 트레이 클릭으로 호출

---

테스트

# 단위 테스트 (vitest)
npm test

# 통합 테스트 (실제 Ollama 호출, 게이트됨)
npm run test:integration

# e2e smoke 테스트 (Playwright + Electron)
npm run test:e2e

# 타입 체크
npm run typecheck

Native ABI 함정

better-sqlite3 는 두 가지 런타임에서 호출된다 — vitest(Node ABI)와 Electron(ABI 145). 한 번에 한 ABI 로만 빌드되므로 npm 스크립트가 자동으로 prebuild-install 을 돌린다.

• pretest / pretest:integration → rebuild:node
• pretest:e2e / prestart / predev → rebuild:electron

새 native dep 을 추가하거나 Electron 메이저 버전을 올리면 package.json 의 rebuild:* 스크립트도 갱신해야 한다.

ELECTRON_RUN_AS_NODE 함정

이 환경변수가 부모 셸에 살아있으면 Electron main-process 모듈 hook 이 비활성화돼 require('electron') 이 path string 만 반환한다. e2e 스펙에서 launch env 단계에 명시적으로 strip 한다. 새 main-launch 스크립트를 작성할 때도 동일 strip 필요.

---

아키텍처

src/
  main/              Electron main process
    db/              SQLite + 마이그레이션
    repository/      NoteRepository (CRUD + edited-flag overwrite guard)
    services/        Capture, Continuity, Hotkey, Intent, Notification, MediaStore, MediaGc, HealthChecker
    ai/              InferenceProvider 인터페이스 + LocalOllamaProvider + AiWorker (3-attempt backoff)
    ipc/             contextBridge용 IPC 핸들러
    windows/         Inbox + QuickCapture BrowserWindow 팩토리
    tray.ts          Tray 아이콘 + 메뉴
    paths.ts         프로필 디렉터리 해석
    logger.ts        electron-log 래퍼 (raw_text 절대 미기록)
  preload/           contextBridge로 typed API expose
  renderer/
    inbox/           React 19 + Zustand 스토어
    quickcapture/    React 19, frameless 640x280
  shared/
    types.ts         IPC 계약 타입
    intentPrompts.ts 의미 한 줄 회전 카피 4종
tests/
  unit/              vitest, 52 cases
  integration/       Ollama golden test (게이트됨)
  e2e/               Playwright smoke
docs/
  superpowers/specs/    설계 문서
  superpowers/plans/    구현 계획
  superpowers/strategy/ 심리학·dogfooding 전략
  handoff/              세션 간 핸드오프
inkling.md         원본 제품 브리프 v1.4

핵심 흐름은 Capture → Clarify → Capitalize 3단계 (Strategy §2). 슬라이스에서는 Capture + Clarify 만 다루고 Capitalize(Confluence 내보내기·주간 회고) 는 후속.

---

Load-bearing 불변 (재논의 금지)

이 규칙들은 spec, 테스트, 코드 곳곳에 박혀 있다. 변경하려면 spec v0.4 §3.3 부터 다시 검토.

1. raw_text 는 불변. update method 없음. 추가 금지.
2. AI 재실행은 user-edited 필드를 덮어쓰지 않는다. *_edited_by_user 컬럼 + CASE WHEN 가드.
3. IntentBanner 는 노트당 정확히 1회. intent_prompted_at IS NULL 이 게이트. setIntent · dismissIntent 둘 다 게이트 닫음.
4. 로그에 본문 금지. raw_text / ai_title / ai_summary / user_intent 내용 절대 미기록. ID, 길이, 해시 prefix 만.
5. "실패", "끊김", "연속 실패" 단어는 모든 UI 문자열에서 금지. 회복 친화 톤이 강제.
6. 네이티브 알림은 submit 을 절대 막지 않는다. 권한 거부 = silent fallback. 캡처는 계속 동작.
7. 버전은 정확 pin (^ 금지). package.json 갱신 시 spec §7.2 와 동시 업데이트.

---

Quick Capture 제약

• 단일 입력창, 텍스트 + 클립보드 이미지만.
• 제목·태그·폴더 선택 강요 안 함 (Strategy §2.1).
• 저장 직후 OS 네이티브 토스트 1개 (회전 카피 4종).
• AI 처리는 비동기 — 저장은 즉시, 정리는 백그라운드.

Inbox 제약

• 날짜 내림차순 리스트, 같은 ms 동기화 시 id DESC 보조 정렬.
• AI 필드(제목·요약) 는 인라인 편집 가능. 편집 시 *_edited_by_user=1 셋 → 이후 AI 재실행은 해당 필드 보존.
• 원문은 read-only.
• AI 가 생성한 필드 옆에 회색 "AI" 라벨. 사용자 편집 시 라벨 사라짐 ("내 메모" 정체성 표시).
• "의미 한 줄" 배너는 AI done 직후 1회만, skip 시 해당 카드에선 다시 안 뜸.
• Weekly Continuity 배지: 7건/주 (KST 월~일). 0/7 도 "이번 주 한 줄이면 시작입니다".

---

문서

문서	경로	용도
제품 브리프	inkling.md	원본 v1.4, 전체 비전
심리학 전략	docs/superpowers/strategy/strategy.md	행동 변화 모델, 회복 친화 스트릭
Dogfooding 전략	docs/superpowers/strategy/dogfood-strategy.md	2주 자기 dogfood 운영안
슬라이스 설계	docs/superpowers/specs/2026-04-24-inkling-vertical-slice-design.md	v0.4 spec, 부하 전달 결정의 출처
Dogfood 피드백	docs/superpowers/specs/2026-04-25-dogfood-feedback.md	슬라이스 dogfood 중 발견된 본인 피드백 수집 (living document)
구현 계획	docs/superpowers/plans/2026-04-24-inkling-vertical-slice.md	33-task TDD 플랜
핸드오프	docs/handoff/2026-04-25-linux-to-windows.md	Linux→Windows 전환 메모

---

원격 백업 (선택, F6-L2)

Inkling 데이터를 사적 git 원격에 백업하려면 한 번만 설정하면 된다. 인코딩된 형식이 아니라 평문 마크다운(F5 export 형식)으로 저장되니, 반드시 비공개 repo 를 사용한다.

일회 설정

# 1. 빈 사적 repo 생성 (예: gitea, GitHub private)

# 2. 데이터 디렉터리에 git 초기화 + 원격 등록
cd "%APPDATA%\Inkling\Inkling\profiles\default\sync"   # Windows
git init
git remote add origin https://your-host/owner/inkling-data.git
git fetch origin || true   # 빈 repo 면 무시

# 3. 자격증명 설정 (Windows Credential Manager 자동 / 또는 token 임베드 URL)

# 4. 첫 동기화: 트레이 → "지금 동기화"

처음 sync 시 SyncService 가 <profileDir>/sync/ 안에 F5 export 트리(notes/, media/, index.jsonl, manifest.json)를 덮어쓰고 git add -A && git commit && git push -u origin <branch> 를 자동 수행.

사용

• 트레이 → "지금 동기화" 로 수동 트리거
• 앱 종료 시 자동 1회 (sync dir 이 설정된 경우만)
• 변경 없으면 토스트 "변경 사항 없음", 변경 있으면 "동기화 완료"

설정이 안 됐으면 트레이 토스트로 안내. 한 번 설정하면 이후 push 는 OS credential helper 가 자동 처리.

데이터 라이프사이클 측면에서 F6-L1 (로컬 스냅샷, 자동) + F5/F6-L3 (수동 export/import) + F6-L2 (원격 git, 반자동) 3-layer 구조의 마지막 layer.

---

라이선스

비공개. 본인 dogfood + 10인 사내 베타까지의 스코프.