# parksy-brain 개발 계획서 — 누적 에이전트 LLM

> **작성일:** 2026-06-05  
> **버전:** v3.0 (라벨 정의 + 롤백 체계 + 헌법 외부 규칙 분리 추가)  
> **분류:** 인프라 / AI 엔진  
> **상태:** 설계 확정, 구현 대기  
> **원본:** `dtslib-papyrus/docs/PARKSY-BRAIN-CUMULATIVE-LLM-PLAN-20260605.md`  
> **미러:** `parksy-logs/docs/plan/PARKSY-BRAIN-CUMULATIVE-LLM-PLAN-20260605.md`

---

## 1. 프로젝트 정의

### 1-1. 무엇인가

**parksy-brain** = DTSlib 에이전트 생태계 전용 누적 LLM.

박씨의 의사결정 패턴, 양산 이벤트, 감사 로그를 지속적으로 먹여서  
**기존 은하계(운영 중인 레포/파이프라인/패턴)를 스스로 관리하는 내부 집장.**

### 1-2. 누적 모델 vs 스냅샷 모델 (핵심 구분)

| 항목 | 스냅샷 파인튜닝 | parksy-brain (누적 모델) |
|------|----------------|--------------------------|
| 학습 방식 | 한 시점 데이터 전체를 한 번에 학습 | 이벤트 발생 시마다 델타 3~10줄씩 추가 |
| 데이터 성격 | 정적 (학습 시점에 고정) | 동적 (살아있는 로그가 계속 쌓임) |
| 트리거 | 수동 (사람이 데이터 준비 후 실행) | 자동 (양산 이벤트 100개 누적 시 자동 발동) |
| 모델 성격 | 사진 | 유기체 (먹을수록 자란다) |
| 목표 | 특정 기술 습득 | 박씨 운영 맥락의 집장 |

**요점:** 스냅샷은 클론 시도다. parksy-brain은 클론이 아니라 **맥락 축적기**다.

---

## 2. 역할 매트릭스

```
박씨
  → 방향 제시, 다음 은하계 설계, OK/NO 결재
  → 이전 은하계에는 개입하지 않는다

Claude (메인)
  → 외부 기준점 (최신 AI 역량 벤치마크)
  → 새 은하계 설계, 법률/헌법 해석, 고난도 판단
  → parksy-brain이 막히면 최후 판단

DeepSeek / aider
  → 실행기 (렌더·패치·반복 작업)
  → parksy-brain 지시 수행

parksy-brain
  → 내부 집장 (기존 은하계 관리)
  → 양산 루프 자율 실행
  → 박씨 의사결정 패턴 재현
  → Claude를 부르지 않아도 되는 판단들 처리
```

**목표 상태:**  
박씨가 다음 은하계(신규 사업/시스템)를 설계하는 동안,  
parksy-brain이 기존 15채널 유튜브, 텔레그램, 배포 파이프라인을 자율 운영.

---

## 3. 데이터 이원화 아키텍처 — 플로우 vs 스탁

> **핵심 설계 원칙: 손익계산서 + 대차대조표 두 축을 동시에 먹인다.**

박씨를 복제하는 키는 코드만이 아니라 **대화와 판단 흔적**에 있다.  
단, 대화 로그만 있으면 말투는 복제돼도 실제 선택 구조가 빠진다.  
두 축을 합쳐야 "말투 + 판단 + 최종 선택"이 전부 학습된다.

### 3-1. FLOW 축 — 손익계산서 (동적)

> **"그 순간 무슨 생각을 했고 어떻게 판단했는가"**

| 소스 | 레포/위치 | 내용 |
|------|----------|------|
| **박씨캡처 APK** | `dtslib-apk-lab` → `~/parksy-logs/raw/` | 박씨↔LLM 대화 전문. 말투, 사고 흐름, 세계관 연결 방식, 분노 포인트, 취향 |
| **아카이브 로그 레포** | `~/parksy-logs/` 전체 | 누적 대화 히스토리, finetune JSONL, 발화 예시 |
| audit.jsonl | `parksy_law_mcp.py` | check_policy 통과/차단 이벤트, 정신 상태 기록, 의사결정 판정 |
| 텔레그램 OK/NO | 배포 파이프라인 결과 | 결재 신호, 승인 논리, 퇴짜 패턴 |
| 양산 결과 | `run_and_publish()` 출력 | 콘텐츠 단위 성공/실패, 생산 로그 |

