세션 컨텍스트
세션 데이터의 계층 구조와 저장 방식을 설명합니다. (.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 | 요약 생성 |