AX 팁 13 — 컴팩트 요약을 이름별 기록으로 남기기

작성

  • AX 팁
  • Claude Code
  • 개발 환경 자동화
  • 컴팩트

/compact 가 만든 요약은 대화 기록 파일(.jsonl) 안에만 남아서 다음 세션이 찾아 쓰기 어렵습니다. PostCompact 훅이 그 요약을 세션 이름 기준 마크다운 파일에 회차로 이어 붙이고, 새 세션이 시작될 때 SessionStart 훅이 「이 기록이 있다」는 한 줄만 알려 주면 맥락을 잃지 않고 세션을 새로 열 수 있습니다. 이 글은 작업 폴더 신뢰 확인창을 없앤 지난 편에 이은 연재 열세 번째 편입니다.

메모를 정리하는 개발자 남성 모습 사진 AI 생성 이미지

왜 컴팩트하면 맥락이 사라진 것처럼 느껴졌을까?

컨텍스트 창이 차서 /compact 를 누르면 대화는 요약 한 덩어리로 줄어듭니다. 그 요약은 화면에서만 보이고, 디스크에서는 세션 기록 파일의 한 줄(isCompactSummary 표시가 붙은 항목)로만 남습니다.

그래서 세션을 닫고 다음 날 다른 세션을 열면 「어제 무슨 결정을 했더라」를 찾을 곳이 없었습니다. 오래 열어 둔 세션을 닫지 못하고 끌고 가는 습관도 여기서 나왔습니다.

요약은 어디서 어떻게 꺼낼까?

훅은 세션 기록 파일을 한 줄씩 읽으면서 두 가지를 모읍니다. 컴팩트 요약 항목 전부, 그리고 /rename 으로 붙인 세션 이름입니다. 마지막 요약 하나만 보지 않는 데에는 이유가 있습니다. 훅이 정확히 언제 발화하는지 제가 확정하지 못해서, 놓친 회차가 있어도 다음 실행에서 따라잡게 했습니다.

def scan_transcript(path):
    summaries, title = [], None
    for entry in iter_entries(path):             # 세션 기록을 한 줄씩
        if entry.get("isCompactSummary"):
            summaries.append(entry)              # 마지막 하나가 아니라 전부
        if entry.get("type") == "custom-title":
            title = entry.get("title") or title  # /rename 으로 붙인 이름
    return summaries, title

저장 위치는 이름이 정합니다. 세션 이름을 [대][중][소]-업무명 꼴로 짓는 규칙이라서, 예를 들어 [블로그][개발][검색]-robots 는 sessions/블로그/개발/검색-robots.md 가 됩니다.

이미 저장한 회차는 요약마다 붙은 uuid 로 알아보고 건너뜁니다. 같은 훅이 몇 번 돌아도 결과가 같습니다. 이름에 역할 태그가 없으면 「미분류」 폴더에 쌓지 않고 저장을 멈춘 뒤 이름부터 받습니다. 요약은 세션 기록에 그대로 있으므로 이름을 붙인 뒤 한 번 더 돌면 따라잡습니다.

컴팩트 요약이 기록으로 남기까지/compact 실행 (PostCompact 훅) → 세션 기록에서 요약 전부 찾기; 세션 기록에서 요약 전부 찾기 → 세션 이름으로 폴더·파일 정하기; 세션 이름으로 폴더·파일 정하기 → 이름이 있나?; 이름이 있나? → 새 회차만 이어 붙이기 (예); 이름이 있나? → 저장을 멈추고 이름부터 받기 (아니오); 새 회차만 이어 붙이기 → 색인 파일 다시 만들기예아니오/compact 실행(PostCompact 훅)세션 기록에서 요약전부 찾기세션 이름으로폴더·파일 정하기이름이 있나?저장을 멈추고 이름부터받기새 회차만 이어 붙이기색인 파일 다시 만들기
컴팩트 요약이 기록으로 남기까지 — 같은 훅이 여러 번 돌아도 결과는 같다

파일이 계속 커지면 어떻게 할까?

회차가 쌓이면 파일이 길어집니다. 500줄을 넘으면 최근 2회차만 본 파일에 남기고 옛 회차는 같은 이름의 .archive.md 로 옮깁니다. 지우지 않고 옮기는 것이 핵심입니다. 두 숫자는 코드에 적지 않고 정책 파일에서 읽습니다.

def rotate(target, max_lines=500, keep=2):
    body = open(target, encoding="utf-8").read()
    if body.count("\n") <= max_lines:
        return
    head, blocks = split_rounds(body)             # 회차 경계로만 자른다
    old, new = blocks[:-keep], blocks[-keep:]
    open(archive_path(target), "a", encoding="utf-8").write("".join(old))
    open(target, "w", encoding="utf-8").write(head + "".join(new))

