---
id: adr-0005-file-based-storage
title: "ADR-0005 파일 기반 저장 채택"
category: "Architecture_Decision"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["ADR storage", "왜 DB 안 쓰나", "Markdown JSONL 저장", "파일 저장 결정"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.89
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["adr", "storage", "decision", "filesystem", "connectai"]
raw_sources: ["ConnectAI/src/core/services.ts", "ConnectAI/src/features/_shared/eventSourcedStore.ts", "ConnectAI/src/intelligence/correctionLoop.ts"]
applied_in: ["ConnectAI"]
github_commit: ""
---

# [[ADR-0005 파일 기반 저장 채택]]

## 🎯 한 줄 통찰 (One-line insight)
지식·메모리·로그를 DB 가 아니라 **Markdown(.md) + JSON/JSONL 파일**로 저장하기로 결정했다 — 사람이 직접 열어 읽고/고치는 투명성(Permission Based Learning)과 무의존성이 단일 사용자 로컬 도구에 최적이기 때문 [S1][S3].

## 🧠 핵심 개념 (Core concepts)
- **결정:** brain 지식=Markdown(frontmatter), 이벤트/케이스=JSONL, 설정/프로필=JSON.
- 검색은 파일 위 TF-IDF/임베딩 인덱스([[RAG 검색 파이프라인]]).

## 📖 세부 내용 (Details · ADR)
### Problem
지식/메모리/학습 데이터를 어디에 저장할 것인가. DB 는 강력하지만 단일 사용자 로컬 확장에 운영·마이그레이션·불투명성 비용을 더한다.

### Context
- 사용자가 두뇌 내용을 직접 보고 수정/삭제할 수 있어야 한다(투명성·신뢰).
- VS Code/에디터로 그대로 열람 가능해야(Markdown).
- 번들 의존성 최소화(런타임 deps 2개).

### Options Considered
1. **SQLite/임베디드 DB** — 쿼리·트랜잭션 강력, 그러나 불투명·의존성·스키마 관리.
2. **벡터 DB** — 의미 검색 최적, 그러나 인프라·운영 부담, 사람이 못 읽음.
3. **파일 기반(Markdown + JSONL + JSON)** — 투명·무의존·버전관리(git) 친화.

### Chosen Solution
3번. 지식은 frontmatter 달린 Markdown, 이벤트/정정 케이스는 append-only JSONL, 프로필/설정은 JSON. 검색은 파일 위 인덱스로 보강 [S1][S2][S3].

### Why It Was Chosen
사람이 읽고 고치는 투명성이 신뢰의 핵심(특히 자기학습 시스템). git diff 로 변경 추적. 의존성 0 으로 배포 단순.

### Benefits
투명성, 무의존, git 친화, 에디터 직접 열람, 백업/이동 단순(폴더 복사).

### Drawbacks
복잡한 쿼리/조인 불가, 대량 데이터에서 스캔 비용, 동시쓰기 잠금 직접 관리, 인덱스를 직접 구축해야 함.

### Future Risks
brain 이 수만 파일로 커지면 파일 스캔/인덱싱 비용 급증. 트랜잭션이 약해 다중 파일 일관성은 보상 트랜잭션에 의존.

### Alternative Approaches
규모 확대 시 SQLite(메타데이터) + 파일(본문) 하이브리드, 또는 임베딩만 벡터 DB 로 외부화하고 본문은 파일 유지.

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
"검색·쿼리 성능" 만 보면 DB 가 우위다. 이 결정은 *투명성·무의존* 을 성능보다 우선한 가치 판단 — 멀티유저/대규모면 뒤집힌다.

## 🛠️ 적용 사례 (Applied in summary)
brain Markdown(BrainService.inject), JSONL 이벤트 스토어, corrections.jsonl / weakness-profile.json [S1][S2][S3].

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
- **관련 개념:** [[ADR-0001 이벤트 소싱 채택]], [[이벤트 소싱 스토어 패턴]], [[Local Storage Pattern]], [[Caching Pattern]]
- **참조 맥락:** 로컬 LLM 이 "DB vs 파일" 저장 방식을 결정할 때 참조.

## 📚 출처 (Sources)
- [S1] ConnectAI/src/core/services.ts — BrainService Markdown 저장
- [S2] ConnectAI/src/features/_shared/eventSourcedStore.ts — JSONL 이벤트
- [S3] ConnectAI/src/intelligence/correctionLoop.ts — JSONL/JSON 케이스·프로필(투명성)

## 📝 변경 이력 (Change history)
- 2026-06-13: ConnectAI 코드 분석 기반 ADR 작성.