**FLOW 데이터가 주는 것:**
- 박씨가 어떻게 말하는가
- 어떤 순서로 생각이 전개되는가
- 어떤 시점에 승인/퇴짜를 치는가
- 짜증의 원인과 패턴

### 3-2. STOCK 축 — 대차대조표 (정적 누적)

> **"결국 무엇이 남았고 어떻게 발전했는가"**

| 소스 | 위치 | 내용 |
|------|------|------|
| **GitHub 28개 레포 전체** | `git log --reverse` | 누적 커밋 히스토리 = 트랜잭션 원장 |
| **git diff summary** | 각 레포 | 코드 변화, 아키텍처 진화, 결정 흔적 |
| law/*.md | `dtslib-papyrus/law/` | 헌법·SOP — 살아남은 규칙들의 결정체 |
| 최종 산출물 | `/mnt/d/PARKSY/` | 실제 배포된 콘텐츠, 확정된 자산 |

**STOCK 데이터가 주는 것:**
- 어떤 코드가 살아남고 어떤 게 폐기됐는가
- 아키텍처가 어떻게 진화했는가
- 리버스 엔지니어링 → 발전상 확인
- 어떤 규칙이 최종적으로 헌법에 새겨졌는가

### 3-3. 두 축을 연결하는 접합부

```
FLOW (대화, 판단)  ──┐
                     ├──→ parksy-brain 학습 재료
STOCK (git, 레포) ──┘

접합부 (연결 신호):
  audit.jsonl      → 어떤 행동이 허용/차단됐는가
  git commit msg   → FLOW의 판단이 STOCK으로 굳어지는 순간
  텔레그램 OK/NO   → 박씨 결재가 STOCK 확정으로 이어지는 신호
```

### 3-4. 박씨캡처 APK — 데이터 먹이 창고 설계

```
박씨캡처 APK (dtslib-apk-lab)
  ↓ 대화 자동 캡처
~/parksy-logs/raw/capture_YYYYMMDD.jsonl
  ↓ 정제 파이프라인 (기존 parksy_v3_300.jsonl 방식 그대로)
~/parksy-logs/finetune/brain_feed_YYYYMMDD.jsonl
  ↓ brain_log_event() 호출
~/parksy-logs/brain_delta/delta_*.jsonl
  ↓ 100개 누적
Vast.ai RTX 3090 → LoRA 학습 트리거
```

**아카이브 로그 레포 (`parksy-logs`) = 데이터 먹이 창고 본체**

```
~/parksy-logs/
├── raw/                    ← 박씨캡처 APK 원본 수신
├── finetune/               ← 정제된 학습 데이터
│   ├── parksy_v3_300.jsonl ← 기존 발화 예시 300개
│   └── brain_feed_*.jsonl  ← 신규 박씨캡처 정제본
├── brain_delta/            ← 증분 학습용 델타
│   ├── delta_*.jsonl
│   └── manifest.json
└── stock/                  ← STOCK 축 요약
    ├── git_summary_28repos.jsonl  ← git log 요약
    └── law_snapshot_*.md          ← 헌법 스냅샷
```

---

## 4. 델타 수집 파이프라인

### 4-1. 트리거 조건

```
이벤트 발생 (아래 중 하나)
├── 박씨캡처 APK → 신규 대화 수신
├── run_and_publish() 완료
├── 박씨 텔레그램 OK/NO 수신
├── check_policy() audit_log 기록
└── git commit (papyrus 또는 15채널 레포)
         ↓
JSONL 3~10줄 자동 생성
         ↓
~/parksy-logs/brain_delta/delta_YYYYMMDD_HHMMSS.jsonl 누적
         ↓
100개 누적 → LoRA 증분 학습 트리거
```

### 4-2. 델타 JSONL 포맷 (이벤트 유형별)

**대화 캡처 이벤트 (박씨캡처 APK → FLOW):**
```jsonl
{"event": "conversation", "source": "parksy_capture", "user": "이거 됐어? 다시 해봐", "agent": "claude", "ts": "2026-06-05T13:22:00+09:00", "mood_signal": "impatient"}
```

**양산 이벤트:**
```jsonl
{"event": "publish", "content": "philosopher-parksy 쇼츠 3개", "result": "ok", "ts": "2026-06-05T14:32:00+09:00", "parksy_response": "OK"}
```

**check_policy 이벤트:**
```jsonl
{"event": "policy_check", "command": "git reset --hard", "verdict": "blocked", "rule": "헌법 제2조 reset --hard 금지", "ts": "2026-06-05T15:10:00+09:00"}
```

**박씨 결재 이벤트:**
```jsonl
{"event": "approval", "context": "philosopher-parksy 업로드 보고", "decision": "OK", "delay_seconds": 42, "ts": "2026-06-05T14:33:42+09:00"}
```

**git commit 이벤트 (STOCK 스냅샷):**
```jsonl
{"event": "git_commit", "repo": "dtslib-papyrus", "message": "docs: parksy-brain 계획서 추가", "files_changed": 1, "ts": "2026-06-05T17:00:00+09:00"}
```

### 4-3. manifest.json

```json
{
  "total_events": 247,
  "flow_events": 189,
  "stock_snapshots": 58,
  "last_trained_at": "2026-06-03T10:00:00+09:00",
  "events_since_last_train": 147,
  "next_train_trigger": 300,
  "model_version": "parksy-brain-v0.3",
  "capture_sources": ["parksy_capture_apk", "audit_jsonl", "telegram_okno", "git_log"]
}
```

---

## 5. 증분 학습 구조

### 5-1. 베이스 모델

```
베이스: Mistral-7B-Instruct-v0.3 (HuggingFace 공개)
이유:
  - 한국어 소규모 파인튜닝 커뮤니티 검증 多
  - 7B = RTX 3090 24GB 한 장으로 LoRA 학습 가능
  - 추론 시 CPU fallback 가능 (4bit 양자화)
대안: Qwen2.5-7B-Instruct (한국어 성능 우수, 멀티언어 강점)
```

### 5-2. LoRA 증분 학습 (Vast.ai RTX 3090)

```
트리거: 누적 이벤트 100개 초과 (manifest.json 기준)
소요: ~30분
비용: ~$1 (RTX 3090 $0.211/hr × 30분)
출력: LoRA 어댑터 (.safetensors, ~50MB)
저장: ~/parksy-audio/voice_models/brain/
```

**학습 원칙:**
- 어댑터 덮어쓰기 금지 → 버전 누적 (brain-v0.1, brain-v0.2, ...)
- 이전 어댑터 + 신규 델타 = 합산 학습 (망각 방지)
- FLOW와 STOCK 데이터를 **3:1 비율**로 혼합 학습 (대화 중심 유지)
- 학습 완료 후 Vast.ai 인스턴스 박씨 확인 전 terminate 금지

### 5-3. 추론 환경

```
로컬 CPU (WSL):
  - 4bit 양자화 (llama.cpp 또는 transformers BitsAndBytes)
  - 응답 시간: 5~15초/회 (배치 작업에 적합)

Vast.ai (인스턴스 재사용):
  - 실시간 추론 필요 시
  - RTX 3090 → 1~2초/회
```

---

## 6. 배포 구조 — parksy-brain MCP

### 6-1. MCP 툴 목록 (v1 범위)

| 툴 이름 | 역할 |
|---------|------|
| `brain_infer(context, task)` | 기존 패턴 기반 판단 수행 |
| `brain_log_event(event_dict)` | 델타 JSONL 기록 (FLOW/STOCK 분류 자동) |
| `brain_manifest_check()` | 누적 카운트 확인, 학습 트리거 판단 |
| `brain_train_trigger()` | Vast.ai 학습 잡 발동 |
| `brain_version_info()` | 현재 모델 버전 + 학습 이력 |
| `brain_capture_ingest(raw_jsonl)` | 박씨캡처 APK 원본 수신 → 정제 → delta 등록 |

### 6-2. 기존 자산 연동

```
박씨캡처 APK (dtslib-apk-lab)
  → 대화 캡처 → brain_capture_ingest() → FLOW delta 등록

parksy-law MCP
  → check_policy() → brain_log_event() 자동 기록

parksy-scm MCP
  → run_and_publish() 완료 → brain_log_event() 자동 기록

parksy-logs (아카이브 레포)
  → 데이터 먹이 창고 본체
  → FLOW: raw/ + finetune/
  → STOCK: stock/ (git 요약, 헌법 스냅샷)

parksy-brain MCP
  → brain_infer() → 패턴 기반 판단 반환
  → 판단 불가 시 → Claude에게 에스컬레이션
```

### 6-3. 자율 루프 예시

```
스케줄: 매일 09:00 KST
  ↓
brain_manifest_check() → 누적 이벤트 확인
  ↓
brain_infer("오늘 philosopher-parksy 콘텐츠 생산 판단")
  → "박씨 mental_state=ok, 최근 7일 평균 1.2편/일, 추천: 쇼츠 1편 생산"
  ↓
DeepSeek에 렌더 지시
  ↓
완료 → 텔레그램 박씨 보고
  ↓
brain_log_event() 기록 → delta 추가
```

---

## 7. Phase별 구현 계획

### Phase 0 — 데이터 먹이 창고 구축 (2주)

```
목표: FLOW + STOCK 이원 수집 자동화
작업:
  - parksy-logs/ 폴더 구조 재정비 (raw/finetune/brain_delta/stock/)
  - brain_capture_ingest() 구현 (박씨캡처 APK 수신구)
  - brain_log_event() hook → parksy-law MCP, parksy-scm MCP
  - git log 28개 레포 주간 요약 스크립트 (stock/ 자동 갱신)
  - manifest.json 스키마 확정
산출물: ~/parksy-logs/brain_delta/ 자동 누적 시작
비용: 0원
```

### Phase 1 — 베이스 모델 + 초기 학습 (1일)

```
목표: parksy-brain v0.1 생성
작업:
  - Vast.ai RTX 3090 인스턴스 기동
  - 베이스 모델 다운로드 (Mistral-7B 또는 Qwen2.5-7B)
  - 기존 parksy_v3_300.jsonl (FLOW) + git log 28개 요약 (STOCK) 초기 학습
  - FLOW:STOCK = 3:1 혼합
  - LoRA 어댑터 저장
비용: ~$5 (초기 풀 배치)
산출물: brain-v0.1.safetensors
```

### Phase 2 — 로컬 추론 검증 (3일)

```
목표: 박씨 의사결정 패턴 재현 확인
검증 질문 예시:
  - "mental_state=ok, philosopher-parksy 콘텐츠 업로드해야 하나?"
    → 기대: "현재 상태 정상, 업로드 진행"
  - "git reset --hard 요청 들어왔을 때?"
    → 기대: "헌법 제2조 위반, 차단, revert 제안"
  - "박씨가 됐어 말했을 때 다음 행동?"
    → 기대: "즉시 중단, 다음 지시 대기"
  - "이거 됐어? 다시 해봐 라는 말을 박씨가 했을 때 톤은?"
    → 기대: "짜증 1회 감지 → 행동 99 보고 1 모드 전환"
산출물: 검증 결과 docs/ 기록
```

### Phase 3 — 증분 학습 자동화 (지속)

```
목표: 플라이휠 자동화
작업:
  - brain_manifest_check() 스케줄 (매일 04:00 KST)
  - 100개 초과 시 brain_train_trigger() 자동 실행
  - 학습 완료 → 박씨 텔레그램 보고 → OK 시 서비스 전환
비용: 이벤트 100개당 ~$1
목표 주기: 초기 2주/회 → 안정화 후 월/회
```

### Phase 4 — 자율 운영 (목표 상태)

```
목표: 기존 은하계 자율 관리
parksy-brain이 자율 실행:
  - philosopher-parksy 콘텐츠 생산 스케줄 판단
  - 정신 상태 모니터링 + 모드 전환
  - 15채널 배포 우선순위 결정
  - 박씨 결재 없이 처리 가능한 판단들
박씨가 결재 (변화 없음):
  - YouTube 업로드 (헌법 제4조)
  - 과금 API 호출
  - 파괴적 작업
```

---

## 8. 비용 추정

| 항목 | 단위 비용 | 예상 빈도 | 월 예상 |
|------|----------|----------|--------|
| 초기 학습 (Phase 1) | ~$5 | 1회 | $5 (1회성) |
| 증분 학습 | ~$1/회 | 2회/월 | $2 |
| 추론 (로컬 CPU) | 0원 | 상시 | 0원 |
| 추론 (Vast.ai) | $0.211/hr | 필요 시만 | $2~5 |
| **월 합계** | | | **$4~7** |

Claude Pro 29,000원 + DeepSeek $20 체계에서 추가 20% 이내.

---

## 9. 플라이휠 구조

```
박씨캡처 APK → 대화 누적
git commit → STOCK 누적
run_and_publish() → 양산 누적
텔레그램 OK/NO → 결재 누적
        ↓ 100개
LoRA 증분 학습 ($1)
        ↓
parksy-brain 업데이트
        ↓ 판단 정확도↑
위임 가능 범위↑
        ↓
박씨 → 다음 은하계 설계에 집중
        ↓
신규 은하계 = 또 다른 양산 루프
        ↓
양산↑ → 박씨캡처 더 쌓임 (처음으로 돌아감)
```

---

## 10. 추가 설계 — 데이터 품질 + 안전 장치

### 10-1. 델타 JSONL 라벨 정의 (학습용 포맷)

parksy-brain은 단순 텍스트 예측이 아니라 **판단형 에이전트**를 목표로 한다.  
그러므로 학습 데이터는 preference 쌍 형식으로 구성한다.

```
형식: DPO (Direct Preference Optimization)
  chosen    = 박씨가 실제 채택한 응답/행동
  rejected  = 박씨가 퇴짜 친 응답/행동 or 헌법 위반 행동

예시 1 — 박씨 결재 패턴:
{
  "prompt":   "philosopher-parksy 쇼츠 업로드 보고 후 박씨 반응",
  "chosen":   "OK",
  "rejected": "나중에 해"
}

예시 2 — 정책 판단:
{
  "prompt":   "git reset --hard 요청이 들어왔을 때",
  "chosen":   "헌법 제2조 위반 → 차단 → revert 제안",
  "rejected":  "그냥 실행"
}

예시 3 — 멘탈 감지:
{
  "prompt":   "박씨가 '왜 이렇게 하냐' 말했을 때",
  "chosen":   "보고 중단, 행동 99 모드 전환",
  "rejected": "현재 작업 계속 진행"
}
```

**수집 규칙:**
- audit.jsonl의 `verdict=blocked` → rejected 자동 태깅
- 텔레그램 OK → chosen, "다시 해"/"됐어" → rejected
- 박씨캡처 APK 대화 중 박씨가 수정 요청한 직전 Claude 응답 → rejected

### 10-2. 롤백 / 버전 관리

```
어댑터 저장 구조:
~/parksy-logs/brain_models/
├── brain-v0.1.safetensors     (초기 학습)
├── brain-v0.2.safetensors     (1차 증분)
├── brain-v0.3.safetensors     (2차 증분)
├── ...
├── brain-latest → brain-v0.3  (symlink, 현재 서비스 중)
└── brain-stable → brain-v0.2  (롤백 기준점)
```

**롤백 트리거:**
- brain_infer()가 헌법 위반 판단을 내릴 때 (check_policy에서 감지)
- 박씨 텔레그램 "이상해" 신호 수신 시
- 롤백: `brain-latest` symlink를 `brain-stable`로 전환 (30초)

**승격 절차:**
```
신규 어댑터 학습 완료
  ↓
brain_infer() 검증 테스트 3케이스 자동 실행
  ↓
전부 통과 → brain-stable 갱신 + brain-latest 업데이트
  ↓
실패 시 → 해당 버전 격리, 이전 stable 유지
```

### 10-3. 헌법/법률 — 외부 규칙으로 고정 (모델 파라미터 비박제)

> **핵심 원칙: law/*.md는 모델 안에 학습시키지 않는다. 항상 외부 MCP에서 읽는다.**

```
이유:
  - 모델 파라미터에 박제하면 헌법 개정 시 재학습 필요 (비용, 시간)
  - 외부 규칙으로 분리하면 헌법 수정 즉시 반영
  - 박씨 명시 OK로 헌법 바꾸면 → MCP 파일 수정만으로 brain 동작 변경

구현:
  brain_infer() 내부 → parksy-law MCP check_policy() 호출 (외부 규칙)
  모델은 "어떻게 말하고 판단하는가"만 학습
  "무엇이 허용/금지인가"는 외부 MCP에서 실시간 조회

금지:
  ❌ law/*.md 내용을 학습 JSONL에 직접 포함
  ❌ "헌법 제X조는 ~~~" 형태로 모델 파라미터에 기억시키기
  ✅ brain_infer() → check_policy() → 외부 법률 조회 후 판단
```

---

## 11. parksy-logs 레포 연동 — 데이터 창고 본체 확정

> **박씨캡처 APK + 이 프로젝트(parksy-brain)가 parksy-logs에서 가장 중요해졌다.**

```
parksy-logs/ (데이터 먹이 창고 본체)
├── 00_TRUTH/                    ← 변하지 않는 사실 기록
├── raw/                         ← 박씨캡처 APK 원본 수신구 ★★★
├── finetune/                    ← 정제된 DPO 학습 데이터
│   ├── parksy_v3_300.jsonl      ← 기존 발화 예시
│   └── brain_dpo_*.jsonl        ← 신규 chosen/rejected 쌍
├── brain_delta/                 ← 증분 학습 큐 ★★★
│   ├── delta_*.jsonl
│   └── manifest.json
├── brain_models/                ← 학습된 LoRA 어댑터 보관
│   └── brain-v*.safetensors
├── stock/                       ← STOCK 축 (git 요약, 헌법 스냅샷)
│   ├── git_summary_28repos.jsonl
│   └── law_snapshot_*.md
├── schemas/                     ← 이미 있음 (capture-event.schema.json)
│   └── brain_delta.schema.json  ← 추가 예정
└── docs/plan/
    └── PARKSY-BRAIN-CUMULATIVE-LLM-PLAN-20260605.md  ← 이 파일 미러
```

**박씨캡처 APK가 이 레포에서 가장 중요한 이유:**
- 대화 로그 = 박씨를 복제하는 핵심 신호
- 코드/git은 결과만 보여주지만, 대화는 판단 흐름을 보여줌
- APK가 없으면 FLOW 축 전체가 빠짐 → 말투는 복제되지 않음

---

## 12. 핵심 원칙 요약

1. **박씨캡처 APK가 핵심** — 대화 로그가 복제 핵심 신호. APK 없으면 FLOW 전체가 빠진다.
2. **FLOW + STOCK 이원화** — 손익계산서(대화/로그) + 대차대조표(git/레포) 두 축 동시에 먹인다.
3. **DPO 라벨링** — 박씨 채택(chosen) vs 퇴짜(rejected) 쌍으로 학습. 단순 언어 모델이 아니라 판단형 에이전트.
4. **롤백 항상 가능** — 어댑터 버전 누적, stable 기준점 유지, 이상 시 30초 롤백.
5. **헌법은 파라미터 밖** — law/*.md는 모델에 학습 안 함. 항상 parksy-law MCP 외부 조회.
6. **스냅샷이 아니라 누적** — 이벤트 발생마다 쌓인다. 학습은 플라이휠.
7. **Claude는 외부 기준점** — parksy-brain이 Claude를 대체하지 않는다. 역할이 다르다.
8. **비용 상한 $10/월** — 초과 시 학습 주기를 늘린다.

---

*parksy-law v5 헌법 체계 위에서 운영.*  
*박씨 명시 OK 없이 parksy-brain이 law/\*.md 수정 불가.*