회차를 자르는 기준은 줄 수가 아니라 회차 제목줄입니다. 요약 본문에 --- 나 ## 가 섞여 있어도 한 회차가 둘로 쪼개지지 않게 하려는 것이었습니다.

새 세션은 이 기록을 어떻게 이어받을까?

여기에서 가장 많이 고민한 것은 본문을 주입하지 않는다는 결정입니다. 매 세션 시작에 수백 줄을 넣으면 아끼려던 컨텍스트를 도로 쓰기 때문입니다.

SessionStart 훅(session-memory.py --notify)은 세션 이름이나 작업 경로가 같은 기록을 찾아, 이름·회차 수·줄 수·경로만 최대 5줄로 알립니다. 보관 파일까지 센 전체 회차 수를 보여 주므로 회전 뒤에도 회차가 줄어 보이지 않습니다. 본문이 필요하면 그때 /세션기억 으로 최근 2회차만 불러옵니다.

{
  "hooks": {
    "PostCompact": [{ "hooks": [{ "type": "command", "command": "python3 hooks/save-compact-summary.py --quiet" }] }],
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "python3 hooks/session-memory.py --notify" }] }]
  }
}

같은 저장 스크립트가 PreCompact·SessionEnd 에도 등록되어 있습니다. 알림에는 「요약은 근거가 아니니 결정은 원문에서 확인하라」는 문장을 항상 붙입니다. 요약은 모델이 다시 쓴 글이라 원문과 다를 수 있기 때문입니다.

기록이 많아져도 어떻게 찾을까?

저장할 때마다 INDEX.md 도 다시 만듭니다. 파일마다 수정 시각과 크기를 지문으로 캐시에 두어서, 바뀐 파일만 다시 읽습니다. 키워드는 최근 3회차 본문에서 티켓 번호·식별자·한글 명사구를 뽑아 TF-IDF 로 점수를 매기고 기록마다 상위 6개를 남깁니다. 「그 얘기를 어느 세션에서 했지」를 grep 한 번으로 찾는 용도입니다.

지금은 무엇이 달라졌나?

2026-11-06 에 명령으로 센 값입니다. 세션 기록 폴더에 기록 파일 134개와 보관 파일 30개가 있고, INDEX.md 는 868줄이며 키워드 항목이 555개 들어 있습니다. 저장 훅은 605줄, 알림 훅은 274줄입니다.

세션을 닫을 때기록 전: 요약이 세션 기록 파일 안에만 있음, 닫은 세션의 결정을 찾을 곳이 없음, 그래서 오래된 세션을 못 닫음 → 기록 후: 요약이 이름별 마크다운에 회차로 쌓임, 새 세션은 한 줄 알림으로 위치를 앎, 키워드 색인으로 바로 검색기록 전요약이 세션 기록 파일안에만 있음닫은 세션의 결정을찾을 곳이 없음그래서 오래된 세션을못 닫음기록 후요약이 이름별마크다운에 회차로쌓임새 세션은 한 줄알림으로 위치를 앎키워드 색인으로 바로검색
세션을 닫을 때

대가도 있습니다. 요약은 로컬 파일이라 다른 기기와 공유되지 않고, 모델이 쓴 요약이라 틀린 내용이 섞일 수 있습니다. 그래서 승인이나 결정의 근거로는 쓰지 않고 원문을 다시 확인합니다.

자주 묻는 질문

/clear 로 비운 대화도 남나요?

남깁니다. 세션이 /clear 로 끝나면 마지막 컴팩트 이후의 대화에서 사용자·assistant 텍스트만 뽑아, 별도 프로세스가 claude -p 로 요약해 「(clear)」 회차로 덧붙입니다. 사용자 입력이 2개 이상일 때만 하고, 대화가 길면 뒤쪽 60,000자까지만 씁니다.

비슷한 도구가 이미 있지 않나요?

있습니다. 공개된 compact-hooks 프로젝트는 PostCompact 훅이 요약을 last-compact-summary.md 에 시각과 함께 저장한다고 설명합니다. 저는 세션 이름별로 파일을 나누고 회차를 이어 붙이는 쪽을 택했습니다.

이름 없는 세션은 어떻게 되나요?

기록을 저장하지 않고 이름을 붙이라는 안내만 합니다. 요약은 세션 기록에 남아 있어서, 이름을 붙인 뒤 어느 훅이든 한 번 돌면 빠진 회차가 채워집니다.

사이트를 만들어볼까요?

무료 상담 받기