세션 요약

세션 내용을 증분 방식으로 요약하는 시스템입니다. (.ai-core v2.1.0 기준)

핵심 개념

summaries는 2차 원본입니다. 단순 축약이 아니라, 1차 원본(sessions/)의 노이즈를 제거하고 정제한 데이터입니다.

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

Multi-LLM 컨텍스트의 단일 소스

user-prompt-submit.sh가 외부 LLM에 주입하는 컨텍스트는 summaries/에서만 가져옵니다. 설정: session.context_for_llm.source: summaries_only

증분 요약 방식

기존 요약을 재작성하지 않고, 새 대화만 추가합니다.

설정	값	의미
mode	append_only	기존 요약 유지, 새 대화만 추가
max_new_conversations_per_batch	15	한 번에 처리하는 최대 대화 수
max_initial_conversations	30	첫 요약 생성 시 처리 대화 수

왜 append_only인가

방식	장점	단점
전체 재요약	일관성 높음	정보 손실 누적, 비용 높음
append_only	정보 손실 최소화, 비용 절감	요약 크기 증가 가능

append_only를 선택한 이유: summaries는 "2차 원본"이므로 정보 보존이 일관성보다 우선합니다. 크기 문제는 3차 가공(brief/auto 모드)에서 별도 처리합니다.

정제 규칙

대상	처리 방식
사용자 질문	문법 개선, 의도 유지
LLM 응답	문맥 파악 필수 정보 모두 포함 (파일 경로, 설정값 before/after, 결정 이유 등)
우선 보존	파일 경로, 설정값 변경, 승인/거절, 에러 해결, 신규 기능 생성

LLM 폴백 체인

요약 생성은 외부 LLM이 담당합니다. 실패 시 다음 LLM으로 자동 전환됩니다.

stop hook → run_heavy_tasks_background()
  ↓
gemini (gemini-2.5-flash)
  ↓ 실패 시
opencode (zai-coding-plan/glm-5)
  ↓ 실패 시
codex (gpt-5.4)
  ↓ 모두 실패 시
{} 빈 객체 기록

LLM	모델	타임아웃
gemini	gemini-2.5-flash	60초
opencode	zai-coding-plan/glm-5	60초
codex	gpt-5.4	60초

설정 위치: detail/session.json > summary.llm.summary_chain

폴백 체인의 실용성

gemini가 가장 빠르고 안정적이므로 1순위입니다. 3개 모두 실패하면 빈 객체를 기록하여 다음 세션에서 재시도할 수 있도록 합니다.

요약 파일 형식

{
  "session_id": "6588f90e-...",
  "compact_count": 0,
  "last_updated": "2026-04-10T10:55:00Z",
  "token_count": 850,
  "turn_count": 15,
  "summary": "[{\"ts\":\"...\",\"type\":\"user\",\"topic\":\"...\",\"content\":\"...\"},...]"
}

파일 위치: .ai-core/data/context/summaries/{session_id}.json

생성 흐름

세션 종료 (/quit)
  ↓
stop.sh [포그라운드]
  ├── Git 요약 출력
  ├── Handoff 자동 저장
  └── 백그라운드 태스크 시작
        ↓
[백그라운드] (disown, Claude 대기 없음)
  ├── Transcript 추출
  ├── 프로젝트 로그 동기화
  ├── 세션 요약 생성 (LLM 폴백 체인)
  ├── RAG 임베딩
  └── 컨텍스트 아카이브

3차 가공 (필요 시)

2차 원본이 너무 커지면 별도 로직으로 축약합니다.

모드	설명
brief	시간대별 차등 요약 (최근 20건은 상세, 이전은 간략)
auto	토큰 기반 자동 축약 (max_tokens 8000 초과 시 brief 적용)

토큰 추정

언어	추정 비율
한글 많음 (50%+)	약 2자/토큰
혼합 (20-50%)	약 3자/토큰
영어 많음	약 4자/토큰

컨텍스트 주입 설정

user-prompt-submit.sh가 summaries를 Claude에 주입할 때의 설정:

설정	값	설명
source	summaries_only	summaries만 사용
max_tokens	50000	주입 최대 토큰
strategy	bottom_up	최신 대화 우선

다음 단계

• 세션 컨텍스트 -- 데이터 계층 구조
• 재개 및 검색 -- 세션 재개