---
id: pattern-local-storage
title: "Local Storage Pattern"
category: "Pattern_Mobile"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["local storage", "로컬 저장 패턴", "key-value", "sqlite", "secure storage"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.86
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["pattern", "mobile", "storage", "persistence", "platform-independent"]
raw_sources: ["일반 모바일/클라이언트 공학 지식", "AstraAI/src/core/services.ts, eventSourcedStore.ts (적용 예)"]
applied_in: ["AstraAI"]
github_commit: ""
---

# [[Local Storage Pattern]]

## 🎯 한 줄 통찰 (One-line insight)
로컬 저장은 "데이터 성격에 맞는 매체를 고르는 것" 이 핵심 — 소량 설정은 key-value, 구조화 데이터는 SQLite, 민감정보는 보안 저장소, 대용량 파일은 파일시스템. 한 매체에 다 넣으면 성능·보안이 무너진다.

## 🧠 핵심 개념 (Core concepts)
1. **key-value(prefs):** 작은 설정/플래그.
2. **임베디드 DB(SQLite/Realm):** 구조화/쿼리 데이터.
3. **보안 저장소(Keychain/Keystore):** 토큰/비밀.
4. **파일시스템:** 이미지/대용량/캐시.
5. **마이그레이션:** 스키마 버전 관리.

## 📖 세부 내용 (Details · 패턴 명세)
- **Problem (언제 쓰나):** 앱이 디바이스에 데이터를 보존해야 할 때.
- **사용 조건:** 데이터 성격 분류; 용량/보안 요구 파악.
- **장점:** 오프라인, 빠른 접근, 네트워크 절약.
- **단점:** 디바이스 한정, 백업/동기화 별도, 보안 책임.
- **대안:** 서버 저장(동기화 필요), 캐시만(휘발).
- **실패 사례:** 토큰을 평문 prefs 에(보안 사고); 대용량을 key-value 에(성능); 마이그레이션 없어 업데이트 시 크래시; 캐시와 영구 데이터 혼동.

## 💻 코드 패턴 (Code patterns)
```text
prefs.set('theme', v)                  # 소량 설정
secureStore.set('token', t)            # 민감정보 (Keychain/Keystore)
db.exec('INSERT ...')                  # 구조화 데이터
fs.write(path, blob)                   # 대용량
onUpgrade(old, new): migrate(old→new)  # 스키마 버전
```
적용 예: AstraAI 는 설정=VS Code config/secrets, 지식=Markdown 파일, 이벤트=JSONL — *데이터 성격별 매체 분리* 원칙을 그대로([[ADR-0005 파일 기반 저장 채택]]).

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
"전부 SQLite" 나 "전부 key-value" 는 안티패턴 — 성격별 분리가 원칙. 민감정보는 *반드시* 보안 저장소.

## 🛠️ 적용 사례 (Applied in summary)
AstraAI secrets(토큰) + 파일(지식) + JSONL(이벤트).

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[패턴 카탈로그 인덱스]]
- **관련 개념:** [[Offline Sync Pattern]], [[Caching Pattern]], [[이벤트 소싱 스토어 패턴]], [[모바일 개발 가이드]]
- **참조 맥락:** 작은 모델이 클라이언트 저장을 설계할 때 참조.

## 📚 출처 (Sources)
- [S1] 일반 모바일 저장 지식
- [S2] AstraAI/src/core/services.ts, extension.ts(secrets), eventSourcedStore.ts — 적용 예

## 📝 변경 이력 (Change history)
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
