세션 컨텍스트

세션 데이터의 계층 구조와 저장 방식을 설명합니다. (.ai-core v2.1.0 기준)

데이터 계층

세션 데이터는 3계층으로 관리됩니다. 각 계층은 목적이 다릅니다.

1차 원본 (sessions/, projects/)  → 로그 원본, 노이즈 포함
2차 원본 (summaries/)            → 정제된 요약, 정보 손실 최소화
3차 가공 (필요 시)               → 토큰 기반 축약

계층	위치	생성 시점	용도
1차	data/context/sessions/	매 대화	원본 보존 (세션별 전체 대화)
1차	data/context/projects/	매 대화	프로젝트별 날짜 기반 집계
2차	data/context/summaries/	stop hook	LLM 컨텍스트 주입 (정제 파일)
-	data/context/handoffs/	stop hook / 수동	세션 인계 문서

2차 원본의 의미

summaries는 단순 요약이 아닌 정제된 2차 원본입니다. 기존 요약을 재작성하지 않고 새 대화만 증분 추가(append_only)하여 정보 손실을 최소화합니다. Multi-LLM 컨텍스트 전달의 단일 소스로 사용됩니다.

프로젝트 결정 로직

세션 로그를 어느 프로젝트 폴더에 저장할지 결정하는 우선순위입니다. session-save, session-resume, user-prompt-submit.sh 모두 동일한 순서를 따릅니다.

순위	소스	설명
1	TMUX 세션명	tmux display-message -p '#S'
2	PROJECT_FOR_LOG	make claude PROJECT=xxx로 전달
3	__default	위 두 가지 모두 없을 때 기본값

# 우선순위 예시:
# tmux 세션 "workspace--quant__how" → 프로젝트 "workspace--quant__how"
# tmux 없음, PROJECT_FOR_LOG=myapp  → 프로젝트 "myapp"
# 둘 다 없음                        → sessions/에만 기록, projects/에는 미기록

폴더 구조

.ai-core/data/context/
├── current/                 # 현재 세션 로그
│   └── log.jsonl
├── current-session.json     # 현재 활성 세션 ID
│
├── sessions/                # [1차] 세션 아카이브
│   └── {YYMMDD}_{session_id}/
│       ├── metadata.json
│       ├── log.jsonl        # user + assistant 모두 기록
│       └── transcript.jsonl
│
├── projects/                # [1차] 프로젝트별 날짜 기반 집계
│   └── {project_name}/
│       └── 2026-04-10.jsonl
│
├── summaries/               # [2차] 세션 요약 (정제 원본)
│   ├── index.json
│   ├── {session_id}.json
│   └── {session_id}.json.backup
│
├── handoffs/                # Handoff 인계 문서
│   └── {project_name}/
│       └── handoff.md       # 프로젝트당 1개 (매번 덮어쓰기)
│
├── vectors/                 # RAG 벡터 DB
│   └── collection/sessions/
│
├── subagents/               # Task 서브에이전트 로그
│   └── {YYYY-MM-DD}/
│       └── {session_id}/
│
├── tmux-sessions/           # tmux 세션별 Claude 세션 ID 매핑
│   └── {tmux_name}.json
│
├── buffer/                  # 문서화 버퍼
├── comparisons/             # 비교 분석 결과
├── check-reports/           # 체크리스트 리포트
├── questions/               # 사용자 질문 로그
└── global/                  # 전역 컨텍스트
    └── project-context.md

데이터 스키마

통일 로그 스키마

sessions/와 projects/ 모두 동일한 JSONL 스키마를 사용합니다.

{
  "ts": "2026-04-10T11:00:00Z",
  "type": "user",
  "content": "메시지 내용",
  "session_id": "3dd191b4-..."
}

필드	설명	sessions/	projects/
ts	ISO 타임스탬프	O	O
type	user / assistant	O	O
content	메시지 내용	O	O
session_id	세션 UUID	-	O

metadata.json (세션별)

{
  "session_id": "3dd191b4-...",
  "workspace_project": "quant.how",
  "branch": "feature/xxx",
  "cwd": "/home/user/multi-saas-kit",
  "created_at": "2026-04-10T11:00:00Z",
  "messages_count": 15
}

current-session.json

{
  "session_id": "3dd191b4-970f-4666-be4a-260103e7b1bf",
  "transcript_path": "/home/user/.claude/projects/.../3dd191b4-....jsonl",
  "updated_at": "2026-04-10T11:00:00+09:00"
}

Handoff vs Summary

	Handoff	Summary
생성 주체	Claude (능동적)	Hook (자동)
트리거	/-session-save 수동 / stop hook 자동	stop hook 백그라운드
내용	작업 맥락, 결정 이유, 다음 액션	로그 기반 정제 요약
충실도	~90%	~60%
용도	세션 전환, /clear 전 인계	Multi-LLM 컨텍스트

관련 명령어

Command	설명
/-session-context	컨텍스트 상태 확인
/-session-resume	세션 재개 (handoff 우선)
/-session-save	Handoff 인계 문서 생성
/-session-summary	요약 생성

다음 단계

• 재개 및 검색 -- 세션 재개 동작
• 요약 시스템 -- 증분 요약 구조